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.

14.2 KB
Raw Blame
/**
 * 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;
}