TypeScript compress() Function — Full API Reference

The compress() function is the primary entry point for reducing message context in any TypeScript or JavaScript application. It accepts a message array in any supported format — OpenAI, Anthropic, Vercel AI SDK, or Google Gemini — auto-detects the format, routes through the Headroom proxy for compression, and returns compressed messages in the same format as the input.

import { compress } from "headroom-ai";

compress() requires a running Headroom proxy. Start one with headroom proxy (default port 8787) or headroom wrap <tool>. The baseUrl option defaults to http://localhost:8787 and can be overridden via HEADROOM_BASE_URL.

Signature

async function compress(
  messages: any[],
  options?: CompressOptions,
): Promise<CompressResult>

Parameters

messages

any[]

required

The message array to compress. Accepts OpenAI (role/content objects), Anthropic (role/content), Vercel AI SDK, or Google Gemini format. Format is detected automatically via detectFormat().

options

CompressOptions

Optional configuration for the compression call. All fields are optional.

Show CompressOptions fields

model

string

The model name used for token counting and context-window budgeting (e.g. "gpt-4o", "claude-opus-4-5"). Defaults to "gpt-4o".

baseUrl

string

URL of the Headroom proxy. Defaults to HEADROOM_BASE_URL env var or http://localhost:8787.

apiKey

string

Bearer token sent as Authorization: Bearer <key>. Reads HEADROOM_API_KEY env var when unset.

timeout

number

Request timeout in milliseconds. Defaults to 30000 (30 s).

fallback

boolean

When true (default), returns the original uncompressed messages on proxy failure instead of throwing. Set to false to propagate errors.

retries

number

Number of additional retry attempts on recoverable errors (5xx, connection failures). Defaults to 1.

tokenBudget

number

Target token count. When set, the proxy compresses aggressively until the message array fits within this budget.

hooks

CompressionHooks

Optional lifecycle hooks for pre/post processing and importance score biasing. See the Hooks section below.

client

HeadroomClientInterface

Supply a pre-configured HeadroomClient instance instead of constructing one from the other options. Useful for sharing a single client across many compress() calls.

stack

string

Integration slug sent as X-Headroom-Stack on every request (e.g. "adapter_ts_openai").

Return value — `CompressResult`

messages

any[]

Compressed messages in the same format as the input (OpenAI, Anthropic, Vercel AI SDK, or Gemini).

tokensBefore

number

Token count of the original uncompressed message array.

tokensAfter

number

Token count after compression.

tokensSaved

number

Absolute tokens saved: tokensBefore - tokensAfter.

compressionRatio

number

Ratio of compressed to original size (tokensAfter / tokensBefore). A value of 0.3 means 70 % reduction.

transformsApplied

string[]

Names of the compression transforms that ran (e.g. ["SmartCrusher", "ToolCrusher", "CCR"]).

ccrHashes

string[]

CCR (Compress-Cache-Retrieve) content hashes for any content archived in the retrieval store. The agent can call headroom_retrieve with these hashes.

compressed

boolean

true when at least one transform reduced the context. false on a passthrough (e.g. fallback mode, or messages already within budget).

Usage examples

import OpenAI from "openai";
import { compress } from "headroom-ai";

const client = new OpenAI();

const messages = [
  { role: "user", content: "Summarize this long document..." },
  // ... hundreds more turns
];

const { messages: compressed, tokensSaved } = await compress(messages, {
  model: "gpt-4o",
});

console.log(`Saved ${tokensSaved} tokens`);

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: compressed,
});

Error handling

When fallback: false is set, compress() surfaces the full error hierarchy. Import error classes directly:

import {
  HeadroomError,
  HeadroomConnectionError,
  HeadroomAuthError,
  HeadroomCompressError,
  ConfigurationError,
} from "headroom-ai";

try {
  const result = await compress(messages, { fallback: false });
} catch (err) {
  if (err instanceof HeadroomConnectionError) {
    // Proxy is not running or unreachable
  } else if (err instanceof HeadroomAuthError) {
    // HEADROOM_API_KEY missing or invalid (HTTP 401)
  } else if (err instanceof HeadroomCompressError) {
    // Proxy returned an error response
    console.error(err.statusCode, err.errorType, err.message);
  } else if (err instanceof ConfigurationError) {
    // Bad configuration passed to the proxy
  }
}

Class	Trigger
`HeadroomConnectionError`	Proxy is unreachable (ECONNREFUSED, timeout)
`HeadroomAuthError`	HTTP 401 — missing or invalid API key
`HeadroomCompressError`	HTTP 4xx/5xx from the proxy; carries `statusCode` and `errorType`
`ConfigurationError`	Invalid configuration sent to the proxy
`ProviderError`	Upstream LLM provider returned an error
`StorageError`	CCR storage failure
`TokenizationError`	Token-count calculation failed
`CacheError`	Semantic cache failure
`ValidationError`	Request failed schema validation
`TransformError`	A specific compression transform failed

Compression hooks

Pass a CompressionHooks instance to intercept the compression lifecycle:

import { compress, CompressionHooks } from "headroom-ai";

const hooks = new CompressionHooks({
  async preCompress(messages, ctx) {
    console.log(`Turn ${ctx.turnNumber}, query: ${ctx.userQuery}`);
    return messages; // optionally transform before compression
  },
  async computeBiases(messages, ctx) {
    // Return token-index → importance-score biases
    return {};
  },
  async postCompress(event) {
    console.log(`Saved ${event.tokensSaved} tokens via ${event.transformsApplied}`);
  },
});

const result = await compress(messages, { hooks });

Python SDK

TypeScript SDK

CLI Reference

Proxy HTTP API

TypeScript compress() Function — Full API Reference

Signature

Parameters

Return value — `CompressResult`

Usage examples

Error handling

Compression hooks

Build docs developers (and LLMs) love

Python SDK

TypeScript SDK

CLI Reference

Proxy HTTP API

Documentation Index

​Signature

​Parameters

​Return value — CompressResult

​Usage examples

​Error handling

​Compression hooks

Build docs developers (and LLMs) love

Signature

Parameters

Return value — `CompressResult`

Usage examples

Error handling

Compression hooks