Files
headroom/sdk/typescript
github-actions[bot] 660fa8cfb6 chore: release main (#1574)
🤖 I have created a release *beep* *boop*
---


<details><summary>0.29.0</summary>

##
[0.29.0](https://github.com/headroomlabs-ai/headroom/compare/v0.28.0...v0.29.0)
(2026-07-03)


### Features

* **proxy:** add --lossless no-CCR mode with format-native compaction
([#1721](https://github.com/headroomlabs-ai/headroom/issues/1721))
([c75ebde](https://github.com/headroomlabs-ai/headroom/commit/c75ebdee6df9b1689a44ef321e36e8b360406ed7))
* **stats:** surface Codex WS compression counters in /stats summary
([#1680](https://github.com/headroomlabs-ai/headroom/issues/1680))
([2fe19c3](https://github.com/headroomlabs-ai/headroom/commit/2fe19c39e40fc350af39f72e1a3bac28f9ce9874))
* **transforms:** adaptive Otsu KEEP/DROP threshold (+ land relevance
split on main)
([#1726](https://github.com/headroomlabs-ai/headroom/issues/1726))
([eea667a](https://github.com/headroomlabs-ai/headroom/commit/eea667a72019cc98401db9211907f67ddf45e7eb))


### Bug Fixes

* **bedrock:** fail fast when session-token auth lacks botocore
([#1553](https://github.com/headroomlabs-ai/headroom/issues/1553))
([54cfa36](https://github.com/headroomlabs-ai/headroom/commit/54cfa361d308dec567615c346af7c77d52ebb676))
* **bedrock:** route ARNs via converse, named AWS profiles, and au. re…
([#1456](https://github.com/headroomlabs-ai/headroom/issues/1456))
([7d87aa2](https://github.com/headroomlabs-ai/headroom/commit/7d87aa2f1cbd93c970a77c6dfec8df03603251b9))
* **ccr:** honor workspace dir for sqlite store
([#1564](https://github.com/headroomlabs-ai/headroom/issues/1564))
([96e1dfe](https://github.com/headroomlabs-ai/headroom/commit/96e1dfe395a440f9e2dddf4589c4f6988f4ee4cd))
* **claude:** surface Remote Control proxy incompatibility
([#1610](https://github.com/headroomlabs-ai/headroom/issues/1610))
([4bf7f92](https://github.com/headroomlabs-ai/headroom/commit/4bf7f92417a8799ab3ae5f61b7ea9e96c5605a4f))
* **cli:** stop advertising unwired compression tuning env vars in
banner
([#1634](https://github.com/headroomlabs-ai/headroom/issues/1634))
([d5bf98d](https://github.com/headroomlabs-ai/headroom/commit/d5bf98df31528dfd6c23ec45dbd3440efcb1cb75))
* **codex:** avoid duplicate headroom provider config
([#1431](https://github.com/headroomlabs-ai/headroom/issues/1431))
([ddd4adf](https://github.com/headroomlabs-ai/headroom/commit/ddd4adf911ee2d7a5323657a771ea0162b5590c4))
* **compression:** reject lossy unmarked tool output in unit router path
([#1479](https://github.com/headroomlabs-ai/headroom/issues/1479))
([de24cd5](https://github.com/headroomlabs-ai/headroom/commit/de24cd5fc0b894037c0481b5394e6851e87b3993))
* **cortex-code:** migrate to current Cortex REST API endpoints + add
e2e benchmarks
([#1474](https://github.com/headroomlabs-ai/headroom/issues/1474))
([f00ace6](https://github.com/headroomlabs-ai/headroom/commit/f00ace6da57aec2f68b833f42603ba3fda0f9110))
* **dashboard:** align token savings headline denominator
([#1653](https://github.com/headroomlabs-ai/headroom/issues/1653))
([646e705](https://github.com/headroomlabs-ai/headroom/commit/646e7055143638ac4a2bc9980649fd046cea7840))
* **dashboard:** derive per-project setup URL from live origin
([#1511](https://github.com/headroomlabs-ai/headroom/issues/1511))
([e035aef](https://github.com/headroomlabs-ai/headroom/commit/e035aefce23fd2e20afccf2659c1db613b05d8ca))
* **detection:** contain unidiff panic on orphaned +++ target line
([#1548](https://github.com/headroomlabs-ai/headroom/issues/1548))
([e386c09](https://github.com/headroomlabs-ai/headroom/commit/e386c097d6d507aa311ca3a22725b226e9d7b223))
* **evals:** CJK-aware F1 tokenization + token estimation
([#1527](https://github.com/headroomlabs-ai/headroom/issues/1527))
([99a8540](https://github.com/headroomlabs-ai/headroom/commit/99a8540e657445df3204f1d15e213262f4289a42))
* **install:** close parent log fd in start_detached_agent
([#1576](https://github.com/headroomlabs-ai/headroom/issues/1576))
([816cb85](https://github.com/headroomlabs-ai/headroom/commit/816cb85fa8ee8d349fe673e7affd9a54acb1207d))
* **install:** use Windows-safe PID liveness probe in runtime_status
([#1544](https://github.com/headroomlabs-ai/headroom/issues/1544))
([#1560](https://github.com/headroomlabs-ai/headroom/issues/1560))
([6b227b9](https://github.com/headroomlabs-ai/headroom/commit/6b227b9c906d708923f39c0d877989a49942adae))
* **learn:** aggregate verbosity baselines across projects instead of
overwriting
([#1288](https://github.com/headroomlabs-ai/headroom/issues/1288))
([27a5468](https://github.com/headroomlabs-ai/headroom/commit/27a546834960b349e710a0b2e86ca3471523f34d))
* **mcp:** show lifetime totals and label rolling session scope in
headroom_stats
([#1428](https://github.com/headroomlabs-ai/headroom/issues/1428))
([1c0e152](https://github.com/headroomlabs-ai/headroom/commit/1c0e15243eda8f2dc868fe9ed4a08d944893686b))
* **memory:** cap local embedder CPU thread oversubscription
([#198](https://github.com/headroomlabs-ai/headroom/issues/198))
([#1559](https://github.com/headroomlabs-ai/headroom/issues/1559))
([b84afbf](https://github.com/headroomlabs-ai/headroom/commit/b84afbfb833999ddf164d324971bf6c11014a9d3))
* **memory:** singleflight LocalBackend init to stop cold-start races
([#1691](https://github.com/headroomlabs-ai/headroom/issues/1691))
([bec47a1](https://github.com/headroomlabs-ai/headroom/commit/bec47a1898883919ad8c5ea41e3a7443a6890e7f))
* **openclaw:** detect uv-installed headroom binary in ~/.local/bin
([#1459](https://github.com/headroomlabs-ai/headroom/issues/1459))
([adaeb88](https://github.com/headroomlabs-ai/headroom/commit/adaeb88a4d5512da5bd0bf58c1e3a276a5269d44))
* **opencode:** preserve custom OpenAI gateway paths
([#1596](https://github.com/headroomlabs-ai/headroom/issues/1596))
([c19347c](https://github.com/headroomlabs-ai/headroom/commit/c19347c31046bf25baf9b1a816c9bede5d3ee807))
* **opencode:** route native providers + load transport plugin, fix
Serena context
([#1573](https://github.com/headroomlabs-ai/headroom/issues/1573))
([ad0034f](https://github.com/headroomlabs-ai/headroom/commit/ad0034f98191501c1a60d26383bc3ed9f6d532be))
* preserve anthropic passthrough tool order
([#1427](https://github.com/headroomlabs-ai/headroom/issues/1427))
([a932247](https://github.com/headroomlabs-ai/headroom/commit/a9322477e33ec2c5ccd6442d3f72c17b7388c9e0))
* **proxy/auth:** match real Anthropic OAuth token prefix (sk-ant-oat)
([#1672](https://github.com/headroomlabs-ai/headroom/issues/1672))
([8cddf9b](https://github.com/headroomlabs-ai/headroom/commit/8cddf9b58ea9ed11a0cd3532be6e779dffe57b55))
* **proxy:** expose persistent savings metrics
([#1647](https://github.com/headroomlabs-ai/headroom/issues/1647))
([5fe4e7b](https://github.com/headroomlabs-ai/headroom/commit/5fe4e7b19530da0c2d07d17f20b18d79b6fab367))
* **proxy:** fail open when kompress saturation would exhaust
pre-upstream budget
([#1430](https://github.com/headroomlabs-ai/headroom/issues/1430))
([15ac650](https://github.com/headroomlabs-ai/headroom/commit/15ac650d409ea7def9e54d9962af1cfdc1f11f5d))
* **proxy:** handle streaming CCR retrieval
([#1451](https://github.com/headroomlabs-ai/headroom/issues/1451))
([d337e3b](https://github.com/headroomlabs-ai/headroom/commit/d337e3b828ffc1f22cd5ca1884500b8905e9bd82))
* **proxy:** include system/tools/sampling in cache key
([#1473](https://github.com/headroomlabs-ai/headroom/issues/1473))
([312129a](https://github.com/headroomlabs-ai/headroom/commit/312129a8e7465c97402ae45b9e9d51b7f4b5b0c7))
* **proxy:** preserve Responses passthrough bytes
([#1598](https://github.com/headroomlabs-ai/headroom/issues/1598))
([2a34a82](https://github.com/headroomlabs-ai/headroom/commit/2a34a822f2a39da57fbd07575752888f5515f51a))
* **proxy:** strip Codex lite header on the HTTP /responses path
([#1663](https://github.com/headroomlabs-ai/headroom/issues/1663))
([9fbd47b](https://github.com/headroomlabs-ai/headroom/commit/9fbd47ba6bdf38b618795541ee517b7e2fa2c6df))
* **proxy:** wire --compression-max-workers /
HEADROOM_COMPRESSION_MAX_WORKERS
([#1632](https://github.com/headroomlabs-ai/headroom/issues/1632))
([814ffa3](https://github.com/headroomlabs-ai/headroom/commit/814ffa36a4d1bb40165a630f96a855452037735e))
* **savings:** count cache-read tokens in input cost estimate
([#1429](https://github.com/headroomlabs-ai/headroom/issues/1429))
([72ade37](https://github.com/headroomlabs-ai/headroom/commit/72ade3711211183b9134a46d9c5d45db6a87edc2))
* skip Magika backend on x86 CPUs without AVX2
([#1162](https://github.com/headroomlabs-ai/headroom/issues/1162))
([64783d8](https://github.com/headroomlabs-ai/headroom/commit/64783d8824e3c3afc43d9980573d9440693d0963))
* **transforms/content-router:** route grep/log output away from HTML
extractor
([#1719](https://github.com/headroomlabs-ai/headroom/issues/1719))
([0d18ef2](https://github.com/headroomlabs-ai/headroom/commit/0d18ef26f4d126f8eec9df1d34330a7129c4c63f))
* **transforms:** bound native content detection with a Windows watchdog
([#575](https://github.com/headroomlabs-ai/headroom/issues/575))
([#1563](https://github.com/headroomlabs-ai/headroom/issues/1563))
([95abca3](https://github.com/headroomlabs-ai/headroom/commit/95abca3abd69add5f075d241284b565e0014d5a4))
* Vertex AI support for Claude Code with ANTHROPIC_VERTEX_BASE_URL
([#1393](https://github.com/headroomlabs-ai/headroom/issues/1393))
([cff7247](https://github.com/headroomlabs-ai/headroom/commit/cff7247efd6fbecc1c2e66280a4a9b6381d7b7a4))
* **wrap:** detach the shared proxy on Windows so it survives an
ungraceful agent close
([#1464](https://github.com/headroomlabs-ai/headroom/issues/1464))
([6cba441](https://github.com/headroomlabs-ai/headroom/commit/6cba4419d04bea79c1b44632a9288cde5b48bbce))
* **wrap:** preserve custom Vertex base URL
([#1477](https://github.com/headroomlabs-ai/headroom/issues/1477))
([75427bb](https://github.com/headroomlabs-ai/headroom/commit/75427bbd4ad14fcb1b205f3253ec4e24ae1d2118))
* **wrap:** remove rtk instructions from Codex AGENTS.md on unwrap
([#1604](https://github.com/headroomlabs-ai/headroom/issues/1604))
([c9d717c](https://github.com/headroomlabs-ai/headroom/commit/c9d717c13c7ae006178e49b6570f63b3f82de9a2))
</details>

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-07-02 22:54:04 -07:00
..
2026-04-06 21:24:36 +06:00
2026-07-02 22:54:04 -07:00
2026-04-06 21:24:36 +06:00

headroom-ai

Compress LLM context. Save tokens. Fit more into every request.

Install

npm install headroom-ai

Quick Start

import { compress } from 'headroom-ai';

const result = await compress(messages, { model: 'gpt-4o' });
console.log(`Saved ${result.tokensSaved} tokens (${((1 - result.compressionRatio) * 100).toFixed(0)}%)`);

// Use compressed messages with any LLM client
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: result.messages,
});

Requires a running Headroom proxy (headroom proxy).

Framework Adapters

Vercel AI SDK

import { withHeadroom } from 'headroom-ai/vercel-ai';
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

const model = withHeadroom(openai('gpt-4o'));
const { text } = await generateText({ model, messages });
Advanced: using middleware directly
import { headroomMiddleware } from 'headroom-ai/vercel-ai';
import { wrapLanguageModel } from 'ai';

const model = wrapLanguageModel({
  model: openai('gpt-4o'),
  middleware: headroomMiddleware({ baseUrl: 'http://localhost:8787' }),
});

OpenAI SDK

import { withHeadroom } from 'headroom-ai/openai';
import OpenAI from 'openai';

const client = withHeadroom(new OpenAI());
const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: longConversation,
});

Anthropic SDK

import { withHeadroom } from 'headroom-ai/anthropic';
import Anthropic from '@anthropic-ai/sdk';

const client = withHeadroom(new Anthropic());
const response = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  messages: longConversation,
  max_tokens: 1024,
});

Google Gemini

import { withHeadroom } from 'headroom-ai/gemini';
import { GoogleGenerativeAI } from '@google/generative-ai';

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const model = withHeadroom(genAI.getGenerativeModel({ model: 'gemini-2.0-flash' }));

const result = await model.generateContent({
  contents: longConversation,
});

HeadroomClient

The full client provides direct access to the proxy's OpenAI and Anthropic passthrough endpoints, plus metrics, CCR, and observability.

import { HeadroomClient } from 'headroom-ai';

const client = new HeadroomClient({
  baseUrl: 'http://localhost:8787',
  providerApiKey: process.env.OPENAI_API_KEY,
  config: {
    smartCrusher: { enabled: true, maxItemsAfterCrush: 10 },
    ccr: { enabled: true },
  },
});

Chat Completions (OpenAI-style)

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: longConversation,
  headroomMode: 'optimize',
});

Messages (Anthropic-style)

const response = await client.messages.create({
  model: 'claude-sonnet-4-5-20250929',
  messages: longConversation,
  max_tokens: 1024,
  headroomMode: 'optimize',
});

Direct Compression

const result = await client.compress(messages, { model: 'gpt-4o', tokenBudget: 4000 });

Simulation (Dry Run)

See what compression would do without calling the LLM.

import { simulate } from 'headroom-ai';

const sim = await simulate(messages, { model: 'gpt-4o' });
console.log(`Would save ${sim.tokensSaved} tokens (${sim.estimatedSavings})`);
console.log('Transforms:', sim.transforms);
console.log('Waste signals:', sim.wasteSignals);
console.log('Cache alignment:', sim.cacheAlignmentScore);

Also available on the client:

const sim = await client.chat.completions.simulate({
  model: 'gpt-4o',
  messages,
});

Compression Hooks

Customize compression with pre/post hooks — matching the Python CompressionHooks API.

import { compress, CompressionHooks } from 'headroom-ai';
import type { CompressContext, CompressEvent } from 'headroom-ai';

class MyHooks extends CompressionHooks {
  // Modify messages before compression
  preCompress(messages: any[], ctx: CompressContext) {
    return [{ role: 'system', content: 'Always preserve error details.' }, ...messages];
  }

  // Set per-message importance biases
  computeBiases(messages: any[], ctx: CompressContext) {
    return { 0: 2.0 }; // preserve first message
  }

  // Observe compression results
  postCompress(event: CompressEvent) {
    console.log(`Saved ${event.tokensSaved} tokens via ${event.transformsApplied.join(', ')}`);
  }
}

const result = await compress(messages, { model: 'gpt-4o', hooks: new MyHooks() });

SharedContext (Multi-Agent)

Compressed inter-agent context sharing — matching the Python SharedContext API.

import { SharedContext } from 'headroom-ai';

const ctx = new SharedContext({ model: 'gpt-4o', ttl: 3600, maxEntries: 100 });

// Agent A stores data (automatically compressed)
const entry = await ctx.put('research', bigAgentOutput, { agent: 'researcher' });
console.log(`Compressed: ${entry.savingsPercent.toFixed(0)}% savings`);

// Agent B reads it (~80% smaller)
const summary = ctx.get('research');

// Agent B gets original if needed
const full = ctx.get('research', { full: true });

// Stats
const stats = ctx.stats();
console.log(`${stats.entries} entries, ${stats.totalTokensSaved} tokens saved`);

CCR Retrieve (Compress-Cache-Retrieve)

Retrieve original content when the LLM needs full details.

const result = await client.compress(messages, { model: 'gpt-4o' });

// Later, when the LLM calls headroom_retrieve:
for (const hash of result.ccrHashes) {
  const original = await client.retrieve(hash);
  console.log(`${original.originalTokens} original tokens for ${original.toolName}`);
}

// Search within compressed content
const search = await client.retrieve('abc123', { query: 'error logs' });

// Handle LLM tool calls in an agent loop
const toolResult = await client.handleToolCall({
  toolCall: assistantMessage.tool_calls[0],
  provider: 'openai',
});

Metrics & Observability

// Proxy health
const health = await client.health();
// → { status: 'healthy', version: '0.5.18', config: { optimize: true, ... } }

// Proxy stats
const stats = await client.proxyStats();
// → { requests: { total, cached, failed }, tokens: { saved, savingsPercent }, ... }

// Request metrics
const metrics = await client.getMetrics({ model: 'gpt-4o', limit: 10 });

// Summary
const summary = await client.getSummary();

// Validate setup
const validation = await client.validateSetup();

// Clear cache
await client.clearCache();

// Prometheus metrics
const prom = await client.prometheusMetrics();

Telemetry, Feedback & TOIN

Access the proxy's learning systems.

// Telemetry
const telemetry = await client.telemetry.getStats();
const tools = await client.telemetry.getTools();

// Feedback — per-tool compression hints
const hints = await client.feedback.getHints('list_servers');
// → { hints: { maxItems: 8, skipCompression: false, preserveFields: ['id', 'status'] } }

// TOIN (Tool Output Intelligence Network)
const toinStats = await client.toin.getStats();
const patterns = await client.toin.getPatterns(20);

Configuration Types

Full TypeScript interfaces for every Python config dataclass.

import type { HeadroomConfig, SmartCrusherConfig, CCRConfig } from 'headroom-ai';

const config: HeadroomConfig = {
  defaultMode: 'optimize',
  smartCrusher: {
    enabled: true,
    minItemsToAnalyze: 5,
    maxItemsAfterCrush: 10,
    varianceThreshold: 2.0,
    relevance: { tier: 'hybrid', relevanceThreshold: 0.25 },
    anchor: { anchorBudgetPct: 0.25 },
  },
  ccr: { enabled: true, injectTool: true },
  cacheOptimizer: { enabled: true, autoDetectProvider: true },
  intelligentContext: { enabled: true, useImportanceScoring: true },
};

const client = new HeadroomClient({ config });

Error Handling

Full error hierarchy matching the Python SDK.

import {
  HeadroomError,
  HeadroomConnectionError,
  HeadroomAuthError,
  HeadroomCompressError,
  ConfigurationError,
  ProviderError,
  StorageError,
  TokenizationError,
  CacheError,
  ValidationError,
  TransformError,
} from 'headroom-ai';

try {
  await client.compress(messages);
} catch (err) {
  if (err instanceof HeadroomAuthError) {
    console.error('Auth failed — check HEADROOM_API_KEY');
  } else if (err instanceof HeadroomCompressError) {
    console.error(`Compression error ${err.statusCode}: ${err.errorType}`);
  } else if (err instanceof ConfigurationError) {
    console.error('Bad config:', err.details);
  }
}

Format Detection & Conversion

Auto-detects and converts between OpenAI, Anthropic, Vercel AI SDK, and Gemini formats.

import { detectFormat, toOpenAI, fromOpenAI } from 'headroom-ai';

const format = detectFormat(messages); // 'openai' | 'anthropic' | 'vercel' | 'gemini'
const openaiMessages = toOpenAI(messages);
const back = fromOpenAI(openaiMessages, format);

The compress() function handles this automatically — pass any format and get the same format back.

Configuration

import { compress } from 'headroom-ai';

const result = await compress(messages, {
  model: 'gpt-4o',
  baseUrl: 'http://localhost:8787',  // proxy URL
  apiKey: 'your-api-key',             // optional, for authenticated endpoints
  timeout: 30000,                     // ms
  fallback: true,                     // return uncompressed if proxy is down (default)
  retries: 1,                         // retry on transient failures (default)
  tokenBudget: 4000,                  // compress to fit this limit
  hooks: new MyHooks(),               // pre/post compression hooks
});

Or use environment variables:

  • HEADROOM_BASE_URL — proxy URL
  • HEADROOM_API_KEY — optional API key for authenticated endpoints

Utilities

// Case conversion for proxy communication
import { deepCamelCase, deepSnakeCase } from 'headroom-ai';

const tsObj = deepCamelCase({ tokens_before: 100 }); // { tokensBefore: 100 }
const pyObj = deepSnakeCase({ tokensBefore: 100 });   // { tokens_before: 100 }

// SSE stream parsing
import { parseSSE, collectStream } from 'headroom-ai';

// Hook helpers
import { extractUserQuery, countTurns, extractToolCalls } from 'headroom-ai';

License

Apache-2.0