fix(openclaw): accept 12-character hashes in headroom_retrieve (#4640)

<!-- maintainer-current-main -->
## Maintainer latest-main checkpoint
Published `930d7f115250cb8d0344f0be8e4fa3fc9f40faa3` incorporates
current upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948` after a
clean merge. 153 plugin tests pass, 2 Windows skips; typecheck/build
pass. Eight actual TCP/store retrieval cases again recover exact
originals through direct/OpenClaw calls and lowercase/uppercase
12/24-character keys. Contributor correctness logic was not rewritten.
Earlier qualification captures below retain their original
commit/platform scope. Hosted CI must finish on this exact head before
approval; nothing merged.
<!-- /maintainer-current-main -->

## Description

The OpenClaw `headroom_retrieve` tool rejected 12-character hashes with
"Invalid hash format. Expected 24 hex characters." before the request
could reach `GET /v1/retrieve/{hash}`. The SmartCrusher row-drop path
keys its CCR markers with a 12-char SHA-256 hex prefix, mirrored into
the compression store through `explicit_hash`, so 12-char keys are valid
retrieval keys. Every other marker consumer in the repo already accepts
both lengths; this validator was the odd one out.

Closes #4639

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)

## Changes Made

- `plugins/openclaw/src/tools/headroom-retrieve.ts`: validator now
accepts 12- or 24-character hex hashes
(`/^(?:[a-f0-9]{12}|[a-f0-9]{24})$/i`); error message and both the tool
and parameter descriptions updated to say 12 or 24.
- `plugins/openclaw/test/headroom-retrieve.test.ts`: new regression
tests — 12-char accepted (reaches fetch), uppercase 12-char accepted,
24-char still accepted, non-hex / 13-char / empty rejected without a
fetch call, and both descriptions mention both lengths.

## Testing

- [x] New tests added for new functionality
- [x] Manual testing performed

The template's pytest/ruff/mypy items are N/A here: this change is
TypeScript-only, in the OpenClaw plugin. What actually ran (fresh clone
at upstream main 31dcaf41, Node v22.23.1, plugin dir `plugins/openclaw`,
`npm ci`):

### Test Output

```text
$ npx vitest run
 Test Files  10 passed (10)
      Tests  150 passed (150)

$ npm run typecheck
(no output — clean)
```

Before the fix, the issue's repro form showed a 12-char hash refused
locally (`{"error":"Invalid hash format. Expected 24 hex characters."}`,
fetch not called) while a 24-char hash reached the stub backend. After
the fix, both lengths reach the stub backend. The new test file fails
6/7 on the unpatched validator and passes 7/7 after; the one test that
passes on both sides is the "24-char still accepted" guard, which exists
to prove the fix did not regress the length that already worked. Full
suite went from 9 files / 143 tests to 10 files / 150 tests.

## Real Behavior Proof

- Environment: fresh clone of headroomlabs-ai/headroom at main 31dcaf41,
Node v22.23.1, npm 11.20.0, vitest, plugin dir `plugins/openclaw`.
- Exact command / steps: `npm ci`, then `npx vitest run` (full plugin
suite) and `npm run typecheck`; plus the issue's repro form (stubbed
fetch, call `headroom_retrieve` with a 12-char hash, observe whether a
request goes out) run before and after the patch.
- Observed result: 12-char hash now produces `GET
/v1/retrieve/{12-char-hash}` against the stub and returns the stored
content; suite 150/150 green, typecheck clean.
- Not tested: no live Headroom proxy (fetch stubbed throughout, so no
real round trip against a running Headroom); no Python or Rust suites
(change is TypeScript-only); no `npm run build`; no in-OpenClaw agent
session; other plugins were not checked for a copy of the same
validator.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: N/A
- Stable/default behavior changed: yes, intentionally — 12-character
hashes are now accepted instead of rejected; 24-character behavior is
unchanged, and all other lengths and non-hex input are still rejected.
- Kill switch / disable path: none needed; revert the commit to restore
the old behavior.
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit.

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

## Screenshots (if applicable)

N/A — no UI change.

## Additional Notes

One honest caveat on the tests: the "24-char still accepted" test passes
before and after by design (it guards against regression, so it cannot
fail on the unpatched code). The file as a whole fails before the fix
and passes after, which is what the repo's bug-fix rule asks for. The
three rejection tests fail pre-fix only on the changed error string;
their accept/reject verdicts are unchanged.
<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4640"
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 -->

## Maintainer follow-up qualification
Published `9bcb14fc447abdc844b77c399691e6bbc9e208f2` includes latest
main `ddbbb07746a274da5c9bd7380a42ba2a46e7515d`, including #4641's
OpenClaw execute adapter and the tsup update. The merge is clean;
contributor normalization logic is unchanged. The previous uppercase
finding is fixed by lowercasing accepted keys before the GET request,
with URL assertions for both lengths.

Windows, Node 22.22.0, Python 3.12.13: `npm ci --no-audit --no-fund`,
`npm test`, `npm run typecheck`, `npm run build` all pass. Full plugin
suite: **153 passed, 2 skipped**, 11 test files; package and
declarations build successfully.

Actual runtime proof: start an offline/beacon-opt-out localhost TCP
Uvicorn `create_app(ProxyConfig(stateless=True, optimize=False,
cache_enabled=False, rate_limit_enabled=False, log_requests=False))`;
store a Unicode original with `get_compression_store().store(original,
"short")` and again with `explicit_hash="a1b2c3d4e5f6"`; import
`createHeadroomRetrieveTool` from the built `dist/index.js`. For each
12/24-character lowercase and uppercase key, call both
`tool.execute({hash})` and `tool.execute("call_fixture", {hash})`,
JSON-parse the response, and assert `original_content` equals the exact
original and returned `hash` equals lowercase input. **All eight real
GET round-trips succeed**. The prior uppercase 404 no longer reproduces.
Both Devin findings are addressed by the code/test follow-up and this
live proof.

Not tested: an installed OpenClaw agent session, model/provider calls,
native rebuild, non-Windows runtime. Existing development native
extension was used only for proxy startup. Hosted checks must complete
on the final published head; nothing merged.

---------

Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
This commit is contained in:
AP
2026-11-05 10:55:26 -06:00
committed by GitHub
co-authored by JerrettDavis
parent 7e827285a4
commit 8d3e9e5ca7
2 changed files with 119 additions and 5 deletions
@@ -20,14 +20,14 @@ export function createHeadroomRetrieveTool(config: RetrieveToolConfig) {
description:
"Retrieve original uncompressed content from Headroom's compression store. " +
"Use when compressed context mentions a hash and you need the full details. " +
"Pass the hash from the compression marker (24 hex characters). " +
"Pass the hash from the compression marker (12 or 24 hex characters). " +
"Retrieval is by hash and always returns the full original content.",
parameters: {
type: "object" as const,
properties: {
hash: {
type: "string",
description: "The 24-character hex hash from the compression marker",
description: "The 12- or 24-character hex hash from the compression marker",
},
},
required: ["hash"],
@@ -44,14 +44,17 @@ export function createHeadroomRetrieveTool(config: RetrieveToolConfig) {
const hash = typeof args?.hash === "string" ? args.hash : "";
// Validate hash format
if (!/^[a-f0-9]{24}$/i.test(hash)) {
if (!/^(?:[a-f0-9]{12}|[a-f0-9]{24})$/i.test(hash)) {
return JSON.stringify({
error: "Invalid hash format. Expected 24 hex characters.",
error: "Invalid hash format. Expected 12 or 24 hex characters.",
});
}
try {
const url = `${proxyOrigin}/v1/retrieve/${hash}`;
// The store keys entries by lowercase hex, so normalize once here
// instead of requiring every caller to pass a pre-lowercased hash.
const normalizedHash = hash.toLowerCase();
const url = `${proxyOrigin}/v1/retrieve/${normalizedHash}`;
const resp = await fetch(url, {
signal: AbortSignal.timeout(10_000),
@@ -0,0 +1,111 @@
/**
* Hash format accepted by the headroom_retrieve tool.
*
* The Rust SmartCrusher row-drop path keys its CCR marker with a 12-char
* SHA-256 hex prefix (`hash_canonical` in
* crates/headroom-core/src/transforms/smart_crusher/crusher.rs), mirrored into
* the compression store through `explicit_hash`, so a 12-char hash is a valid
* retrieval key just like a 24-char one.
*/
import { describe, it, expect, afterEach, vi } from "vitest";
import { createHeadroomRetrieveTool } from "../src/tools/headroom-retrieve.js";
const PROXY_URL = "http://127.0.0.1:8788";
function stubRetrieveOk() {
const mock = vi.fn().mockResolvedValue({
ok: true,
status: 200,
json: () => Promise.resolve({ original_content: "the full original text" }),
});
vi.stubGlobal("fetch", mock);
return mock;
}
function retrieve(hash: string) {
const tool = createHeadroomRetrieveTool({ proxyUrl: PROXY_URL });
return tool.execute({ hash });
}
afterEach(() => {
vi.unstubAllGlobals();
});
describe("headroom_retrieve hash validation", () => {
it("accepts a 12-character hex hash and queries the store", async () => {
const fetchMock = stubRetrieveOk();
const result = await retrieve("a1b2c3d4e5f6");
expect(fetchMock).toHaveBeenCalledTimes(1);
expect(fetchMock.mock.calls[0][0]).toBe(`${PROXY_URL}/v1/retrieve/a1b2c3d4e5f6`);
expect(JSON.parse(result)).toEqual({ original_content: "the full original text" });
});
it("queries the store with the lowercased key for an uppercase 12-character hash", async () => {
const fetchMock = stubRetrieveOk();
await retrieve("A1B2C3D4E5F6");
expect(fetchMock).toHaveBeenCalledTimes(1);
expect(fetchMock.mock.calls[0][0]).toBe(`${PROXY_URL}/v1/retrieve/a1b2c3d4e5f6`);
});
it("still accepts a 24-character hex hash", async () => {
const fetchMock = stubRetrieveOk();
const result = await retrieve("a1b2c3d4e5f6a1b2c3d4e5f6");
expect(fetchMock).toHaveBeenCalledTimes(1);
expect(fetchMock.mock.calls[0][0]).toBe(`${PROXY_URL}/v1/retrieve/a1b2c3d4e5f6a1b2c3d4e5f6`);
expect(JSON.parse(result)).toEqual({ original_content: "the full original text" });
});
it("queries the store with the lowercased key for an uppercase 24-character hash", async () => {
const fetchMock = stubRetrieveOk();
await retrieve("A1B2C3D4E5F6A1B2C3D4E5F6");
expect(fetchMock).toHaveBeenCalledTimes(1);
expect(fetchMock.mock.calls[0][0]).toBe(`${PROXY_URL}/v1/retrieve/a1b2c3d4e5f6a1b2c3d4e5f6`);
});
it("rejects a non-hex 12-character hash without querying the store", async () => {
const fetchMock = stubRetrieveOk();
const result = await retrieve("zzzzzzzzzzzz");
expect(fetchMock).not.toHaveBeenCalled();
expect(JSON.parse(result).error).toBe("Invalid hash format. Expected 12 or 24 hex characters.");
});
it("rejects a 13-character hash without querying the store", async () => {
const fetchMock = stubRetrieveOk();
const result = await retrieve("a1b2c3d4e5f67");
expect(fetchMock).not.toHaveBeenCalled();
expect(JSON.parse(result).error).toBe("Invalid hash format. Expected 12 or 24 hex characters.");
});
it("rejects an empty hash without querying the store", async () => {
const fetchMock = stubRetrieveOk();
const result = await retrieve("");
expect(fetchMock).not.toHaveBeenCalled();
expect(JSON.parse(result).error).toBe("Invalid hash format. Expected 12 or 24 hex characters.");
});
});
describe("headroom_retrieve hash documentation", () => {
it("documents both supported hash lengths", () => {
const tool = createHeadroomRetrieveTool({ proxyUrl: PROXY_URL });
const mentionsBothLengths = /\b12\b[^\n]*\b24\b/;
expect(tool.description).toMatch(mentionsBothLengths);
expect(tool.parameters.properties.hash.description).toMatch(mentionsBothLengths);
});
});