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.

feat(sdk): support per-call config override in compress() (#3370)

Shubham Srivastavac3e8a1ee63f8
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index dbfa71fd6..79355eeba 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -19,7 +19,7 @@ import type {
import { mapProxyError, HeadroomConnectionError, HeadroomAuthError, HeadroomCompressError } from "./errors.js";
import { deepCamelCase, deepSnakeCase } from "./utils/case.js";
import { parseSSE } from "./utils/stream.js";
-import type { HeadroomConfig, HeadroomMode } from "./types/config.js";
+import type { CompressRequestConfig, HeadroomMode } from "./types/config.js";
import type {
SimulationResult,
RequestMetrics,
@@ -191,7 +191,7 @@ class Messages {
export interface ExtendedClientOptions extends HeadroomClientOptions {
providerApiKey?: string;
defaultMode?: HeadroomMode;
- config?: HeadroomConfig;
+ config?: CompressRequestConfig;
}
export class HeadroomClient implements HeadroomClientInterface {
@@ -200,7 +200,7 @@ export class HeadroomClient implements HeadroomClientInterface {
private timeout: number;
private fallback: boolean;
private retries: number;
- private config: HeadroomConfig | undefined;
+ private config: CompressRequestConfig | undefined;
private stack: string | undefined;
/** @internal */ providerApiKey: string | undefined;
@@ -234,7 +234,7 @@ export class HeadroomClient implements HeadroomClientInterface {
async compress(
messages: OpenAIMessage[],
- options: { model?: string; tokenBudget?: number } = {},
+ options: { model?: string; tokenBudget?: number; config?: CompressRequestConfig } = {},
): Promise<CompressResult> {
const model = options.model ?? "gpt-4o";
@@ -243,7 +243,7 @@ export class HeadroomClient implements HeadroomClientInterface {
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
- return await this._doCompress(messages, model, options.tokenBudget);
+ return await this._doCompress(messages, model, options.tokenBudget, options.config);
} catch (error) {
lastError = error;
if (error instanceof HeadroomAuthError) throw error;
@@ -569,13 +569,15 @@ export class HeadroomClient implements HeadroomClientInterface {
messages: OpenAIMessage[],
model: string,
tokenBudget?: number,
+ config?: CompressRequestConfig,
): Promise<CompressResult> {
const body: Record<string, unknown> = { messages, model };
if (tokenBudget) {
body.token_budget = tokenBudget;
}
- if (this.config) {
- body.config = deepSnakeCase(this.config);
+ const mergedConfig = { ...this.config, ...config };
+ if (Object.keys(mergedConfig).length > 0) {
+ body.config = deepSnakeCase(mergedConfig);
}
const response = await this._fetch("/v1/compress", {
diff --git a/sdk/typescript/src/compress.ts b/sdk/typescript/src/compress.ts
index 935cb9e26..23bf50e05 100644
--- a/sdk/typescript/src/compress.ts
+++ b/sdk/typescript/src/compress.ts
@@ -25,6 +25,7 @@ export async function compress(
model,
tokenBudget,
hooks,
+ config,
...clientOptions
} = options;
@@ -57,7 +58,7 @@ export async function compress(
// 5. Compress via proxy
const client = providedClient ?? new HeadroomClient(clientOptions);
- const result = await client.compress(openaiMessages, { model, tokenBudget });
+ const result = await client.compress(openaiMessages, { model, tokenBudget, config });
// 6. Convert compressed messages back to original format
const outputMessages = fromOpenAI(result.messages, inputFormat);
diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.ts
index 5b74b7437..a888e4cac 100644
--- a/sdk/typescript/src/index.ts
+++ b/sdk/typescript/src/index.ts
@@ -51,6 +51,8 @@ export {
// --- Config types ---
export type {
HeadroomMode,
+ CompressMode,
+ CompressRequestConfig,
RelevanceTier,
ContentType,
BlockKind,
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index a0dc91883..aef505aad 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -4,6 +4,7 @@
*/
import type { CompressionHooks } from "./hooks.js";
+import type { CompressRequestConfig } from "./types/config.js";
// --- Message types (OpenAI chat format) ---
@@ -69,6 +70,9 @@ export interface CompressOptions {
hooks?: CompressionHooks;
/** Integration slug sent as X-Headroom-Stack (e.g. "adapter_ts_openai"). */
stack?: string;
+ /** Per-call /v1/compress config, merged over the client-level config
+ * (per-call keys override at the top level). */
+ config?: CompressRequestConfig;
}
export interface CompressResult {
@@ -103,7 +107,7 @@ export interface HeadroomClientOptions {
export interface HeadroomClientInterface {
compress(
messages: OpenAIMessage[],
- options?: { model?: string; tokenBudget?: number },
+ options?: { model?: string; tokenBudget?: number; config?: CompressRequestConfig },
): Promise<CompressResult>;
}
diff --git a/sdk/typescript/src/types/config.ts b/sdk/typescript/src/types/config.ts
index bd596d419..adee140ea 100644
--- a/sdk/typescript/src/types/config.ts
+++ b/sdk/typescript/src/types/config.ts
@@ -7,6 +7,30 @@
export type HeadroomMode = "audit" | "optimize" | "simulate";
+/** Pipeline mode accepted by POST /v1/compress. Unset = default marker-free
+ * pipeline. Any other value is rejected (400) by the proxy. */
+export type CompressMode = "ccr" | "lossy_inline" | "lossless_then_lossy";
+
+/** Config accepted by the POST /v1/compress endpoint. camelCase keys are
+ * snake_cased on the wire (e.g. targetRatio -> target_ratio). Every field is
+ * optional; only these keys are honored by the endpoint. */
+export interface CompressRequestConfig {
+ /** Compression pipeline mode (unset = default marker-free pipeline). */
+ mode?: CompressMode;
+ /** Target keep-ratio (0–1) for lossy compression. -> target_ratio */
+ targetRatio?: number;
+ /** Also compress user-role messages (default false). -> compress_user_messages */
+ compressUserMessages?: boolean;
+ /** Number of most-recent messages to protect from compression. -> protect_recent */
+ protectRecent?: number;
+ /** Protect analysis/reasoning context from compression. -> protect_analysis_context */
+ protectAnalysisContext?: boolean;
+ /** Freeze the first N messages (prefix) from compression. -> frozen_message_count */
+ frozenMessageCount?: number;
+ /** Session id for session-aware compression. -> session_id */
+ sessionId?: string;
+}
+
export type RelevanceTier = "bm25" | "embedding" | "hybrid";
export type ContentType =
diff --git a/sdk/typescript/test/client.test.ts b/sdk/typescript/test/client.test.ts
index 0f5cc48cf..b5997ca8e 100644
--- a/sdk/typescript/test/client.test.ts
+++ b/sdk/typescript/test/client.test.ts
@@ -263,4 +263,48 @@ describe("HeadroomClient", () => {
const body = JSON.parse(mockFetch.mock.calls[0][1].body);
expect(body.model).toBe("gpt-4o");
});
+
+ it("sends a per-call config (snake_cased) in the request body", async () => {
+ mockFetch.mockResolvedValueOnce(okResponse(sampleProxyResponse));
+ const client = new HeadroomClient({ baseUrl: "http://localhost:8787" });
+
+ await client.compress(sampleMessages, {
+ model: "gpt-4o",
+ config: { mode: "ccr", targetRatio: 0.3, compressUserMessages: true },
+ });
+
+ 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.3);
+ expect(body.config.compress_user_messages).toBe(true);
+ });
+
+ it("per-call config overrides client-level config", async () => {
+ mockFetch.mockResolvedValueOnce(okResponse(sampleProxyResponse));
+ const client = new HeadroomClient({
+ baseUrl: "http://localhost:8787",
+ config: { mode: "lossy_inline" },
+ });
+
+ await client.compress(sampleMessages, {
+ model: "gpt-4o",
+ config: { mode: "ccr" },
+ });
+
+ const [, opts] = mockFetch.mock.calls[0];
+ const body = JSON.parse(opts.body);
+ expect(body.config.mode).toBe("ccr");
+ });
+
+ it("omits the config key when neither client nor call sets config", async () => {
+ mockFetch.mockResolvedValueOnce(okResponse(sampleProxyResponse));
+ const client = new HeadroomClient({ baseUrl: "http://localhost:8787" });
+
+ await client.compress(sampleMessages, { model: "gpt-4o" });
+
+ const [, opts] = mockFetch.mock.calls[0];
+ const body = JSON.parse(opts.body);
+ expect(body.config).toBeUndefined();
+ });
});
diff --git a/sdk/typescript/test/compress.test.ts b/sdk/typescript/test/compress.test.ts
index 69a741bd2..0bddcce16 100644
--- a/sdk/typescript/test/compress.test.ts
+++ b/sdk/typescript/test/compress.test.ts
@@ -1,5 +1,6 @@
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();
@@ -115,4 +116,22 @@ describe("compress()", () => {
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);
+ });
});