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): delegate native compaction (#2304)

Gautam Sharmaeb4da6477404
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.md
index 25e2d324b..9d7ec5d8c 100644
--- a/plugins/openclaw/README.md
+++ b/plugins/openclaw/README.md
@@ -215,8 +215,8 @@ Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored
| | lossless-claw | headroom |
|---|---|---|
-| Compaction method | LLM summarization (DAG) | Content-aware compression (zero LLM) |
-| Cost of compaction | Tokens (LLM calls) | Zero |
+| 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) |
diff --git a/plugins/openclaw/src/engine.ts b/plugins/openclaw/src/engine.ts
index 0abe0b2db..71a3836fb 100644
--- a/plugins/openclaw/src/engine.ts
+++ b/plugins/openclaw/src/engine.ts
@@ -10,6 +10,11 @@
import { compress } from "headroom-ai";
import { ProxyManager, defaultLogger, type ProxyManagerConfig, type ProxyManagerLogger } from "./proxy-manager.js";
import { agentToOpenAI, normalizeAgentMessages, openAIToAgent } from "./convert.js";
+import {
+ delegateCompactionToRuntime,
+ type OpenClawCompactParams,
+ type OpenClawCompactResult,
+} from "./openclaw-compaction.js";
/** Race a promise against a timeout and always release the timer. */
function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
@@ -34,7 +39,7 @@ export class HeadroomContextEngine {
id: "headroom",
name: "Headroom Context Compression",
version: "0.1.0",
- ownsCompaction: true,
+ ownsCompaction: false,
};
private proxyManager: ProxyManager;
@@ -169,54 +174,19 @@ export class HeadroomContextEngine {
}
}
- /**
- * Compact context — zero-cost alternative to LLM summarization.
- *
- * Calls compress() with the token budget, which triggers:
- * - SmartCrusher: aggressive JSON compression (70-90% on tool outputs)
- * - Kompress: ModernBERT text compression (40-60% on assistant text)
- * - RollingWindow: drops oldest messages if still over budget
- * - CCR: stores originals for retrieval via headroom_retrieve tool
- *
- * Zero LLM calls. All algorithmic.
- */
- async compact(params: {
- sessionId: string;
- sessionFile: string;
- tokenBudget?: number;
- force?: boolean;
- runtimeContext?: any;
- }): Promise<{
- ok: boolean;
- compacted: boolean;
- reason?: string;
- result?: {
- tokensBefore: number;
- tokensAfter?: number;
- };
- }> {
- if (!this.proxyUrl) {
- return { ok: false, compacted: false, reason: "Proxy not available" };
- }
+ /** Delegate persistent compaction to OpenClaw's built-in runtime. */
+ async compact(params: OpenClawCompactParams): Promise<OpenClawCompactResult> {
+ const result = await delegateCompactionToRuntime(params);
- // Read current messages from session file if available
- // For now, compact() works in tandem with assemble() — the next assemble()
- // call will compress with the token budget. When compact() is called
- // independently, we report success since our pipeline handles it.
- //
- // TODO: Read session file, extract messages, call compress() with tokenBudget,
- // write back compacted messages.
-
- this.stats.compactions++;
+ if (result.compacted) {
+ this.stats.compactions++;
+ }
this.logger.info(
- `Compact called (budget: ${params.tokenBudget ?? "none"}, force: ${params.force ?? false})`,
+ `Compaction ${result.compacted ? "completed" : "skipped"} ` +
+ `(budget: ${params.tokenBudget ?? "none"}, force: ${params.force ?? false})`,
);
- return {
- ok: true,
- compacted: true,
- reason: "Headroom applies SmartCrusher + Kompress + RollingWindow on next assemble()",
- };
+ return result;
}
async afterTurn?(params: {
diff --git a/plugins/openclaw/src/openclaw-compaction.ts b/plugins/openclaw/src/openclaw-compaction.ts
new file mode 100644
index 000000000..885ec8fd4
--- /dev/null
+++ b/plugins/openclaw/src/openclaw-compaction.ts
@@ -0,0 +1,50 @@
+export interface OpenClawCompactParams {
+ sessionId: string;
+ sessionKey?: string;
+ agentId?: string;
+ sessionTarget?: unknown;
+ sessionFile?: string;
+ tokenBudget?: number;
+ force?: boolean;
+ currentTokenCount?: number;
+ compactionTarget?: "budget" | "threshold";
+ customInstructions?: string;
+ runtimeSettings?: unknown;
+ runtimeContext?: unknown;
+ abortSignal?: AbortSignal;
+}
+
+export interface OpenClawCompactResult {
+ ok: boolean;
+ compacted: boolean;
+ reason?: string;
+ result?: {
+ summary?: string;
+ firstKeptEntryId?: string;
+ tokensBefore: number;
+ tokensAfter?: number;
+ details?: unknown;
+ sessionId?: string;
+ sessionTarget?: unknown;
+ sessionFile?: string;
+ };
+}
+
+const OPENCLAW_PLUGIN_SDK_CORE = "openclaw/plugin-sdk/core";
+
+/** Delegate compaction without bundling the optional OpenClaw peer dependency. */
+export async function delegateCompactionToRuntime(
+ params: OpenClawCompactParams,
+): Promise<OpenClawCompactResult> {
+ const pluginSdk = (await import(OPENCLAW_PLUGIN_SDK_CORE)) as {
+ delegateCompactionToRuntime?: (
+ compactParams: OpenClawCompactParams,
+ ) => Promise<OpenClawCompactResult>;
+ };
+
+ if (!pluginSdk.delegateCompactionToRuntime) {
+ throw new Error("OpenClaw runtime does not expose delegateCompactionToRuntime");
+ }
+
+ return pluginSdk.delegateCompactionToRuntime(params);
+}
diff --git a/plugins/openclaw/test/engine.test.ts b/plugins/openclaw/test/engine.test.ts
index 6ef7792b5..d9886f707 100644
--- a/plugins/openclaw/test/engine.test.ts
+++ b/plugins/openclaw/test/engine.test.ts
@@ -1,6 +1,8 @@
import { afterEach, describe, expect, it, vi } from "vitest";
const mocked = vi.hoisted(() => ({
+ compress: vi.fn(),
+ delegateCompactionToRuntime: vi.fn(),
start: vi.fn(async () => "http://127.0.0.1:8787"),
stop: vi.fn(async () => undefined),
logger: {
@@ -12,7 +14,11 @@ const mocked = vi.hoisted(() => ({
}));
vi.mock("headroom-ai", () => ({
- compress: vi.fn(),
+ compress: mocked.compress,
+}));
+
+vi.mock("../src/openclaw-compaction.js", () => ({
+ delegateCompactionToRuntime: mocked.delegateCompactionToRuntime,
}));
vi.mock("../src/proxy-manager.js", () => ({
@@ -27,7 +33,8 @@ import { HeadroomContextEngine } from "../src/engine.js";
import { compress } from "headroom-ai";
afterEach(() => {
- vi.mocked(compress).mockReset();
+ mocked.compress.mockReset();
+ mocked.delegateCompactionToRuntime.mockReset();
mocked.start.mockReset();
mocked.start.mockResolvedValue("http://127.0.0.1:8787");
mocked.stop.mockClear();
@@ -37,6 +44,73 @@ afterEach(() => {
mocked.logger.warn.mockClear();
});
+describe("HeadroomContextEngine compaction", () => {
+ it("delegates persistent compaction to OpenClaw without claiming ownership", async () => {
+ const engine = new HeadroomContextEngine();
+ const params = {
+ sessionId: "session-1",
+ sessionKey: "agent:main:session-1",
+ tokenBudget: 12_000,
+ force: true,
+ runtimeContext: { workspaceDir: "/tmp/workspace" },
+ };
+ const delegatedResult = {
+ ok: true,
+ compacted: true,
+ result: {
+ tokensBefore: 20_000,
+ tokensAfter: 8_000,
+ },
+ };
+ mocked.delegateCompactionToRuntime.mockResolvedValueOnce(delegatedResult);
+
+ expect(engine.info.ownsCompaction).toBe(false);
+ await expect(engine.compact(params)).resolves.toEqual(delegatedResult);
+
+ expect(mocked.delegateCompactionToRuntime).toHaveBeenCalledWith(params);
+ expect(mocked.compress).not.toHaveBeenCalled();
+ expect(engine.getStats().compactions).toBe(1);
+ });
+
+ it("does not count a delegated no-op as a compaction", async () => {
+ const engine = new HeadroomContextEngine();
+ mocked.delegateCompactionToRuntime.mockResolvedValueOnce({
+ ok: true,
+ compacted: false,
+ reason: "Below compaction threshold",
+ });
+
+ await expect(
+ engine.compact({
+ sessionId: "session-1",
+ sessionKey: "agent:main:session-1",
+ }),
+ ).resolves.toEqual({
+ ok: true,
+ compacted: false,
+ reason: "Below compaction threshold",
+ });
+
+ expect(engine.getStats().compactions).toBe(0);
+ });
+
+ it("propagates delegated compaction failures without reporting success", async () => {
+ const engine = new HeadroomContextEngine();
+ const failure = new Error("native compaction failed");
+ mocked.delegateCompactionToRuntime.mockRejectedValueOnce(failure);
+
+ await expect(
+ engine.compact({
+ sessionId: "session-1",
+ sessionKey: "agent:main:session-1",
+ }),
+ ).rejects.toBe(failure);
+
+ expect(engine.getStats().compactions).toBe(0);
+ expect(mocked.logger.info).not.toHaveBeenCalled();
+ });
+});
+
describe("HeadroomContextEngine proxy startup helpers", () => {
it("bootstraps by scheduling proxy startup when enabled", async () => {
const engine = new HeadroomContextEngine();