Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

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

AP8d3e9e5ca7cd
diff --git a/plugins/openclaw/src/tools/headroom-retrieve.ts b/plugins/openclaw/src/tools/headroom-retrieve.ts
index 1ccbd483d..310a5e1e8 100644
--- a/plugins/openclaw/src/tools/headroom-retrieve.ts
+++ b/plugins/openclaw/src/tools/headroom-retrieve.ts
@@ -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),
diff --git a/plugins/openclaw/test/headroom-retrieve.test.ts b/plugins/openclaw/test/headroom-retrieve.test.ts
new file mode 100644
index 000000000..e612d9a18
--- /dev/null
+++ b/plugins/openclaw/test/headroom-retrieve.test.ts
@@ -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);
+ });
+});