mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
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:
@@ -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);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user