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
/**
* HeadroomContextEngine — ContextEngine implementation for OpenClaw.
*
* Compresses tool outputs and conversation context using the Headroom proxy.
* Zero LLM calls — all compression is algorithmic (SmartCrusher, ContentRouter, etc.)
*/
/* eslint-disable @typescript-eslint/no-explicit-any */
import { compress } from "headroom-ai";
import { ProxyManager, defaultLogger, type ProxyManagerConfig, type ProxyManagerLogger } from "./proxy-manager.js";
import { agentToOpenAIIndexed, normalizeAgentMessages, restoreAgentMessages } from "./convert.js";
import { DurableAdvancementKeyStore, defaultCommitLogPath } from "./advancement-key-store.js";
import {
delegateCompactionToRuntime,
type OpenClawCompactParams,
type OpenClawCompactResult,
} from "./openclaw-compaction.js";
// 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;
minContextChars?: number;
circuitBreakerThreshold?: number;
circuitBreakerCooldownMs?: number;
/** Where to durably record committed turn-advancement keys (see
* `DurableAdvancementKeyStore`; the markers live beside it in
* `markerDirFor(commitLogPath)`). Must be on a writable filesystem.
* Defaults to `defaultCommitLogPath()`. */
commitLogPath?: string;
announceCompression?: boolean;
}
export class HeadroomContextEngine {
readonly info = {
id: "headroom",
name: "Headroom Context Compression",
version: "0.1.0",
ownsCompaction: false,
transcriptSemantics: {
currentTurnFence: "before-current-turn-entry-v1",
turnAdvancementIdempotency: "atomic-idempotent-v1",
},
};
// Durable, restart-safe record of committed advancement keys, for
// commitTurn's idempotent-retry check. See advancement-key-store.ts for
// why this must survive a process restart and must not evict entries.
private advancementKeyStore: DurableAdvancementKeyStore;
private proxyManager: ProxyManager;
private proxyUrl: string | null = null;
private config: HeadroomEngineConfig;
private logger: ProxyManagerLogger;
private proxyReadyListeners = new Set<(proxyUrl: string) => void | Promise<void>>();
private proxyStartupPromise: Promise<string> | null = null;
private proxyStartupError: unknown = null;
private stats = {
totalCompressions: 0,
totalTokensSaved: 0,
totalTokensBefore: 0,
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;
this.logger = logger ?? defaultLogger;
this.proxyManager = new ProxyManager(config, this.logger);
this.advancementKeyStore = new DurableAdvancementKeyStore(
config.commitLogPath ?? defaultCommitLogPath(),
);
}
// === ContextEngine Lifecycle ===
async bootstrap(params: {
sessionId: string;
sessionKey?: string;
sessionFile: string;
}): Promise<{ bootstrapped: boolean; reason?: string }> {
if (this.config.enabled === false) {
return { bootstrapped: false, reason: "disabled" };
}
this.ensureProxyStarted();
return { bootstrapped: true, reason: "proxy startup scheduled" };
}
async ingest(params: {
sessionId: string;
message: any;
isHeartbeat?: boolean;
}): Promise<{ ingested: boolean }> {
// No-op: OpenClaw's runtime stores messages. We don't need a separate store.
return { ingested: true };
}
async ingestBatch?(params: {
sessionId: string;
messages: any[];
isHeartbeat?: boolean;
}): Promise<{ ingestedCount: number }> {
return { ingestedCount: params.messages.length };
}
/**
* Assemble context for the model — THE CORE HOOK.
*
* Converts AgentMessage[] → OpenAI format → compress() → AgentMessage[]. Only messages the proxy
* actually changed are rebuilt; the rest are returned exactly as OpenClaw passed them, so the
* provider prompt cache survives up to the first compressed message (see restoreAgentMessages).
*/
async assemble(params: {
sessionId: string;
messages: any[];
tokenBudget?: number;
model?: string;
prompt?: string;
}): Promise<{
messages: any[];
estimatedTokens: number;
systemPromptAddition?: string;
}> {
if (!this.proxyUrl || this.config.enabled === false) {
this.ensureProxyStarted();
// Fallback: return messages unchanged
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,
systemPromptAddition: this.sessionCompressionNotice(params.sessionId),
};
}
try {
// Convert AgentMessage → OpenAI format
const openaiMessages = agentToOpenAIIndexed(params.messages);
const minContextChars = this.config.minContextChars ?? 800;
if (minContextChars > 0 && countContextChars(openaiMessages) < minContextChars) {
this.logger.debug("[headroom] Context below compression threshold — using original messages");
return {
messages: normalizeAgentMessages(params.messages),
estimatedTokens: 0,
systemPromptAddition: this.sessionCompressionNotice(params.sessionId),
};
}
// Compress via proxy — pass tokenBudget so RollingWindow enforces it
const result = await compress(openaiMessages, {
model: params.model ?? "claude-sonnet-4-5",
baseUrl: this.proxyUrl,
fallback: true,
tokenBudget: params.tokenBudget,
// The SDK applies this to AbortSignal.timeout(), so a timed-out call is
// cancelled instead of continuing in the background after fail-open.
timeout: this.config.requestTimeoutMs ?? 2_000,
} as any);
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),
};
}
// Convert back to AgentMessage format
const compressedAgentMessages = restoreAgentMessages(params.messages, openaiMessages, result.messages);
this.resetCircuit();
// Track stats
this.stats.totalCompressions++;
this.stats.totalTokensSaved += result.tokensSaved;
this.stats.totalTokensBefore += result.tokensBefore;
this.logger.debug(
`Assembled: ${result.tokensBefore} → ${result.tokensAfter} tokens (saved ${result.tokensSaved})`,
);
return {
messages: compressedAgentMessages,
estimatedTokens: result.tokensAfter,
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,
systemPromptAddition: this.sessionCompressionNotice(params.sessionId),
};
}
}
/** Delegate persistent compaction to OpenClaw's built-in runtime. */
async compact(params: OpenClawCompactParams): Promise<OpenClawCompactResult> {
const result = await delegateCompactionToRuntime(params);
if (result.compacted) {
this.stats.compactions++;
}
this.logger.info(
`Compaction ${result.compacted ? "completed" : "skipped"} ` +
`(budget: ${params.tokenBudget ?? "none"}, force: ${params.force ?? false})`,
);
return result;
}
/**
* Durable turn-advancement commit — required by OpenClaw's transcriptSemantics
* contract. Called only for the accepted, successful turn; failed or aborted
* turns never reach here. Must be one atomic, idempotent write keyed by
* `advancementKey`, so a host retry with the same key reports "duplicate"
* instead of re-applying the advancement — including a retry that arrives
* after this process restarted, which is why the record lives on disk (see
* `DurableAdvancementKeyStore`) rather than in memory. This engine keeps no
* turn state of its own (OpenClaw's transcript holds the accepted
* `messages`), so recording the key is the whole advancement.
*/
async commitTurn(params: { advancementKey: string; messages: any[] }): Promise<{
status: "committed" | "duplicate";
}> {
const status = await this.advancementKeyStore.tryCommit(params.advancementKey);
return { status };
}
async afterTurn?(params: {
sessionId: string;
messages: any[];
prePromptMessageCount: number;
isHeartbeat?: boolean;
}): Promise<void> {
// Optional: could log stats or trigger learning
}
async prepareSubagentSpawn?(params: {
parentSessionKey: string;
childSessionKey: string;
ttlMs?: number;
}): Promise<{ rollback: () => Promise<void> } | undefined> {
// Subagent context is compressed naturally via assemble()
return undefined;
}
async onSubagentEnded?(params: {
childSessionKey: string;
reason: string;
}): Promise<void> {
// No-op
}
async dispose(): Promise<void> {
await this.proxyManager.stop();
this.logger.info(
`Engine disposed. Stats: ${this.stats.totalCompressions} compressions, ` +
`${this.stats.totalTokensSaved} tokens saved`,
);
}
// --- Public API ---
getStats() {
return { ...this.stats };
}
getProxyUrl(): string | null {
return this.proxyUrl;
}
getProxyStartupError(): unknown {
return this.proxyStartupError;
}
private isCircuitOpen(): boolean {
const threshold = this.config.circuitBreakerThreshold ?? 3;
if (this.circuit.errors < threshold) return false;
if (Date.now() < this.circuit.openUntilMs) return true;
this.circuit = { errors: 0, openUntilMs: 0 };
return false;
}
private tripCircuit(error: unknown): void {
this.circuit.errors += 1;
const threshold = this.config.circuitBreakerThreshold ?? 3;
if (this.circuit.errors < threshold) return;
const cooldownMs = this.config.circuitBreakerCooldownMs ?? 60_000;
this.circuit.openUntilMs = Date.now() + cooldownMs;
this.logger.warn(
`[headroom] Circuit breaker opened after ${this.circuit.errors} errors ` +
`(last: ${String(error)}); bypassing compression for ${cooldownMs}ms`,
);
}
private resetCircuit(): void {
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;
}
this.proxyStartupError = null;
this.proxyStartupPromise = this.proxyManager
.start()
.then(async (proxyUrl) => {
this.proxyUrl = proxyUrl;
this.proxyStartupError = null;
await this.notifyProxyReady(proxyUrl);
this.logger.info(`Headroom proxy ready at ${proxyUrl}`);
return proxyUrl;
})
.catch((error) => {
this.proxyStartupError = error;
this.logger.warn(`Headroom proxy unavailable: ${error}`);
throw error;
})
.finally(() => {
this.proxyStartupPromise = null;
});
// Fire-and-forget lifecycle callers intentionally do not await this promise.
// Keep the promise rejectable for ensureProxyUrl(), but mark it observed so
// a missing proxy cannot become a process-level unhandled rejection.
void this.proxyStartupPromise.catch(() => {});
}
onProxyReady(listener: (proxyUrl: string) => void | Promise<void>): () => void {
this.proxyReadyListeners.add(listener);
return () => {
this.proxyReadyListeners.delete(listener);
};
}
async ensureProxyUrl(): Promise<string> {
if (this.proxyUrl) {
return this.proxyUrl;
}
this.ensureProxyStarted();
if (!this.proxyStartupPromise) {
throw new Error("Headroom proxy startup is disabled");
}
return this.proxyStartupPromise;
}
private async notifyProxyReady(proxyUrl: string): Promise<void> {
for (const listener of this.proxyReadyListeners) {
try {
await listener(proxyUrl);
} catch (error) {
this.logger.warn(`Headroom proxy ready listener failed: ${error}`);
}
}
}
}
function countContextChars(messages: ReturnType<typeof agentToOpenAIIndexed>): number {
let total = 0;
for (const message of messages) {
total += message.content?.length ?? 0;
for (const toolCall of message.tool_calls ?? []) {
total += toolCall.function?.arguments?.length ?? 0;
}
}
return total;
}