How Headroom Integrates with Vercel AI SDK via wrapLanguageModel Middleware

Headroom provides a TypeScript adapter that implements the Vercel AI SDK LanguageModelV3Middleware interface, automatically compressing prompts through the Headroom proxy before they reach the underlying LLM.

The chopratejas/headroom repository includes a dedicated adapter for the Vercel AI SDK that enables automatic context compression via the wrapLanguageModel middleware pattern. This integration allows developers to reduce token costs and improve latency without changing existing AI SDK code patterns, keeping all heavy processing on the Headroom proxy or Headroom Cloud while maintaining zero runtime dependencies for the client.

Middleware Architecture and Contract

The integration centers on the headroomMiddleware function defined in sdk/typescript/src/adapters/vercel-ai.ts, which conforms to the Vercel AI SDK LanguageModelV3Middleware contract.

The transformParams Hook

Vercel AI SDK middlewares expose a transformParams hook that intercepts requests before they reach the language model. According to the source implementation, this hook receives the request parameters—including prompt or messages—and returns modified parameters. Headroom leverages this hook to compress context windows transparently.

The middleware executes the following sequence:

1. Intercept – The SDK calls transformParams on headroomMiddleware before invoking the underlying model
2. Normalize – Convert Vercel's ModelMessage[] format to OpenAI-compatible messages using vercelToOpenAI
3. Compress – Send messages to the Headroom proxy via the compress() API
4. Transform – Convert compressed OpenAI messages back to Vercel format using openAIToVercel
5. Proceed – Return transformed parameters to the SDK with the compressed prompt

Data Transformation Pipeline

Headroom operates on OpenAI-style chat schemas, requiring bidirectional format conversion handled by utilities in sdk/typescript/src/utils/format.ts.

Format Conversion Utilities

The vercelToOpenAI function translates Vercel AI SDK message arrays into the OpenAI chat completion format expected by the Headroom compression pipeline. After compression, openAIToVercel converts the optimized messages back to Vercel's internal ModelMessage[] structure.

These utilities ensure compatibility while allowing Headroom's core components—SmartCrusher, ContentRouter, and CacheAligner—to process the conversation history using their standard OpenAI-oriented logic.

Implementation Details

The adapter exports two primary interfaces from sdk/typescript/src/adapters/vercel-ai.ts:

• headroomMiddleware – The core middleware factory accepting configuration options including baseUrl
• withHeadroom – A convenience wrapper that composes wrapLanguageModel with the Headroom middleware

Both approaches maintain the zero-runtime-dependency design: the TypeScript SDK only requires the optional peer dependency ai (Vercel AI SDK), while all compression logic executes remotely on the Headroom proxy.

Usage Examples

Using headroomMiddleware with wrapLanguageModel

Import the middleware and wrap your existing model to enable automatic compression:

import { headroomMiddleware } from 'headroom-ai/vercel-ai';
import { wrapLanguageModel, generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

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

const { text } = await generateText({
  model,
  messages: longConversation,
});

The transformParams method inside headroomMiddleware intercepts the request, compresses it via the proxy, and returns the optimized prompt to the SDK.

Convenience Wrapper with withHeadroom

For simpler setup, use the withHeadroom helper which handles the wrapLanguageModel composition internally:

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

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

const { text } = await generateText({ model, messages: longConversation });

Direct Vercel Message Compression

For scenarios requiring manual control, compress Vercel messages directly before passing them to the model:

import { compressVercelMessages } from 'headroom-ai/vercel-ai';

const result = await compressVercelMessages(vercelMessages, {
  model: 'gpt-4o',
  baseUrl: 'http://localhost:8787',
});

console.log('Tokens saved:', result.tokensSaved);
const compressed = result.messages; // Returns Vercel ModelMessage[]

Summary

• Headroom implements LanguageModelV3Middleware via headroomMiddleware in sdk/typescript/src/adapters/vercel-ai.ts to intercept Vercel AI SDK requests.
• Bidirectional format conversion occurs through vercelToOpenAI and openAIToVercel utilities in src/utils/format.ts, enabling compatibility with Headroom's OpenAI-oriented compression pipeline.
• Zero client-side dependencies are required beyond the optional ai peer dependency; compression executes on the Headroom proxy or Headroom Cloud.
• The withHeadroom wrapper provides a drop-in replacement for wrapLanguageModel calls, maintaining existing code patterns while adding automatic context compression.

Frequently Asked Questions

What is the LanguageModelV3Middleware interface?

LanguageModelV3Middleware is the Vercel AI SDK contract for intercepting and modifying language model requests. It exposes hooks like transformParams that receive the original request parameters and return modified versions. Headroom's headroomMiddleware implements this interface to inject compression logic between the SDK and the underlying LLM without altering the developer-facing API.

Do I need to modify existing Vercel AI SDK code to integrate Headroom?

No. The Headroom Vercel AI SDK integration is designed as a transparent middleware layer. You can wrap existing models using either headroomMiddleware with wrapLanguageModel or the withHeadroom convenience function. Your existing generateText or streamText calls remain unchanged; the middleware automatically compresses messages before they reach the model.

How does Headroom handle format differences between Vercel AI SDK and OpenAI?

The middleware uses utility functions vercelToOpenAI and openAIToVercel located in sdk/typescript/src/utils/format.ts. When transformParams executes, it first converts Vercel's ModelMessage[] to OpenAI format for compression, then converts the resulting compressed messages back to Vercel format. This allows Headroom's core compression engine—which expects OpenAI-style schemas—to work seamlessly with the Vercel AI SDK's native message format.

Is the compression performed client-side or server-side?

Compression executes server-side on the Headroom proxy or Headroom Cloud infrastructure. The TypeScript SDK sends messages to the configured baseUrl via the compress() API, receives the optimized context, and returns it to the Vercel AI SDK. This architecture keeps client bundles small and offloads the heavy processing of SmartCrusher, ContentRouter, and CacheAligner components to the proxy layer.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}