[FEATURE] Add headroom-ai/cursor adapter for @cursor/sdk

[brandonlee-lomtech]

Problem Statement

Headroom already provides withHeadroom() adapters for OpenAI, Anthropic, Gemini, and Vercel AI SDK, but there is no equivalent for the Cursor TypeScript SDK (@cursor/sdk). Without an adapter, developers must manually compress history or rely on headroom wrap cursor (IDE proxy), which does not help programmatic SDK usage in Node.js/CI pipelines.

Proposed Solution

Add a headroom-ai/cursor export with a withHeadroom(Agent, options?) wrapper that mirrors the existing adapter pattern (OpenAI, Anthropic, etc.).

The wrapper should:

1. Intercept Agent.create(), Agent.resume(), Agent.prompt(), and each returned agent's send().
2. Local agents: Before each send(), read conversation history via Agent.messages.list(), compress it through the Headroom proxy, and apply compressed history on the next checkpoint loadLatest() by wrapping local.store.checkpointStore.
3. Cloud agents (bc-* agent ids): Compress outgoing user message text on each send() (and Agent.prompt()).
4. Pass through all other methods unchanged (list, getRun, messages.list, etc.).
5. Support standard Headroom options: baseUrl, model, fallback, etc.

Use Case

• Application type: Node.js automation, CI agents, internal tooling, and backend services built on @cursor/sdk (local repo agents and cloud agents against GitHub repos).
• How it helps: Automatic context compression on every turn without changing application code — wrap Agent once, call send() as usual. Local agents get full history compression; cloud agents get prompt compression for large pasted context.
• Token/cost savings: Depends on session length; Headroom's compress endpoint typically reports significant reduction on long histories (e.g. mock tests show ~70% token reduction: 100 → 30 tokens). Real savings scale with conversation length, tool output volume, and repeated file contents in history.

Alternatives Considered

1. headroom wrap cursor (IDE proxy) — Works for Cursor IDE traffic only; does not integrate with programmatic @cursor/sdk usage in scripts or CI.
2. Manual compression before each send() — Requires developers to call Headroom's compress API themselves, convert message formats, and manage checkpoint state — error-prone and duplicates logic across apps.
3. Intercept at a lower Cursor SDK API — The SDK keeps context in opaque checkpoint blobs and only accepts new prompts on send(); there is no single "messages array" hook like Anthropic's messages.create(). A lifecycle + checkpoint-store wrapper is the practical integration point.

Example API (Optional)

import { Agent } from '@cursor/sdk';
import { withHeadroom } from 'headroom-ai/cursor';

const HAgent = withHeadroom(Agent, {
  baseUrl: 'http://localhost:8787',
  model: 'composer-2.5',
  fallback: true,
});

// Local agent — history compressed via wrapped checkpoint store
const localAgent = await HAgent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: 'composer-2.5' },
  local: {
    cwd: process.cwd(),
    store: myLocalAgentStore, // wrapped automatically
  },
});

await localAgent.send('Summarize this repository.');
await localAgent.send('Now focus on the SDK folder.'); // history compressed before this send

// Cloud agent — user prompt text compressed on each send()
const cloudAgent = await HAgent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  cloud: {
    repos: [{ url: 'https://github.com/your-org/your-repo' }],
  },
});

await cloudAgent.send('Large pasted context plus a question...');

Additional Context

• Are you willing to contribute this feature?

• Yes. implementation, unit tests, example, and documentation.