mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
c2fc4d3753
The optional `query` parameter on headroom_retrieve routed retrieval through CompressionStore.search(), which BM25-scored the items inside a single cached blob and dropped everything below a 0.3 relevance floor. On small per-blob corpora with conversational queries this returned an empty result the large majority of the time, so the LLM saw "nothing found" for content that was actually present — pushing users to turn compression off entirely. Retrieval is fundamentally a hash lookup (this already matches the Rust proxy's CCR store, which is put/get only — "no BM25 search"). Remove the query/search path end to end and always return the full original content: Core (Python proxy): - tool schemas (anthropic/openai/google) drop the `query` property - parse_tool_call returns the hash (str | None) instead of (hash, query) - response handler, proxy POST/GET/tool-call handlers, the MCP retrieve tool, and the streaming feedback recorders retrieve by hash only - proactive context-tracker expansion always restores full content - delete CompressionStore.search() and its BM25 machinery (the bm25 module stays — it is still used by relevance/) - CCRToolCall.query, CCRToolResult.was_search, and ExpansionRecommendation.expand_full/search_query are removed Plugins (advertised a now-defunct query param to the LLM): - hermes (Python), openclaw + opencode (TypeScript) retrieve tools drop `query` from their schemas, signatures, request URLs, and tests Benchmarks/docs: - ccr_regression + adversarial benchmarks switch from store.search() to full hash retrieval (search input-injection tests repurposed to the hash, the only remaining input surface) - wiki/ARCHITECTURE.md, wiki/ccr.md, docs/content/docs/ccr.mdx, config.py and store docstrings updated to describe hash-only retrieval Tests updated to assert full-content retrieval and guard the removed surface; the full CCR/proxy/store/TOIN suite passes. ruff + mypy clean. ## Description <!-- Briefly explain the change and why it is needed. --> Closes # ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [ ] New feature (non-breaking change that adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update - [ ] Performance improvement - [ ] Code refactoring (no functional changes) ## Changes Made - ## Testing <!-- Check what you actually ran, then paste the real command output below. --> - [ ] Unit tests pass (`pytest`) - [ ] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) - [ ] New tests added for new functionality - [ ] Manual testing performed ### Test Output ```text # Paste relevant command output or artifact links here ``` ## Real Behavior Proof - Environment: - Exact command / steps: - Observed result: - Not tested: ## Review Readiness - [ ] I have performed a self-review - [ ] This PR is ready for human review ## Checklist - [ ] My code follows the project's style guidelines - [ ] I have performed a self-review of my code - [ ] I have commented my code, particularly in hard-to-understand areas - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable ## Screenshots (if applicable) Add screenshots to help explain your changes. ## Additional Notes <!-- Mention any N/A checklist items, tradeoffs, follow-ups, or maintainer context. -->
107 lines
2.8 KiB
Markdown
107 lines
2.8 KiB
Markdown
# headroom-opencode
|
|
|
|
OpenCode integration helpers for Headroom. The package supports two integration paths:
|
|
|
|
1. Provider config helpers used by `headroom wrap opencode` and persistent installs.
|
|
2. A native OpenCode plugin that installs Headroom transport interception and exposes the retrieve tool.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install headroom-opencode
|
|
```
|
|
|
|
## Provider Config Helpers
|
|
|
|
Use these helpers when you need to generate OpenCode config that routes a `headroom` provider through a running Headroom proxy.
|
|
|
|
```ts
|
|
import {
|
|
buildOpencodeConfigContent,
|
|
createHeadroomProvider,
|
|
} from "headroom-opencode";
|
|
|
|
const provider = createHeadroomProvider({ proxyPort: 8787 });
|
|
const config = buildOpencodeConfigContent({
|
|
proxyPort: 8787,
|
|
defaultModel: "claude-sonnet-4-6",
|
|
});
|
|
|
|
console.log(provider.provider.headroom.npm);
|
|
console.log(config.model);
|
|
```
|
|
|
|
The generated provider uses `@ai-sdk/openai-compatible` and points model requests at `http://127.0.0.1:<port>/v1`.
|
|
|
|
## Native OpenCode Plugin
|
|
|
|
Use `HeadroomPlugin` when OpenCode should intercept provider traffic in-process and expose Headroom tooling from a plugin.
|
|
|
|
```ts
|
|
import { HeadroomPlugin } from "headroom-opencode";
|
|
|
|
export default async function plugin(input) {
|
|
return HeadroomPlugin(input, {
|
|
proxyUrl: process.env.HEADROOM_PROXY_URL ?? "http://127.0.0.1:8787",
|
|
});
|
|
}
|
|
```
|
|
|
|
`HeadroomPlugin`:
|
|
|
|
- installs Headroom transport interception for OpenCode provider traffic.
|
|
- exposes the `headroom_retrieve` tool.
|
|
- publishes `HEADROOM_PROXY_URL` in the plugin output env.
|
|
- defaults to `http://127.0.0.1:8787` when no proxy URL is supplied.
|
|
|
|
## Retrieve Tool
|
|
|
|
```ts
|
|
import { createHeadroomRetrieveTool } from "headroom-opencode";
|
|
|
|
const retrieve = createHeadroomRetrieveTool({
|
|
proxyBaseUrl: "http://127.0.0.1:8787",
|
|
});
|
|
|
|
const result = await retrieve.execute({
|
|
hash: "0123456789abcdef01234567",
|
|
});
|
|
```
|
|
|
|
The tool calls `/v1/retrieve/<hash>` on the Headroom proxy.
|
|
|
|
## Compression Helper
|
|
|
|
```ts
|
|
import { compressWithHeadroom } from "headroom-opencode";
|
|
|
|
const result = await compressWithHeadroom(
|
|
[{ role: "user", content: "Summarize this file" }],
|
|
{ model: "gpt-4o", proxyUrl: "http://127.0.0.1:8787" },
|
|
);
|
|
|
|
console.log(`Saved ${result.tokensSaved} tokens`);
|
|
```
|
|
|
|
## Models
|
|
|
|
| Model | Context | Output |
|
|
|---|---:|---:|
|
|
| `claude-sonnet-4-6` | 200K | 16K |
|
|
| `claude-opus-4-6` | 200K | 16K |
|
|
| `claude-haiku-4-5-20251001` | 200K | 8K |
|
|
| `gpt-4o` | 128K | 16K |
|
|
| `gpt-4.1` | 1M | 32K |
|
|
|
|
The provider config exposes these as `headroom/<model>` and defaults to `headroom/claude-sonnet-4-6`.
|
|
|
|
## Environment
|
|
|
|
| Variable | Used by | Description |
|
|
|---|---|---|
|
|
| `HEADROOM_PROXY_URL` | Native plugin | Proxy URL used by `HeadroomPlugin` |
|
|
| `OPENCODE_CONFIG_CONTENT` | OpenCode wrapper | Generated OpenCode provider, model, and MCP config |
|
|
|
|
## License
|
|
|
|
Apache-2.0
|