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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(openclaw): delegate native compaction (#2304)
Gautam Sharmaeb4da6477404
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.mdindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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();