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(plugins/openclaw): keep compression system-prompt notice cache-stable (#3811)
slxng1758f8851878a4fe
diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.mdindex 9d7ec5d8c..4bbd333d6 100644--- a/plugins/openclaw/README.md+++ b/plugins/openclaw/README.md@@ -210,6 +210,7 @@ Compression is lossless via CCR (Compress-Cache-Retrieve): originals are stored| `circuitBreakerCooldownMs` | `60000` | How long (ms) the circuit breaker stays open after the threshold is reached. After the cool-down the breaker resets automatically and the next request re-probes the proxy via `/health`. || `routeCodexViaProxy` | `true` | Rewrite OpenClaw's built-in `openai-codex` provider to use the active Headroom proxy in memory so upstream Codex requests pass through Headroom. || `gatewayProviderIds` | `[]` | Optional explicit list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases `codex`, `claude`, `copilot`, and `gemini` are also accepted. When set, this overrides the default `openai-codex` routing list. |+| `announceCompression` | `true` | Adds a static, cache-stable notice to the system prompt the first time a session compresses more than 100 tokens, then keeps it unchanged for the rest of the session. Set to `false` to guarantee Headroom never modifies the system prompt. |## Comparison with lossless-clawdiff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.jsonindex d482384ae..a60bac685 100644--- a/plugins/openclaw/openclaw.plugin.json+++ b/plugins/openclaw/openclaw.plugin.json@@ -41,6 +41,10 @@"gatewayProviderIds": {"label": "Gateway Provider IDs","help": "Optional list of OpenClaw provider ids to route through the active Headroom proxy in memory. Friendly aliases codex, claude, copilot, and gemini are also accepted. When set, this overrides the default openai-codex-only routing."+ },+ "announceCompression": {+ "label": "Announce Compression In System Prompt",+ "help": "When enabled, a static, cache-stable notice is added to the system prompt the first time a session compresses more than 100 tokens. Disable to guarantee the plugin never modifies the system prompt."}},"configSchema": {@@ -106,6 +110,10 @@"type": "string"},"default": []+ },+ "announceCompression": {+ "type": "boolean",+ "default": true}}},diff --git a/plugins/openclaw/src/engine.ts b/plugins/openclaw/src/engine.tsindex 4b1ac1f7a..1d7f9304d 100644--- a/plugins/openclaw/src/engine.ts+++ b/plugins/openclaw/src/engine.ts@@ -28,6 +28,10 @@ function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {});}+// Must stay static — OpenClaw prepends it to the cached system prompt.+const HEADROOM_COMPRESSION_NOTICE =+ "[Headroom is compressing tool outputs in this session. Use headroom_retrieve if you need the original, uncompressed content.]";+export interface HeadroomEngineConfig extends ProxyManagerConfig {enabled?: boolean;requestTimeoutMs?: number;@@ -36,6 +40,7 @@ export interface HeadroomEngineConfig extends ProxyManagerConfig {/** Where to durably record committed turn-advancement keys (see* `DurableAdvancementKeyStore`). Defaults to `defaultCommitLogPath()`. */commitLogPath?: string;+ announceCompression?: boolean;}export class HeadroomContextEngine {@@ -69,6 +74,10 @@ export class HeadroomContextEngine {compactions: 0,};private circuit = { errors: 0, openUntilMs: 0 };+ // Sessions shown the compression notice. Bounded via insertion-order+ // eviction — no session lifecycle callback exists here to bound it otherwise.+ private announcedSessions = new Set<string>();+ private static readonly MAX_ANNOUNCED_SESSIONS = 1000;constructor(config: HeadroomEngineConfig = {}, logger?: ProxyManagerLogger) {this.config = config;@@ -132,12 +141,20 @@ export class HeadroomContextEngine {if (!this.proxyUrl || this.config.enabled === false) {this.ensureProxyStarted();// Fallback: return messages unchanged- return { messages: normalizeAgentMessages(params.messages), estimatedTokens: 0 };+ return {+ messages: normalizeAgentMessages(params.messages),+ estimatedTokens: 0,+ systemPromptAddition: this.sessionCompressionNotice(params.sessionId),+ };}if (this.isCircuitOpen()) {this.logger.warn("[headroom] Circuit open — using uncompressed messages");- return { messages: normalizeAgentMessages(params.messages), estimatedTokens: 0 };+ return {+ messages: normalizeAgentMessages(params.messages),+ estimatedTokens: 0,+ systemPromptAddition: this.sessionCompressionNotice(params.sessionId),+ };}try {@@ -155,11 +172,19 @@ export class HeadroomContextEngine {this.config.requestTimeoutMs ?? 30_000,);+ const shouldAnnounceCompression =+ (this.hasAnnouncedCompression(params.sessionId) || result.tokensSaved > 100) &&+ this.config.announceCompression !== false;+ if (shouldAnnounceCompression) {+ this.markCompressionAnnounced(params.sessionId);+ }+if (!result.compressed || result.tokensSaved === 0) {this.resetCircuit();return {messages: normalizeAgentMessages(params.messages),estimatedTokens: result.tokensBefore,+ systemPromptAddition: this.sessionCompressionNotice(params.sessionId),};}@@ -179,16 +204,17 @@ export class HeadroomContextEngine {return {messages: compressedAgentMessages,estimatedTokens: result.tokensAfter,- systemPromptAddition:- result.tokensSaved > 100- ? `[Context compressed by Headroom: ${result.tokensSaved} tokens saved. Use headroom_retrieve with the hash to get full details.]`- : undefined,+ systemPromptAddition: this.sessionCompressionNotice(params.sessionId),};} catch (error) {this.logger.error(`Assemble failed: ${error}`);this.tripCircuit(error);// Graceful fallback: return original messages- return { messages: normalizeAgentMessages(params.messages), estimatedTokens: 0 };+ return {+ messages: normalizeAgentMessages(params.messages),+ estimatedTokens: 0,+ systemPromptAddition: this.sessionCompressionNotice(params.sessionId),+ };}}@@ -295,6 +321,26 @@ export class HeadroomContextEngine {this.circuit = { errors: 0, openUntilMs: 0 };}+ private hasAnnouncedCompression(sessionId: string): boolean {+ return this.announcedSessions.has(sessionId);+ }++ private markCompressionAnnounced(sessionId: string): void {+ if (this.announcedSessions.has(sessionId)) return;+ if (this.announcedSessions.size >= HeadroomContextEngine.MAX_ANNOUNCED_SESSIONS) {+ const oldest = this.announcedSessions.values().next().value;+ if (oldest !== undefined) this.announcedSessions.delete(oldest);+ }+ this.announcedSessions.add(sessionId);+ }++ /** The sticky notice if this session already earned it and announcements aren't opted out. */+ private sessionCompressionNotice(sessionId: string): string | undefined {+ return this.hasAnnouncedCompression(sessionId) && this.config.announceCompression !== false+ ? HEADROOM_COMPRESSION_NOTICE+ : undefined;+ }+ensureProxyStarted(): void {if (this.config.enabled === false || this.proxyUrl || this.proxyStartupPromise) {return;diff --git a/plugins/openclaw/test/engine.test.ts b/plugins/openclaw/test/engine.test.tsindex 786717727..33f14f3a3 100644--- a/plugins/openclaw/test/engine.test.ts+++ b/plugins/openclaw/test/engine.test.ts@@ -33,7 +33,7 @@ vi.mock("../src/proxy-manager.js", () => ({defaultLogger: mocked.logger,}));-import { HeadroomContextEngine } from "../src/engine.js";+import { HeadroomContextEngine, type HeadroomEngineConfig } from "../src/engine.js";import { compress } from "headroom-ai";afterEach(() => {@@ -428,3 +428,207 @@ describe("HeadroomContextEngine transcriptSemantics contract", () => {expect(entries["turn-1"].messages).toEqual(messages);});});++describe("HeadroomContextEngine assemble() compression notice", () => {+ const HEADROOM_COMPRESSION_NOTICE =+ "[Headroom is compressing tool outputs in this session. Use headroom_retrieve if you need the original, uncompressed content.]";+ const messages = [{ role: "user", content: "hello" }];++ function mockCompressResult(overrides: Partial<{+ compressed: boolean;+ tokensSaved: number;+ tokensBefore: number;+ tokensAfter: number;+ }>) {+ const tokensSaved = overrides.tokensSaved ?? 0;+ return {+ compressed: overrides.compressed ?? tokensSaved > 0,+ messages: [{ role: "user", content: "hello" }],+ tokensBefore: overrides.tokensBefore ?? 1000,+ tokensAfter: overrides.tokensAfter ?? 1000 - tokensSaved,+ tokensSaved,+ };+ }++ function readyEngine(config?: HeadroomEngineConfig) {+ const engine = new HeadroomContextEngine(config);+ (engine as unknown as { proxyUrl: string | null }).proxyUrl = "http://127.0.0.1:8787";+ return engine;+ }++ it("returns the static notice, with no interpolated count, once tokensSaved crosses the threshold", async () => {+ vi.mocked(compress).mockResolvedValueOnce(mockCompressResult({ tokensSaved: 150 }));++ const engine = readyEngine();+ const result = await engine.assemble({ sessionId: "s1", messages });++ expect(result.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ });++ it("returns byte-identical notices across turns with different tokensSaved amounts", async () => {+ vi.mocked(compress)+ .mockResolvedValueOnce(mockCompressResult({ tokensSaved: 150 }))+ .mockResolvedValueOnce(mockCompressResult({ tokensSaved: 9000 }));++ const engine = readyEngine();+ const first = await engine.assemble({ sessionId: "s1", messages });+ const second = await engine.assemble({ sessionId: "s1", messages });++ expect(first.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ expect(second.systemPromptAddition).toBe(first.systemPromptAddition);+ });++ it("keeps the notice present on a later turn that has nothing to compress", async () => {+ vi.mocked(compress)+ .mockResolvedValueOnce(mockCompressResult({ tokensSaved: 150 }))+ .mockResolvedValueOnce(mockCompressResult({ compressed: false, tokensSaved: 0 }));++ const engine = readyEngine();+ const first = await engine.assemble({ sessionId: "s1", messages });+ const second = await engine.assemble({ sessionId: "s1", messages });++ expect(first.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ expect(second.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ });++ it("never returns a notice when announceCompression is false", async () => {+ vi.mocked(compress).mockResolvedValueOnce(mockCompressResult({ tokensSaved: 500 }));++ const engine = readyEngine({ announceCompression: false });+ const result = await engine.assemble({ sessionId: "s1", messages });++ expect(result.systemPromptAddition).toBeUndefined();+ });++ it("does not announce for compression below the noise threshold", async () => {+ vi.mocked(compress).mockResolvedValueOnce(mockCompressResult({ tokensSaved: 50 }));++ const engine = readyEngine();+ const result = await engine.assemble({ sessionId: "s1", messages });++ expect(result.systemPromptAddition).toBeUndefined();+ });++ it("does not leak a session's announcement to a different session on the same engine", async () => {+ vi.mocked(compress)+ .mockResolvedValueOnce(mockCompressResult({ tokensSaved: 150 }))+ .mockResolvedValueOnce(mockCompressResult({ compressed: false, tokensSaved: 0 }));++ const engine = readyEngine();+ const sessionA = await engine.assemble({ sessionId: "a", messages });+ const sessionB = await engine.assemble({ sessionId: "b", messages });++ expect(sessionA.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ expect(sessionB.systemPromptAddition).toBeUndefined();+ });++ it("keeps announcing for the session that earned the notice even after another session is seen", async () => {+ vi.mocked(compress)+ .mockResolvedValueOnce(mockCompressResult({ tokensSaved: 150 }))+ .mockResolvedValueOnce(mockCompressResult({ compressed: false, tokensSaved: 0 }))+ .mockResolvedValueOnce(mockCompressResult({ compressed: false, tokensSaved: 0 }));++ const engine = readyEngine();+ await engine.assemble({ sessionId: "a", messages });+ await engine.assemble({ sessionId: "b", messages });+ const sessionAAgain = await engine.assemble({ sessionId: "a", messages });++ expect(sessionAAgain.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ });++ it("evicts the oldest tracked session once the announced-session bound is exceeded", async () => {+ vi.mocked(compress).mockResolvedValue(mockCompressResult({ tokensSaved: 150 }));++ const engine = readyEngine();+ for (let i = 0; i < 1000; i++) {+ await engine.assemble({ sessionId: `session-${i}`, messages });+ }+ const overflow = await engine.assemble({ sessionId: "session-overflow", messages });++ vi.mocked(compress).mockResolvedValueOnce(mockCompressResult({ compressed: false, tokensSaved: 0 }));+ const oldest = await engine.assemble({ sessionId: "session-0", messages });+ vi.mocked(compress).mockResolvedValueOnce(mockCompressResult({ compressed: false, tokensSaved: 0 }));+ const newest = await engine.assemble({ sessionId: "session-overflow", messages });++ expect(overflow.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ expect(oldest.systemPromptAddition).toBeUndefined();+ expect(newest.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ });++ it("keeps the earned notice byte-identical through a timeout, a circuit-open turn, and recovery", async () => {+ vi.useFakeTimers();+ try {+ const requestTimeoutMs = 5_000;+ const circuitBreakerCooldownMs = 10_000;+ const engine = readyEngine({+ requestTimeoutMs,+ circuitBreakerThreshold: 1,+ circuitBreakerCooldownMs,+ });++ vi.mocked(compress).mockResolvedValueOnce(mockCompressResult({ tokensSaved: 150 }));+ const turn1 = await engine.assemble({ sessionId: "s1", messages });+ const firstNotice = turn1.systemPromptAddition;+ expect(firstNotice).toBe(HEADROOM_COMPRESSION_NOTICE);++ vi.mocked(compress).mockImplementationOnce(() => new Promise(() => {}));+ const turn2Promise = engine.assemble({ sessionId: "s1", messages });+ await vi.advanceTimersByTimeAsync(requestTimeoutMs);+ const turn2 = await turn2Promise;+ expect(turn2.systemPromptAddition).toBe(firstNotice);++ const turn3 = await engine.assemble({ sessionId: "s1", messages });+ expect(turn3.systemPromptAddition).toBe(firstNotice);+ expect(compress).toHaveBeenCalledTimes(2);++ await vi.advanceTimersByTimeAsync(circuitBreakerCooldownMs);+ vi.mocked(compress).mockResolvedValueOnce(mockCompressResult({ compressed: false, tokensSaved: 0 }));+ const turn4 = await engine.assemble({ sessionId: "s1", messages });+ expect(turn4.systemPromptAddition).toBe(firstNotice);+ expect(turn4.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ } finally {+ vi.useRealTimers();+ }+ });++ it("preserves an earned notice when the proxy becomes unavailable", async () => {+ vi.mocked(compress).mockResolvedValueOnce(mockCompressResult({ tokensSaved: 150 }));++ const engine = readyEngine();+ const first = await engine.assemble({ sessionId: "s1", messages });+ expect(first.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);++ (engine as unknown as { proxyUrl: string | null }).proxyUrl = null;+ const second = await engine.assemble({ sessionId: "s1", messages });++ expect(second.systemPromptAddition).toBe(HEADROOM_COMPRESSION_NOTICE);+ });++ it("never surfaces a notice in any fallback path when announceCompression is false", async () => {+ vi.useFakeTimers();+ try {+ const requestTimeoutMs = 5_000;+ const engine = readyEngine({+ announceCompression: false,+ requestTimeoutMs,+ circuitBreakerThreshold: 1,+ circuitBreakerCooldownMs: 10_000,+ });++ vi.mocked(compress).mockResolvedValueOnce(mockCompressResult({ tokensSaved: 150 }));+ const turn1 = await engine.assemble({ sessionId: "s1", messages });+ expect(turn1.systemPromptAddition).toBeUndefined();++ vi.mocked(compress).mockImplementationOnce(() => new Promise(() => {}));+ const turn2Promise = engine.assemble({ sessionId: "s1", messages });+ await vi.advanceTimersByTimeAsync(requestTimeoutMs);+ const turn2 = await turn2Promise;+ expect(turn2.systemPromptAddition).toBeUndefined();++ const turn3 = await engine.assemble({ sessionId: "s1", messages });+ expect(turn3.systemPromptAddition).toBeUndefined();+ } finally {+ vi.useRealTimers();+ }+ });+});