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
import { describe, it, expect, vi, beforeEach } from "vitest";
import { compress } from "../src/compress.js";
import { HeadroomClient } from "../src/client.js";
import type { OpenAIMessage } from "../src/types.js";
const mockFetch = vi.fn();
vi.stubGlobal("fetch", mockFetch);
function okResponse(overrides = {}) {
return new Response(
JSON.stringify({
messages: [{ role: "user", content: "hello" }],
tokens_before: 100,
tokens_after: 30,
tokens_saved: 70,
compression_ratio: 0.3,
transforms_applied: ["smart_crusher"],
ccr_hashes: [],
...overrides,
}),
{ status: 200, headers: { "Content-Type": "application/json" } },
);
}
describe("compress()", () => {
beforeEach(() => {
mockFetch.mockReset();
});
it("compresses messages and returns CompressResult", async () => {
mockFetch.mockResolvedValueOnce(okResponse());
const messages: OpenAIMessage[] = [{ role: "user", content: "hello" }];
const result = await compress(messages, {
model: "gpt-4o",
baseUrl: "http://localhost:8787",
});
expect(result.compressed).toBe(true);
expect(result.tokensBefore).toBe(100);
expect(result.tokensAfter).toBe(30);
expect(result.tokensSaved).toBe(70);
});
it("passes all options through to the HTTP call", async () => {
mockFetch.mockResolvedValueOnce(okResponse());
await compress([{ role: "user", content: "hello" }], {
model: "claude-sonnet-4-5-20250929",
baseUrl: "http://custom:9999",
apiKey: "hr_mykey",
});
const [url, opts] = mockFetch.mock.calls[0];
expect(url).toBe("http://custom:9999/v1/compress");
expect(opts.headers["Authorization"]).toBe("Bearer hr_mykey");
const body = JSON.parse(opts.body);
expect(body.model).toBe("claude-sonnet-4-5-20250929");
});
it("uses provided client instance instead of creating new one", async () => {
const mockClient = {
compress: vi.fn().mockResolvedValue({
messages: [],
tokensBefore: 0,
tokensAfter: 0,
tokensSaved: 0,
compressionRatio: 1.0,
transformsApplied: [],
ccrHashes: [],
compressed: false,
}),
};
await compress([{ role: "user", content: "hello" }], {
client: mockClient,
model: "gpt-4o",
});
expect(mockClient.compress).toHaveBeenCalledOnce();
expect(mockFetch).not.toHaveBeenCalled(); // no HTTP call
});
it("handles multi-turn conversation with tool calls", async () => {
mockFetch.mockResolvedValueOnce(okResponse());
const messages: OpenAIMessage[] = [
{ role: "system", content: "You are a helpful assistant" },
{ role: "user", content: "Search for data" },
{
role: "assistant",
content: null,
tool_calls: [
{
id: "tc_1",
type: "function",
function: { name: "search", arguments: '{"q":"data"}' },
},
],
},
{
role: "tool",
content: '{"results": [1, 2, 3]}',
tool_call_id: "tc_1",
},
{ role: "user", content: "Summarize" },
];
const result = await compress(messages, {
model: "gpt-4o",
baseUrl: "http://localhost:8787",
});
expect(result.compressed).toBe(true);
// Verify all messages were sent to proxy
const body = JSON.parse(mockFetch.mock.calls[0][1].body);
expect(body.messages).toHaveLength(5);
});
it("forwards a per-call config, overriding a provided client's config", async () => {
mockFetch.mockResolvedValueOnce(okResponse());
const client = new HeadroomClient({
baseUrl: "http://localhost:8787",
config: { mode: "lossy_inline" },
});
await compress([{ role: "user", content: "hello" }], {
client,
config: { mode: "ccr", targetRatio: 0.25 },
});
const [, opts] = mockFetch.mock.calls[0];
const body = JSON.parse(opts.body);
expect(body.config.mode).toBe("ccr");
expect(body.config.target_ratio).toBe(0.25);
});
});
describe("compress() autodetects Vercel media-only conversations", () => {
beforeEach(() => {
mockFetch.mockReset();
});
it("sends binary file parts as image_url data URIs and restores Vercel file parts", async () => {
mockFetch.mockResolvedValueOnce(
okResponse({
messages: [
{
role: "user",
content: [
{ type: "text", text: "compressed" },
{ type: "image_url", image_url: { url: "data:image/png;base64,iVBORw==", part: "file" } },
],
},
],
}),
);
const result = await compress(
[
{
role: "user",
content: [
{ type: "text", text: "what is this?" },
{ type: "file", mediaType: "image/png", data: new Uint8Array([137, 80, 78, 71]) },
],
},
],
{ baseUrl: "http://localhost:8787" },
);
const body = JSON.parse(mockFetch.mock.calls[0][1].body);
expect(body.messages[0].content[1]).toEqual({
type: "image_url",
image_url: { url: "data:image/png;base64,iVBORw==", part: "file" },
});
expect(JSON.stringify(body)).not.toContain('"0":137');
expect(result.messages[0].content[1]).toEqual({ type: "file", mediaType: "image/png", data: "iVBORw==" });
});
});
describe("compress() keeps Anthropic text documents through the public path", () => {
beforeEach(() => {
mockFetch.mockReset();
});
it("posts a document-only turn as the native document block and returns it unchanged", async () => {
const doc = {
type: "document",
source: { type: "text", media_type: "text/plain", data: "Critical contract: do not delete account 123" },
title: "Contract",
citations: { enabled: true },
};
// The proxy passes non-text blocks through unchanged; echo the request's messages back.
mockFetch.mockImplementationOnce(async (_url: string, init: any) => okResponse({ messages: JSON.parse(init.body).messages }));
const result = await compress([{ role: "user", content: [doc] }], { baseUrl: "http://localhost:8787" });
// Anthropic input is not converted: the document block itself reaches the proxy.
const body = JSON.parse(mockFetch.mock.calls[0][1].body);
expect(body.messages).toEqual([{ role: "user", content: [doc] }]);
expect(result.messages).toEqual([{ role: "user", content: [doc] }]);
});
});
describe("compress() sends Anthropic-format input to the proxy natively", () => {
beforeEach(() => {
mockFetch.mockReset();
});
const anthropicTurn = [
{ role: "user", content: "search for X" },
{
role: "assistant",
content: [
{ type: "thinking", thinking: "Search first.", signature: "SIG-1" },
{ type: "tool_use", id: "toolu_1", name: "search", input: { q: "X" } },
],
},
{
role: "user",
content: [{ type: "tool_result", tool_use_id: "toolu_1", content: "a\nb\nc" }],
},
];
it("posts the Anthropic blocks as-is and returns the proxy's messages unconverted", async () => {
const returned = structuredClone(anthropicTurn);
(returned[2].content as any[])[0].content = "[3 lines]";
mockFetch.mockResolvedValueOnce(okResponse({ messages: returned }));
const result = await compress(anthropicTurn, { baseUrl: "http://localhost:8787" });
const body = JSON.parse(mockFetch.mock.calls[0][1].body);
expect(body.messages).toEqual(anthropicTurn);
expect(result.messages).toEqual(returned);
});
});
describe("compress() honors a declared input format", () => {
beforeEach(() => {
mockFetch.mockReset();
});
it("converts a text-only Vercel prompt both ways when format is declared, instead of autodetecting OpenAI", async () => {
// Nothing in this prompt distinguishes it from OpenAI, so autodetection would hand it
// to the proxy unconverted and return OpenAI shape (a string) to an AI SDK caller.
const prompt = [{ role: "user", content: [{ type: "text", text: "hi" }] }];
mockFetch.mockResolvedValueOnce(okResponse({ messages: [{ role: "user", content: "compressed" }] }));
const result = await compress(prompt, { baseUrl: "http://localhost:8787", format: "vercel" });
const body = JSON.parse(mockFetch.mock.calls[0][1].body);
expect(body.messages).toEqual([{ role: "user", content: "hi" }]);
expect(result.messages).toEqual([{ role: "user", content: [{ type: "text", text: "compressed" }] }]);
});
});
describe("compress() keeps OpenAI attachments on the autodetection path when messages carry providerOptions", () => {
beforeEach(() => {
mockFetch.mockReset();
});
it("passes an OpenAI user message with providerOptions, an image_url and a file part through unconverted", async () => {
const messages = [
{
role: "user",
providerOptions: { openai: {} },
content: [
{ type: "text", text: "Describe this" },
{ type: "image_url", image_url: { url: "https://example.com/cat.png" } },
{ type: "file", file: { file_id: "file-abc", filename: "notes.pdf" } },
],
},
];
mockFetch.mockResolvedValueOnce(okResponse({ messages }));
const result = await compress(messages, { baseUrl: "http://localhost:8787" });
const body = JSON.parse(mockFetch.mock.calls[0][1].body);
expect(body.messages).toEqual(messages);
expect(result.messages).toEqual(messages);
});
});