chore(sync): merge main into per-request cost branch

This commit is contained in:
JerrettDavis
2026-10-16 19:19:59 -05:00
194 changed files with 14360 additions and 3328 deletions
+49 -49
View File
@@ -1,49 +1,49 @@
{
"name": "headroom-marketplace",
"owner": {
"name": "Headroom Contributors"
},
"metadata": {
"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
"version": "0.40.0"
},
"plugins": [
{
"name": "headroom",
"source": "./plugins/headroom-agent-hooks",
"description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
"version": "0.40.0",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/headroomlabs-ai/headroom"
},
"homepage": "https://github.com/headroomlabs-ai/headroom",
"repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"hooks",
"claude-code",
"copilot-cli"
]
},
{
"name": "headroom-snip",
"source": "./plugins/headroom-snip",
"description": "Claude Code mod: watch Headroom snip tokens off every request, with an animated band, a /headroom log and a running total.",
"version": "0.40.0",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/headroomlabs-ai/headroom"
},
"homepage": "https://github.com/headroomlabs-ai/headroom",
"repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"claude-code",
"tokens",
"compression",
"mod"
]
}
]
}
{
"name": "headroom-marketplace",
"owner": {
"name": "Headroom Contributors"
},
"metadata": {
"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
"version": "0.41.0"
},
"plugins": [
{
"name": "headroom",
"source": "./plugins/headroom-agent-hooks",
"description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
"version": "0.41.0",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/headroomlabs-ai/headroom"
},
"homepage": "https://github.com/headroomlabs-ai/headroom",
"repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"hooks",
"claude-code",
"copilot-cli"
]
},
{
"name": "headroom-snip",
"source": "./plugins/headroom-snip",
"description": "Claude Code mod: watch Headroom snip tokens off every request, with an animated band, a /headroom log and a running total.",
"version": "0.41.0",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/headroomlabs-ai/headroom"
},
"homepage": "https://github.com/headroomlabs-ai/headroom",
"repository": "https://github.com/headroomlabs-ai/headroom",
"keywords": [
"headroom",
"claude-code",
"tokens",
"compression",
"mod"
]
}
]
}
+2 -2
View File
@@ -5,14 +5,14 @@
},
"metadata": {
"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
"version": "0.40.0"
"version": "0.41.0"
},
"plugins": [
{
"name": "headroom",
"source": "./plugins/headroom-agent-hooks",
"description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
"version": "0.40.0",
"version": "0.41.0",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/headroomlabs-ai/headroom"
+1 -1
View File
@@ -730,7 +730,7 @@ jobs:
timeout-minutes: 20
steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v6
- uses: actions/setup-python@v7
with:
python-version: ${{ env.PY_VERSION }}
- name: Install headroom-ai[dev] (published wheel; local source shadows it)
+1 -1
View File
@@ -41,7 +41,7 @@ jobs:
python-version: "3.12"
- name: Install uv
uses: astral-sh/setup-uv@v10.2.0
uses: astral-sh/setup-uv@v10.3.0
- name: Export production dependency set from uv.lock
run: |
+1 -1
View File
@@ -27,7 +27,7 @@ repos:
# unconditionally, so installing hooks is not required for enforcement.
args: [--assume-in-merge]
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.16.8
rev: v0.17.0
hooks:
- id: ruff
args: [--fix]
+1 -1
View File
@@ -1,3 +1,3 @@
{
".": "0.40.0"
".": "0.41.0"
}
+6 -6
View File
@@ -1,10 +1,10 @@
{
"version": "0.40.0",
"version": "0.41.0",
"packages": {
"pypi": "0.40.0",
"npm-sdk": "0.40.0",
"npm-openclaw": "0.40.0",
"npm-opencode": "0.40.0",
"agent-hooks-plugin": "0.40.0"
"pypi": "0.41.0",
"npm-sdk": "0.41.0",
"npm-openclaw": "0.41.0",
"npm-opencode": "0.41.0",
"agent-hooks-plugin": "0.41.0"
}
}
+121
View File
@@ -284,6 +284,127 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- **code:** fix two `CodeAwareCompressor` AST-reassembly bugs: an exported JS/TS function or class (`export function foo() {`) produced a duplicated `export export` keyword and invalid syntax, because line-based node slicing (used to preserve indentation) pulled in the preceding `export` sibling's text on top of the `export_statement` handler's own prefix reconstruction. Separately, in every supported language, a doc comment immediately above a top-level function, class, or type was detached from its declaration during extraction and re-emitted in a cluster at the end of the compressed output instead of staying attached to what it documents.
- * **proxy:** Buffered upstream responses containing a `server_tool_use` (or any other unrecognized Anthropic content block) no longer turn a fully-generated response into an HTTP 502. `StreamingMixin._response_to_sse` raised `ValueError` on unknown block types after the entire upstream generation had already been buffered, so a slow-but-successful response failed and the client retried the whole multi-minute request. Unknown blocks are now emitted verbatim in `content_block_start` (following the existing redacted_thinking` pattern), so `server_tool_use`, `server_tool_result`, `mcp_tool_use`, and future block types round-trip ([#1806](https://github.com/headroomlabs-ai/headroom/issues/1806)).
## [0.41.0](https://github.com/headroomlabs-ai/headroom/compare/v0.40.0...v0.41.0) (2026-10-13)
### Features
* **antigravity:** add native Google Antigravity IDE integration ([#3817](https://github.com/headroomlabs-ai/headroom/issues/3817)) ([cd4367b](https://github.com/headroomlabs-ai/headroom/commit/cd4367b040bf80b7358f100da54994f6d5fbfcfe))
* **opencode:** support the OpenCode 2.x plugin API ([#3999](https://github.com/headroomlabs-ai/headroom/issues/3999)) ([1d4b357](https://github.com/headroomlabs-ai/headroom/commit/1d4b357ca745549382e1ed9a3a6d39b5df52d3d5))
* **plugins:** add headroom-snip Claude Code mod that animates compression ([#3980](https://github.com/headroomlabs-ai/headroom/issues/3980)) ([17abee2](https://github.com/headroomlabs-ai/headroom/commit/17abee2721c1946bc8903d623bec91ff6e531c17))
* **proxy:** native spend/savings stats + dashboard for the Rust proxy ([#2321](https://github.com/headroomlabs-ai/headroom/issues/2321)) ([70b21c1](https://github.com/headroomlabs-ai/headroom/commit/70b21c12c41cd128c7b8700c33b29b687de567a4))
* **router:** add max_output_tokens condition to ModelRoute ([#3898](https://github.com/headroomlabs-ai/headroom/issues/3898)) ([01185e3](https://github.com/headroomlabs-ai/headroom/commit/01185e32d393c02ae63b104429f6dbfc6cdd1da0))
* **savings:** per-agent attribution in history checkpoints and rollups ([#2627](https://github.com/headroomlabs-ai/headroom/issues/2627)) ([489de46](https://github.com/headroomlabs-ai/headroom/commit/489de468258584c69c90c798397d81e0b35ace67))
* show the Headroom for Teams offer in the dashboard, docs, llms.txt and release notes ([#3991](https://github.com/headroomlabs-ai/headroom/issues/3991)) ([1ad92f0](https://github.com/headroomlabs-ai/headroom/commit/1ad92f0cbc3dea27676e253588100f64a2af6994))
### Bug Fixes
* **anthropic:** route /api/hello connectivity probes to Anthropic ([#3336](https://github.com/headroomlabs-ai/headroom/issues/3336)) ([#4059](https://github.com/headroomlabs-ai/headroom/issues/4059)) ([931e5b9](https://github.com/headroomlabs-ai/headroom/commit/931e5b9666f4022feb38abadfbdb77c96c69e95a))
* **beacon:** stop Cloudflare logging senders' IP addresses ([#4018](https://github.com/headroomlabs-ai/headroom/issues/4018)) ([db983ba](https://github.com/headroomlabs-ai/headroom/commit/db983bacc616fec3d622e8a039b47135b1ad4166))
* **cache:** keep cache mode when Claude Code re-serializes its last reply ([#4003](https://github.com/headroomlabs-ai/headroom/issues/4003)) ([aeb09f8](https://github.com/headroomlabs-ai/headroom/commit/aeb09f8d1884318d27b05b440b44c603e1c0d727))
* **cache:** retain prefix trackers for the provider cache lifetime ([#4023](https://github.com/headroomlabs-ai/headroom/issues/4023)) ([9553d42](https://github.com/headroomlabs-ai/headroom/commit/9553d4292f949224105bfee8c29f4979a2c3092a))
* **cache:** stop Claude Code forks from cold-starting the conversation's lineage ([#4043](https://github.com/headroomlabs-ai/headroom/issues/4043)) ([1cf4d05](https://github.com/headroomlabs-ai/headroom/commit/1cf4d053d2bae276280dd3b71ebcf00cfd4d9cfc))
* **ccr:** serve headroom_retrieve when the model calls it alongside client tools ([#4034](https://github.com/headroomlabs-ai/headroom/issues/4034)) ([01d9194](https://github.com/headroomlabs-ai/headroom/commit/01d9194854233ef6ed04005cf0a5b8c32bf65d6d))
* **cli:** name the broken Codex config, write init configs atomically, keep the identity check ([#4129](https://github.com/headroomlabs-ai/headroom/issues/4129)) ([976aa71](https://github.com/headroomlabs-ai/headroom/commit/976aa714ef3e19174dc0cb586cee7b20d064e4ef))
* **cli:** pass configured SSL context to stdlib urlopen calls ([#4011](https://github.com/headroomlabs-ai/headroom/issues/4011)) ([22d0905](https://github.com/headroomlabs-ai/headroom/commit/22d0905a73d1498e1a3658427687416373c1d4a1))
* **cli:** say why the proxy failed to start ([#4120](https://github.com/headroomlabs-ai/headroom/issues/4120)) ([f3d240b](https://github.com/headroomlabs-ai/headroom/commit/f3d240bcae5f12d87925b5fa46d36eecff19ba2d))
* **codex:** make unwrap codex remove headroom init routing ([#3920](https://github.com/headroomlabs-ai/headroom/issues/3920)) ([3260795](https://github.com/headroomlabs-ai/headroom/commit/326079517b40d2bbec6d2c7a453b22be9b8b6755))
* **codex:** preserve auth.json API keys through Headroom ([#3355](https://github.com/headroomlabs-ai/headroom/issues/3355)) ([a6523b1](https://github.com/headroomlabs-ai/headroom/commit/a6523b19678af49ed1039fe946ae0cfee2181509))
* **copilot:** honour GitHub's advertised Business/Enterprise host by default ([#4155](https://github.com/headroomlabs-ai/headroom/issues/4155)) ([1dc7a18](https://github.com/headroomlabs-ai/headroom/commit/1dc7a183f55db35188aefa95f9cd4aed18377862))
* **copilot:** send VS Code next-edit requests to the completions host ([#4188](https://github.com/headroomlabs-ai/headroom/issues/4188)) ([22a1296](https://github.com/headroomlabs-ai/headroom/commit/22a1296cfabc855f9bc6e36a1bcb0f9e788f75a5))
* **dashboard:** keep savings profile visible in light mode ([#2544](https://github.com/headroomlabs-ai/headroom/issues/2544)) ([4e4f49d](https://github.com/headroomlabs-ai/headroom/commit/4e4f49d058846c44ae6061edd5a53776c03a0507))
* **dashboard:** show the effective value in settings enum selects ([#4032](https://github.com/headroomlabs-ai/headroom/issues/4032)) ([20ce054](https://github.com/headroomlabs-ai/headroom/commit/20ce054f8d34af50106daa0c8aa518231e17004b))
* **deps:** bump quinn-proto to 0.11.19 for RUSTSEC-2026-0338..0342 ([#4178](https://github.com/headroomlabs-ai/headroom/issues/4178)) ([49751ec](https://github.com/headroomlabs-ai/headroom/commit/49751ec4c797c9ff8ae7e3cdfed6c8372c7fbfcd))
* **deps:** clear the two high npm advisories failing the Security workflow ([#4004](https://github.com/headroomlabs-ai/headroom/issues/4004)) ([5a516b5](https://github.com/headroomlabs-ai/headroom/commit/5a516b54afd50156521638645a9063992e395a7b))
* **deps:** recommend headroom-ai for optional extras ([#4046](https://github.com/headroomlabs-ai/headroom/issues/4046)) ([f1bc260](https://github.com/headroomlabs-ai/headroom/commit/f1bc260948c159549d6937e9c4d2cf969256f2bb))
* **deps:** support Intel macOS ONNX Runtime resolution ([#3823](https://github.com/headroomlabs-ai/headroom/issues/3823)) ([51ec6e8](https://github.com/headroomlabs-ai/headroom/commit/51ec6e8ffef8d3c76b0dc7b283c8c5eabcd6acc2))
* **docker:** adds mount for the litellm config dir ([#2454](https://github.com/headroomlabs-ai/headroom/issues/2454)) ([64a661d](https://github.com/headroomlabs-ai/headroom/commit/64a661d5b4898d97061bfcaa10caad477b319b37))
* **gateway:** report why /v1/compress/response rejected a body ([#4081](https://github.com/headroomlabs-ai/headroom/issues/4081)) ([5cac7ab](https://github.com/headroomlabs-ai/headroom/commit/5cac7ab693c2f1e3d8dbbe4756f0e7f6fa0687d6))
* **grok:** attribute api.x.ai chat outcomes as provider xai, recognize grok-shell UA ([#2626](https://github.com/headroomlabs-ai/headroom/issues/2626)) ([b1fb162](https://github.com/headroomlabs-ai/headroom/commit/b1fb162b622327102832f15b2ca14a4613da9fcd))
* **install/windows:** back persistent-service with an always-on task ([#1866](https://github.com/headroomlabs-ai/headroom/issues/1866)) ([#2460](https://github.com/headroomlabs-ai/headroom/issues/2460)) ([5682883](https://github.com/headroomlabs-ai/headroom/commit/5682883bb03472caeb510d6ff84070d5558d0f62))
* **install:** distinguish protocol targets in status ([#4040](https://github.com/headroomlabs-ai/headroom/issues/4040)) ([79f2c27](https://github.com/headroomlabs-ai/headroom/commit/79f2c2781a1e6d5a13c75ae233e01c6d8d910ef1))
* **install:** keep an explicitly empty dashboard allowlist on Windows PowerShell 5.1 ([#4012](https://github.com/headroomlabs-ai/headroom/issues/4012)) ([c195a12](https://github.com/headroomlabs-ai/headroom/commit/c195a1220f8d3525879c87486bd63d96e870e648))
* **install:** preserve OpenCode edits during reactivation ([#4022](https://github.com/headroomlabs-ai/headroom/issues/4022)) ([40955b0](https://github.com/headroomlabs-ai/headroom/commit/40955b0eef2e509aad1a200db9cfa0762ca457ce))
* **learn:** decode sanitized pattern-id markers and keep visible-text dedup keys ([#3956](https://github.com/headroomlabs-ai/headroom/issues/3956)) ([ec1ba70](https://github.com/headroomlabs-ai/headroom/commit/ec1ba70c974fb0729870bfd444cdc1152a1b4301))
* **learn:** make live traffic learning use the shared error classifier ([#4110](https://github.com/headroomlabs-ai/headroom/issues/4110)) ([e6eaa41](https://github.com/headroomlabs-ai/headroom/commit/e6eaa411791750884a7eb2594d0b86f9e4100f81))
* **learn:** pin the learned verbosity level on a cache-mode proxy ([#4033](https://github.com/headroomlabs-ai/headroom/issues/4033)) ([71663b4](https://github.com/headroomlabs-ai/headroom/commit/71663b44e26fc2e0ad7d52c0b264aa7500926900))
* **logging:** add payload-safe helpers for exceptions, URLs, ids and repeat warnings ([#4138](https://github.com/headroomlabs-ai/headroom/issues/4138)) ([bebe559](https://github.com/headroomlabs-ai/headroom/commit/bebe5593ea4abaf326215c7236586b38e7b325a5))
* **onnx:** stop magika's ORT intra-op pool from spinning idle cores ([#4189](https://github.com/headroomlabs-ai/headroom/issues/4189)) ([2016dc6](https://github.com/headroomlabs-ai/headroom/commit/2016dc6d6064926790b9c843fbf1798d2e660524))
* **openclaw:** preserve tool-call thought signatures ([#4038](https://github.com/headroomlabs-ai/headroom/issues/4038)) ([37f3f9e](https://github.com/headroomlabs-ai/headroom/commit/37f3f9efe16f6b1ff94e03dbae85a27e387097a2))
* **plugins/openclaw:** keep compression system-prompt notice cache-stable ([#3811](https://github.com/headroomlabs-ai/headroom/issues/3811)) ([f885187](https://github.com/headroomlabs-ai/headroom/commit/f8851878a4feb0b64df8a5b22a89ebb198199bdf))
* **pricing:** reconcile cache billing with model-specific LiteLLM rates ([#3033](https://github.com/headroomlabs-ai/headroom/issues/3033)) ([463c1a4](https://github.com/headroomlabs-ai/headroom/commit/463c1a43e30fc33cb256a3f455daf28043e53b05))
* **providers:** drop the shadowed POST /v1/messages route spec ([#4075](https://github.com/headroomlabs-ai/headroom/issues/4075)) ([69a16cb](https://github.com/headroomlabs-ai/headroom/commit/69a16cb59c0fe4b8233caf5824e34e5772f48d81))
* **proxy/bedrock:** record the real upstream status on InvokeModel outcomes ([#4025](https://github.com/headroomlabs-ai/headroom/issues/4025)) ([159daa2](https://github.com/headroomlabs-ai/headroom/commit/159daa25a0886fb5c5808e37d62fe8cf4971290a))
* **proxy/streaming:** tolerate malformed upstream SSE events ([#2558](https://github.com/headroomlabs-ai/headroom/issues/2558)) ([d091fbd](https://github.com/headroomlabs-ai/headroom/commit/d091fbd9f2ccc522de87350c0bc7a85f0de230eb))
* **proxy:** astgrep disk verify truncation ([#3192](https://github.com/headroomlabs-ai/headroom/issues/3192)) ([1fb4cba](https://github.com/headroomlabs-ai/headroom/commit/1fb4cbaea0dcc62aa092bac3af04991d994207d0))
* **proxy:** break the compact-every-turn loop near the real context window ([#2942](https://github.com/headroomlabs-ai/headroom/issues/2942)) ([76cceeb](https://github.com/headroomlabs-ai/headroom/commit/76cceeb48728a4f179626e43f1ec23d1f7cebd79))
* **proxy:** classify failed streams as failed requests ([#3747](https://github.com/headroomlabs-ai/headroom/issues/3747)) ([42d4f58](https://github.com/headroomlabs-ai/headroom/commit/42d4f58b434bdca8f81cabf5f00d6e8e02a7fb2c))
* **proxy:** don't retry a 429/529 that cannot succeed within the backoff cap ([#3992](https://github.com/headroomlabs-ai/headroom/issues/3992)) ([a961a6f](https://github.com/headroomlabs-ai/headroom/commit/a961a6fea083a9a739df40d1371e1e7ec108516d))
* **proxy:** don't send a memory continuation with unanswered client tool calls ([#4009](https://github.com/headroomlabs-ai/headroom/issues/4009)) ([#4013](https://github.com/headroomlabs-ai/headroom/issues/4013)) ([87e05b6](https://github.com/headroomlabs-ai/headroom/commit/87e05b68b8aa578f1439abfc8006b38cd09db14d))
* **proxy:** forward x-litellm-key-* headers on streaming path ([#2532](https://github.com/headroomlabs-ai/headroom/issues/2532)) ([33ade5b](https://github.com/headroomlabs-ai/headroom/commit/33ade5b0e1019adf34d9fd888cc105d4bc23935e))
* **proxy:** ignore defer_loading when measuring a turn hook's tool delta ([#4056](https://github.com/headroomlabs-ai/headroom/issues/4056)) ([f8212a3](https://github.com/headroomlabs-ai/headroom/commit/f8212a39dcc5b03a75e98b60a8ecdef81a0f48ed))
* **proxy:** keep Claude Haiku 5.5 mid-conversation system messages in place ([#4153](https://github.com/headroomlabs-ai/headroom/issues/4153)) ([a9eb2a7](https://github.com/headroomlabs-ai/headroom/commit/a9eb2a7b6fe6b75042646284109846da46939649))
* **proxy:** keep leading Anthropic system payloads valid ([#3671](https://github.com/headroomlabs-ai/headroom/issues/3671)) ([d9e29bb](https://github.com/headroomlabs-ai/headroom/commit/d9e29bb2600a746dea80caa7721f0fb98109589c))
* **proxy:** log the savings and metrics failures that currently vanish ([#4084](https://github.com/headroomlabs-ai/headroom/issues/4084)) ([2800932](https://github.com/headroomlabs-ai/headroom/commit/2800932e1827400cf41be1cff6154f78f691ccce))
* **proxy:** read stream cache usage from message_delta; keep Fireworks sessions on one replica ([#4174](https://github.com/headroomlabs-ai/headroom/issues/4174)) ([30b22df](https://github.com/headroomlabs-ai/headroom/commit/30b22df7fda6163c576c8f720982bf1ca48762c3))
* **proxy:** record the provider's billed input count on streamed turns ([#4052](https://github.com/headroomlabs-ai/headroom/issues/4052)) ([a9815bb](https://github.com/headroomlabs-ai/headroom/commit/a9815bbb5fa2d2347ceeeac0f01cc9f041e2ded2))
* **proxy:** say why proxy.log is missing and why a knob or extension was ignored ([#4088](https://github.com/headroomlabs-ai/headroom/issues/4088)) ([72302a3](https://github.com/headroomlabs-ai/headroom/commit/72302a3998104a400765fa7e21177ed59f429f38))
* **release:** synchronize editable uv lock version ([#4054](https://github.com/headroomlabs-ai/headroom/issues/4054)) ([3f99066](https://github.com/headroomlabs-ai/headroom/commit/3f990663cca5b9dd2ed0ca26343b0619bbab0aa7))
* **router:** bound ML compression per request, not just per block ([#3721](https://github.com/headroomlabs-ai/headroom/issues/3721)) ([f37980f](https://github.com/headroomlabs-ai/headroom/commit/f37980f7f7612e7ae58b4f3b5b98f185e216fd91))
* **router:** preserve nested JSON records through compression ([#3680](https://github.com/headroomlabs-ai/headroom/issues/3680)) ([fd06703](https://github.com/headroomlabs-ai/headroom/commit/fd067033da185f1abf48ea58e63c6d71d4d11ec1))
* **savings,ccr:** log the ledger and MCP failures that are swallowed silently ([#4105](https://github.com/headroomlabs-ai/headroom/issues/4105)) ([97680e7](https://github.com/headroomlabs-ai/headroom/commit/97680e7782423308b8e35c5560fea5b1d9434e1b))
* **savings:** don't let a thin holdout arm decide the headline number ([#3127](https://github.com/headroomlabs-ai/headroom/issues/3127)) ([2a12e03](https://github.com/headroomlabs-ai/headroom/commit/2a12e035a3239bdfbb4fe75e1246923c144aabef))
* **security:** resolve 23 open CodeQL alerts ([#4045](https://github.com/headroomlabs-ai/headroom/issues/4045)) ([a88e2d5](https://github.com/headroomlabs-ai/headroom/commit/a88e2d51452f7a2fa1882639585d482e1f05d92f))
* **security:** resolve high-severity CodeQL alerts ([#4005](https://github.com/headroomlabs-ai/headroom/issues/4005)) ([dea9092](https://github.com/headroomlabs-ai/headroom/commit/dea9092e19385f286b7f67a64f4d85de2708d756))
* **smart-crusher:** preserve wrapped retrieval results in apply ([#4149](https://github.com/headroomlabs-ai/headroom/issues/4149)) ([9762a14](https://github.com/headroomlabs-ai/headroom/commit/9762a14a40bde4d3f58a027c086b6ac75fbd5ed2))
* **subscription:** log a failed OTEL window update instead of passing silently ([#4131](https://github.com/headroomlabs-ai/headroom/issues/4131)) ([7d9dd55](https://github.com/headroomlabs-ai/headroom/commit/7d9dd55e7c4bbd2a95b054de7e5722c4cf20ce50))
* **toin:** make diagnostic pattern identifiers addressable ([#4021](https://github.com/headroomlabs-ai/headroom/issues/4021)) ([def6d41](https://github.com/headroomlabs-ai/headroom/commit/def6d41185d3091d4ef42ae379829087deeaf38f))
* **transforms:** log failed transforms with tracebacks ([#3981](https://github.com/headroomlabs-ai/headroom/issues/3981)) ([a654558](https://github.com/headroomlabs-ai/headroom/commit/a65455804ce6c16670af6fe253bd9f8f6105bfe3))
* **wrap:** carry the shared proxy's extensions over to a dedicated Copilot proxy ([#4154](https://github.com/headroomlabs-ai/headroom/issues/4154)) ([feea130](https://github.com/headroomlabs-ai/headroom/commit/feea130f81953030bda222ffe88abb61fbb60ee8))
* **wrap:** let `wrap opencode` target a third-party OpenAI-compatible upstream ([#3125](https://github.com/headroomlabs-ai/headroom/issues/3125)) ([0d7d61d](https://github.com/headroomlabs-ai/headroom/commit/0d7d61d5ccaee25d399ae3209e8ce067e8673b30))
* **wrap:** reject saved bob gateway URLs the proxy would not route ([#3975](https://github.com/headroomlabs-ai/headroom/issues/3975)) ([944eafc](https://github.com/headroomlabs-ai/headroom/commit/944eafc6d4bcebbe6624cff95681f5af8b257868))
* **wrap:** trim the wrap claude startup banner ([#3900](https://github.com/headroomlabs-ai/headroom/issues/3900)) ([aba75cb](https://github.com/headroomlabs-ai/headroom/commit/aba75cbf6d2fe1e4c728e4af258907d9c28028d0))
* **wrap:** warn when reused proxy ignores compression settings ([#4019](https://github.com/headroomlabs-ai/headroom/issues/4019)) ([278bbc8](https://github.com/headroomlabs-ai/headroom/commit/278bbc8771938eec18e89df942e1594b6ddf41d4))
### Performance Improvements
* **proxy:** avoid eager dependency imports ([#3546](https://github.com/headroomlabs-ai/headroom/issues/3546)) ([59bd482](https://github.com/headroomlabs-ai/headroom/commit/59bd482fa1661293d86834e73fe90f0ee21130c5))
### Code Refactoring
* **backends:** reuse the LiteLLM tool converters in the any-llm backend ([#4076](https://github.com/headroomlabs-ai/headroom/issues/4076)) ([03538f2](https://github.com/headroomlabs-ai/headroom/commit/03538f2f2f55cafc0cec4ddf1b22e3189e2a0a24))
* **cli:** one missing-binary error for every wrap command ([#4122](https://github.com/headroomlabs-ai/headroom/issues/4122)) ([2c2357a](https://github.com/headroomlabs-ai/headroom/commit/2c2357ad342de69d4576f0e38efc58646f054913))
* **cli:** remove test-only and dead helpers from wrap, proxy and mcp ([#4118](https://github.com/headroomlabs-ai/headroom/issues/4118)) ([73f59a3](https://github.com/headroomlabs-ai/headroom/commit/73f59a32ccda8fe9de385031ccd032d1007be650))
* **compression:** deprecate the test-only UniversalCompressor package ([#4095](https://github.com/headroomlabs-ai/headroom/issues/4095)) ([fc8ff5a](https://github.com/headroomlabs-ai/headroom/commit/fc8ff5a7619271ffe306ffad50f2ee936d5d2158))
* **core:** remove unreferenced helpers, attributes and a shadowed module ([#4091](https://github.com/headroomlabs-ai/headroom/issues/4091)) ([08fce18](https://github.com/headroomlabs-ai/headroom/commit/08fce1831067005f048cb81f0033abc17a89e9fd))
* **graph:** drop the bespoke codebase-memory-mcp downloader nothing calls ([#4102](https://github.com/headroomlabs-ai/headroom/issues/4102)) ([30d23fb](https://github.com/headroomlabs-ai/headroom/commit/30d23fb799674a5d9a3c531baf09a307d62c2bf2))
* **mcp_registry:** share spec helpers and fold GrokRegistrar onto the Codex TOML registrar ([#4121](https://github.com/headroomlabs-ai/headroom/issues/4121)) ([6e14ee0](https://github.com/headroomlabs-ai/headroom/commit/6e14ee0bc2dde72378b841f708f73cdf79df6e2d))
* **memory,learn,cache:** remove unreferenced classes, methods and constants ([#4112](https://github.com/headroomlabs-ai/headroom/issues/4112)) ([abbf36f](https://github.com/headroomlabs-ai/headroom/commit/abbf36f052fca643a3cd5f7cadd21b5a7d4bf406))
* **memory:** deprecate the never-wired agent memory writers ([#4101](https://github.com/headroomlabs-ai/headroom/issues/4101)) ([2e497cb](https://github.com/headroomlabs-ai/headroom/commit/2e497cbec3c26c1d2c83adcc94794164cbab3268))
* **memory:** deprecate the orphaned Mem0SystemAdapter ([#4114](https://github.com/headroomlabs-ai/headroom/issues/4114)) ([7387b8c](https://github.com/headroomlabs-ai/headroom/commit/7387b8cc11ecdf4775faa6042e7cc15d114b4942))
* **memory:** drop the unused extraction prompts and tool schemas ([#4100](https://github.com/headroomlabs-ai/headroom/issues/4100)) ([6d23895](https://github.com/headroomlabs-ai/headroom/commit/6d23895dc003e865c3c5d4690853551406e7cdc8))
* **memory:** remove the unused memory budget manager ([#4099](https://github.com/headroomlabs-ai/headroom/issues/4099)) ([e7ac6ca](https://github.com/headroomlabs-ai/headroom/commit/e7ac6ca6f81834549a66fc0832b1ddb2470da245))
* **proxy:** delete the unused memory_tool_adapter module ([#4071](https://github.com/headroomlabs-ai/headroom/issues/4071)) ([7e5d97f](https://github.com/headroomlabs-ai/headroom/commit/7e5d97fe29073af0751cc0abc7bdf6a6d3bd74a2))
* **proxy:** drop the test-only memory ranker and file-backed native memory ops ([#4072](https://github.com/headroomlabs-ai/headroom/issues/4072)) ([fc5ac70](https://github.com/headroomlabs-ai/headroom/commit/fc5ac70b4a1eac8f49d86ad386c76c67bab40372))
* **proxy:** parse HEADROOM_OUTPUT_HOLDOUT in one place ([#4082](https://github.com/headroomlabs-ai/headroom/issues/4082)) ([1a4e419](https://github.com/headroomlabs-ai/headroom/commit/1a4e4194a0b26e4f09026c18ac6b8935c6a99c0c))
* **proxy:** remove dead aliases and wrappers from helpers, body_forwarding, forwarded_headers ([#4080](https://github.com/headroomlabs-ai/headroom/issues/4080)) ([63cc9af](https://github.com/headroomlabs-ai/headroom/commit/63cc9afa9d282aeae127e6af20d9a9efa2eebd7e))
* **proxy:** remove dead wiring and unused re-exports from server.py ([#4073](https://github.com/headroomlabs-ai/headroom/issues/4073)) ([58387c1](https://github.com/headroomlabs-ai/headroom/commit/58387c1174e6f7f526c3677b72986079da554a8a))
* **proxy:** remove test-only and dead helpers from the handlers ([#4117](https://github.com/headroomlabs-ai/headroom/issues/4117)) ([31d378b](https://github.com/headroomlabs-ai/headroom/commit/31d378b0e5337bf8c572ca272e8649762457dc5f))
* **proxy:** remove the unreachable debug branches from the Responses payload compressor ([#4116](https://github.com/headroomlabs-ai/headroom/issues/4116)) ([132cd58](https://github.com/headroomlabs-ai/headroom/commit/132cd583daeb968dd4121f0163677f5b1605f29c))
* **proxy:** remove the unreachable debug branches from the Responses unit router ([#4115](https://github.com/headroomlabs-ai/headroom/issues/4115)) ([25cc2d5](https://github.com/headroomlabs-ai/headroom/commit/25cc2d586316fee5cb67b7a25ef2927198a0ae6b))
* **proxy:** remove unreferenced and test-only helpers ([#4074](https://github.com/headroomlabs-ai/headroom/issues/4074)) ([e5cbec5](https://github.com/headroomlabs-ai/headroom/commit/e5cbec5f1a860eb51e4e49507b8eb26742abba22))
* remove test-only compatibility helpers in rollout and agent_savings ([#4089](https://github.com/headroomlabs-ai/headroom/issues/4089)) ([310c108](https://github.com/headroomlabs-ai/headroom/commit/310c108c24caef1839a538a28878b6709f8987f9))
* remove write-only and test-only code in subscription and install ([#4123](https://github.com/headroomlabs-ai/headroom/issues/4123)) ([c191bee](https://github.com/headroomlabs-ai/headroom/commit/c191beef59cc9bde622cf7db251ac94eb2a20c70))
* **transforms:** deprecate the unused Python AnchorSelector port ([#4104](https://github.com/headroomlabs-ai/headroom/issues/4104)) ([9b1971d](https://github.com/headroomlabs-ai/headroom/commit/9b1971dd82c941d683902014b203de4bf617cc61))
* **transforms:** deprecate unused compress_with_stats, extract_batch and align_for_cache ([#4098](https://github.com/headroomlabs-ai/headroom/issues/4098)) ([e4a1ec1](https://github.com/headroomlabs-ai/headroom/commit/e4a1ec19be787a312624fdca52e2184b9a4127b9))
* **transforms:** drop the Python mirror of the Rust log selector ([#4096](https://github.com/headroomlabs-ai/headroom/issues/4096)) ([a20c76c](https://github.com/headroomlabs-ai/headroom/commit/a20c76c26b15557a1bf176c4ef84f46121550297))
* **transforms:** drop the Python mirror of the Rust search selector ([#4103](https://github.com/headroomlabs-ai/headroom/issues/4103)) ([47f8710](https://github.com/headroomlabs-ai/headroom/commit/47f8710817ddc6612127662714b5fcecf83dc644))
* **transforms:** remove the unused summarize_dropped_items ([#4093](https://github.com/headroomlabs-ai/headroom/issues/4093)) ([eaa7308](https://github.com/headroomlabs-ai/headroom/commit/eaa7308a52620ad803b13c7f66300d7196f63212))
* **transforms:** remove unused convenience wrappers and helpers ([#4097](https://github.com/headroomlabs-ai/headroom/issues/4097)) ([5c72d82](https://github.com/headroomlabs-ai/headroom/commit/5c72d824f4d1ab0d46a960f8f61a14d000482591))
## [0.40.0](https://github.com/headroomlabs-ai/headroom/compare/v0.39.1...v0.40.0) (2026-10-06)
Generated
+151 -66
View File
@@ -606,9 +606,9 @@ dependencies = [
[[package]]
name = "aws-smithy-runtime-api"
version = "1.18.0"
version = "1.19.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9bb0deb40a69de59f7809251cfe1ab16de135f42c49d222d1202b4d0ce19720f"
checksum = "c0730c16f91124c6a2abb4932c77e299288b3dd9f967ea2e9ec48cc6731e87a4"
dependencies = [
"aws-smithy-async",
"aws-smithy-runtime-api-macros",
@@ -797,6 +797,15 @@ dependencies = [
"bit-vec 0.8.0",
]
[[package]]
name = "bit-set"
version = "0.11.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "56d87354e4229f54a44f7bf2435906a4656dba36026ab6eaca629a2c436a691c"
dependencies = [
"bit-vec 0.10.1",
]
[[package]]
name = "bit-vec"
version = "0.8.0"
@@ -812,6 +821,16 @@ dependencies = [
"serde",
]
[[package]]
name = "bit-vec"
version = "0.10.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5727b15fa97d4f4fee0a3b7c3d550ed0269f54329207b86388de918604e31269"
dependencies = [
"borsh",
"serde",
]
[[package]]
name = "bit_field"
version = "0.10.3"
@@ -864,6 +883,30 @@ dependencies = [
"hybrid-array",
]
[[package]]
name = "borsh"
version = "1.8.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "553c5d846a6ba5150c65e3b1b8ec073bcf1abc20f9b7220de384a4443ea4e20a"
dependencies = [
"borsh-derive",
"bytes",
"cfg_aliases",
]
[[package]]
name = "borsh-derive"
version = "1.8.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "12cdfe656708a01f89b451a7d36466e6fe6c414de0aa18fc54f864f6f9ca9f56"
dependencies = [
"once_cell",
"proc-macro-crate",
"proc-macro2",
"quote",
"syn 3.0.3",
]
[[package]]
name = "bstr"
version = "1.13.1"
@@ -944,9 +987,9 @@ dependencies = [
[[package]]
name = "cc"
version = "1.5.1"
version = "1.8.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f360145194ee8e21db5ee7f3fcd4fe52210864c75c985dae33218202c8bbe040"
checksum = "6651c9ed80effdc7db0ff72512157f901af5e3549e341e24b1dd4887d836d838"
dependencies = [
"find-msvc-tools",
"jobserver",
@@ -1179,6 +1222,12 @@ version = "0.8.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
[[package]]
name = "core_detect"
version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7f8f80099a98041a3d1622845c271458a2d73e688351bf3cb999266764b81d48"
[[package]]
name = "core_maths"
version = "0.1.1"
@@ -1616,7 +1665,7 @@ version = "0.19.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d301f5bf187b3c295fce6468d3875037a0bccc5f6b151c63cac2f85babf21912"
dependencies = [
"bit-set",
"bit-set 0.8.0",
"regex-automata",
"regex-syntax",
]
@@ -1848,11 +1897,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
dependencies = [
"cfg-if",
"js-sys",
"libc",
"r-efi 5.3.0",
"wasip2",
"wasm-bindgen",
]
[[package]]
@@ -1862,9 +1909,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
dependencies = [
"cfg-if",
"js-sys",
"libc",
"r-efi 6.0.0",
"rand_core 0.10.1",
"wasm-bindgen",
]
[[package]]
@@ -2009,7 +2058,7 @@ dependencies = [
"aws-sigv4",
"aws-smithy-runtime-api",
"axum",
"base64 0.22.1",
"base64 0.23.1",
"bytes",
"bytesize",
"clap",
@@ -2049,7 +2098,7 @@ dependencies = [
"tracing-subscriber",
"url",
"uuid",
"webpki-roots 1.0.8",
"webpki-roots 1.0.9",
"wiremock",
]
@@ -2215,9 +2264,9 @@ dependencies = [
[[package]]
name = "hyper"
version = "1.11.1"
version = "1.12.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "27b501faa50e7a26c3d3560ca625132f4078a17771f4810baf70475ae48cbe43"
checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c"
dependencies = [
"atomic-waker",
"bytes",
@@ -2249,7 +2298,7 @@ dependencies = [
"tokio",
"tokio-rustls",
"tower-service",
"webpki-roots 1.0.8",
"webpki-roots 1.0.9",
]
[[package]]
@@ -3267,6 +3316,15 @@ dependencies = [
"zerocopy",
]
[[package]]
name = "proc-macro-crate"
version = "3.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f"
dependencies = [
"toml_edit",
]
[[package]]
name = "proc-macro2"
version = "1.0.106"
@@ -3311,16 +3369,17 @@ dependencies = [
[[package]]
name = "proptest"
version = "1.11.0"
version = "1.12.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
checksum = "b8530004ccb15eae51c7e40009fbe317f341f804db54dc033eec1c50be28cfa0"
dependencies = [
"bit-set",
"bit-vec 0.8.0",
"bit-set 0.11.1",
"bit-vec 0.10.1",
"bitflags",
"chacha20",
"core_detect",
"num-traits",
"rand 0.9.4",
"rand_chacha",
"rand 0.10.2",
"rand_xorshift",
"regex-syntax",
"rusty-fork",
@@ -3336,9 +3395,9 @@ checksum = "e0c5ccf5294c6ccd63a74f1565028353830a9c2f5eb0c682c355c471726a6e3f"
[[package]]
name = "pyo3"
version = "0.29.2"
version = "0.29.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4688ddedf473e32662b9b067670129a8afb8c18e351482c70d62ba4a88171e8b"
checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
dependencies = [
"libc",
"once_cell",
@@ -3350,18 +3409,18 @@ dependencies = [
[[package]]
name = "pyo3-build-config"
version = "0.29.2"
version = "0.29.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f41027e41b4bd03f6e60f9f417fe24a6341a6bb744edd62b6f709f2a52ea30e9"
checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
dependencies = [
"target-lexicon",
]
[[package]]
name = "pyo3-ffi"
version = "0.29.2"
version = "0.29.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e591a95526fead067432c3b3a33fc74770b87b1e04e73671090d9c2055a2b327"
checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
dependencies = [
"libc",
"pyo3-build-config",
@@ -3380,9 +3439,9 @@ dependencies = [
[[package]]
name = "pyo3-macros"
version = "0.29.2"
version = "0.29.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "73225868fc1cd84eef2c3c230ddb91273bf1de46aeb8a4248da76d32a0924a1c"
checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
dependencies = [
"proc-macro2",
"pyo3-macros-backend",
@@ -3392,9 +3451,9 @@ dependencies = [
[[package]]
name = "pyo3-macros-backend"
version = "0.29.2"
version = "0.29.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "571575aa3749fa6216757dd47d2a3e7ef360f329a40f0666a9fbd14889024952"
checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
dependencies = [
"heck",
"proc-macro2",
@@ -3445,14 +3504,15 @@ dependencies = [
[[package]]
name = "quinn-proto"
version = "0.11.15"
version = "0.11.19"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4fcb935c5bec503c2f0e306bdd3e58bb9029dcb14fa8d9ac76e3a5256ac0763e"
checksum = "0e750cca55fe4f0439a15d0bb529da9651e79993e8e72c61a899a36d462befbe"
dependencies = [
"bytes",
"getrandom 0.3.4",
"getrandom 0.4.3",
"lru-slab",
"rand 0.9.4",
"rand 0.10.2",
"rand_pcg",
"ring",
"rustc-hash",
"rustls",
@@ -3546,12 +3606,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
[[package]]
name = "rand_xorshift"
version = "0.4.0"
name = "rand_pcg"
version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "513962919efc330f829edb2535844d1b912b0fbe2ca165d613e4e8788bb05a5a"
checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a"
dependencies = [
"rand_core 0.9.5",
"rand_core 0.10.1",
]
[[package]]
name = "rand_xorshift"
version = "0.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "60aa6af80be32871323012e02e6e65f8a7cc7890931ae421d217ad8fe0df2ccf"
dependencies = [
"rand_core 0.10.1",
]
[[package]]
@@ -3766,7 +3835,7 @@ dependencies = [
"wasm-bindgen-futures",
"wasm-streams",
"web-sys",
"webpki-roots 1.0.8",
"webpki-roots 1.0.9",
]
[[package]]
@@ -3853,9 +3922,9 @@ dependencies = [
[[package]]
name = "rustls"
version = "0.23.45"
version = "0.23.46"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf"
dependencies = [
"aws-lc-rs",
"log",
@@ -4023,10 +4092,11 @@ dependencies = [
[[package]]
name = "serde_json"
version = "1.0.151"
version = "1.0.154"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
dependencies = [
"foldhash",
"indexmap",
"itoa",
"memchr",
@@ -4048,9 +4118,9 @@ dependencies = [
[[package]]
name = "serde_spanned"
version = "1.1.1"
version = "1.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6662b5879511e06e8999a8a235d848113e942c9124f211511b16466ee2995f26"
checksum = "4e7523beb55eece201a2356bee0bbca0d1ab466c14c07703b2e0ee6d42cb0c2c"
dependencies = [
"serde_core",
]
@@ -4500,9 +4570,9 @@ dependencies = [
[[package]]
name = "tokio"
version = "1.53.1"
version = "1.53.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"
checksum = "ce3335fa71841cda333a58d7615b03901380ecf09d59b3296d21f8bbac0dde4e"
dependencies = [
"bytes",
"libc",
@@ -4577,9 +4647,9 @@ dependencies = [
[[package]]
name = "tokio-util"
version = "0.7.19"
version = "0.7.20"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52"
checksum = "e464cf451ba96ebfc6f9b6542f17ee8b8956e33f1e40d9690624e59d7a7f8a4b"
dependencies = [
"bytes",
"futures-core",
@@ -4591,9 +4661,9 @@ dependencies = [
[[package]]
name = "toml"
version = "1.1.6+spec-1.1.0"
version = "1.1.8+spec-1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "920602543f0911ab71da12c50d59701da54c196d1a2bf5cb4b75667f137a406a"
checksum = "20489e00e4d8741d6be680764cc12e270655e375a20d1011e844a9c3379e678d"
dependencies = [
"indexmap",
"serde_core",
@@ -4606,27 +4676,39 @@ dependencies = [
[[package]]
name = "toml_datetime"
version = "1.1.1+spec-1.1.0"
version = "1.1.2+spec-1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
checksum = "2b86d767906c6c42421dcba507eb9d203e779497710a47782a224bb871653053"
dependencies = [
"serde_core",
]
[[package]]
name = "toml_parser"
version = "1.1.3+spec-1.1.0"
name = "toml_edit"
version = "0.25.17+spec-1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1d38ac1cf9b95face32296c0a3ede1fdc270627c9d9c02a7274dd6d960dc4d56"
checksum = "e3641d5bbb5349a79e1020a242d251efbc546ad8048d133958323ce9c40a9c9c"
dependencies = [
"indexmap",
"toml_datetime",
"toml_parser",
"winnow",
]
[[package]]
name = "toml_parser"
version = "1.1.5+spec-1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c"
dependencies = [
"winnow",
]
[[package]]
name = "toml_writer"
version = "1.1.2+spec-1.1.0"
version = "1.1.3+spec-1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7d56353a2a665ad0f41a421187180aab746c8c325620617ad883a99a1cbe66d2"
checksum = "06bdbd8cfc056b8d2e2e85f29b56a3bdbecb527cef81eb39e3e7b98af4652770"
[[package]]
name = "tower"
@@ -4843,9 +4925,9 @@ dependencies = [
[[package]]
name = "tree-sitter-language"
version = "0.1.8"
version = "0.1.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ca0d1bf6fdd806e43ae5198f82f527056d359def39e54e67a0f478ac09dac081"
checksum = "d0af592be68c579aa78a16846bd19422978c3c52e438523d45ff5d1bff1f9d4a"
[[package]]
name = "tree-sitter-python"
@@ -5002,7 +5084,7 @@ dependencies = [
"socks",
"ureq-proto",
"utf8-zero",
"webpki-roots 1.0.8",
"webpki-roots 1.0.9",
]
[[package]]
@@ -5055,9 +5137,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
[[package]]
name = "uuid"
version = "1.26.1"
version = "1.28.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2ef6dac1e96601b4fb3acccccff2139741fcb757cb9a36089bf5be91cfb285ce"
checksum = "7cc1186384beb7dd8eedea376413fd654937285ea6c9cfbb928dc3043ea4b606"
dependencies = [
"getrandom 0.4.3",
"js-sys",
@@ -5120,9 +5202,9 @@ dependencies = [
[[package]]
name = "want"
version = "0.3.1"
version = "0.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
checksum = "ec4cdd0dd910afe868b7ef477227d8d538b46b3075031afee8a9f2acb0a2ed0b"
dependencies = [
"try-lock",
]
@@ -5236,14 +5318,14 @@ version = "0.26.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
dependencies = [
"webpki-roots 1.0.8",
"webpki-roots 1.0.9",
]
[[package]]
name = "webpki-roots"
version = "1.0.8"
version = "1.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bf85cb06032201fa7c6f829d7db5a7e5aa45bcc0655327713065f6f0576731bf"
checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a"
dependencies = [
"rustls-pki-types",
]
@@ -5431,6 +5513,9 @@ name = "winnow"
version = "1.0.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0592e1c9d151f854e6fd382574c3a0855250e1d9b2f99d9281c6e6391af352f1"
dependencies = [
"memchr",
]
[[package]]
name = "wiremock"
+2 -2
View File
@@ -624,8 +624,8 @@ prompts, completions, code or file paths. It exists so we can see when a release
regresses a compression ratio across real workloads rather than only our own test
corpus.
Turn it off with `HEADROOM_BEACON=off`, the `DO_NOT_TRACK=1` convention, or
`HEADROOM_OFFLINE=1`. The full field list is in
Turn it off with `HEADROOM_BEACON=off`, `HEADROOM_TELEMETRY=off`, the
`DO_NOT_TRACK=1` convention, or `HEADROOM_OFFLINE=1`. The full field list is in
[the proxy docs](https://docs.headroomlabs.ai/docs/proxy).
## Headroom for teams
+20 -15
View File
@@ -26,17 +26,25 @@ default — with your token.)
## API host & Enterprise / data-residency
Headroom routes wrapped Copilot traffic to GitHub's **generic public host**,
`https://api.githubcopilot.com`, for both `--subscription` and the implicit
OAuth path. That host serves the full model set (including newer models on the
responses API) and matches the routing that worked before 0.23.
Which host a wrapped session talks to depends on the lane:
Headroom deliberately does **not** auto-select a per-account host from
`/copilot_internal/user`. That endpoint advertises a segmented host (e.g.
`api.individual.githubcopilot.com`) that does **not** serve newer models on the
responses API and is not the host the official Copilot client routes with — using
it regressed `headroom wrap copilot` after 0.22.4
([#610](https://github.com/headroomlabs-ai/headroom/issues/610)).
- **`--subscription`, `headroom wrap vscode`, and OpenCode `--copilot-subscription`**
resolve the host from GitHub's token exchange. Business and Enterprise seats
route to the plan host GitHub advertises (`api.business.githubcopilot.com` /
`api.enterprise.githubcopilot.com`), which is what GitHub's own clients use and
the only host an enterprise firewall on GitHub's subscription-based network
routing allows. If that host rejects a model the generic host serves, set
`GITHUB_COPILOT_USE_ADVERTISED_HOST=0` to fold back to the generic host.
Individual seats route to the generic host: `api.individual.githubcopilot.com`
does **not** serve newer models on the responses API, and using it regressed
`headroom wrap copilot` after 0.22.4
([#610](https://github.com/headroomlabs-ai/headroom/issues/610)).
- **The implicit OAuth path** (plain `headroom wrap copilot` with a GitHub login
and no provider key) performs no token exchange at launch and always uses the
**generic public host** `https://api.githubcopilot.com`. On a firewall that
allows only the plan host, use `--subscription` or pin the host as below.
An explicit `GITHUB_COPILOT_API_URL` wins over all of the above.
**Enterprise / data-residency:** if your organization is provisioned on a
dedicated Copilot API host (GitHub Enterprise Cloud with data residency, or an
@@ -48,11 +56,8 @@ export GITHUB_COPILOT_API_URL=https://api.<your-host>.githubcopilot.com
headroom wrap copilot --subscription -- --model gpt-5.4
```
If you operate such an environment and would like Headroom to **auto-detect** the
correct host instead of pinning it, please [open an issue](https://github.com/headroomlabs-ai/headroom/issues/new) —
the intended path is to resolve it from GitHub's token-exchange endpoint (the
source the official Copilot client uses), and we'd want to validate it against a
real enterprise tenant.
The Business and Enterprise plan hosts are detected from GitHub's token-exchange
endpoint (see above); only data-residency and egress-proxy hosts still need the pin.
## Status
@@ -382,7 +382,11 @@ fn session() -> &'static Mutex<Result<Session, String>> {
let spawned = std::thread::Builder::new()
.name("magika-init".into())
.spawn(move || {
let _ = tx.send(Session::new().map_err(|e| e.to_string()));
// One intra-op thread means ORT builds no pool: pool threads
// spin-wait between inferences, burning ~2 cores under light
// load (#4187), and magika's builder has no allow_spinning knob.
let built = Session::builder().with_intra_threads(1).build();
let _ = tx.send(built.map_err(|e| e.to_string()));
});
if let Err(e) = spawned {
tracing::warn!("magika init thread spawn failed: {e}");
@@ -0,0 +1,57 @@
//! Magika must not leave an ONNX Runtime intra-op thread pool behind (#4187).
//!
//! ORT's pool threads spin-wait between inferences, so a pool sized to the
//! core count pegs idle CPUs in a long-lived proxy. The magika session is a
//! process-global singleton and the assertion counts OS threads, so this file
//! holds exactly ONE `#[test]` fn and must run in its own process.
#![cfg(all(feature = "ml", any(target_os = "linux", target_os = "macos")))]
use std::time::Duration;
use headroom_core::transforms::magika_detector::{magika_detect, MagikaDetectorError};
#[cfg(target_os = "linux")]
fn os_thread_count() -> usize {
std::fs::read_dir("/proc/self/task")
.expect("read /proc/self/task")
.count()
}
#[cfg(target_os = "macos")]
fn os_thread_count() -> usize {
let out = std::process::Command::new("ps")
.args(["-M", "-p", &std::process::id().to_string()])
.output()
.expect("run ps -M");
// One header line, then one line per thread.
String::from_utf8_lossy(&out.stdout).lines().count() - 1
}
#[test]
fn magika_session_does_not_spawn_intra_op_pool() {
let before = os_thread_count();
match magika_detect("fn main() { println!(\"hi\"); }") {
Ok(_) => {}
// With an explicit ORT_DYLIB_PATH (as in CI) the runtime is present,
// so an init failure is a real session-build regression, not a skip.
Err(MagikaDetectorError::Init(reason))
if std::env::var("ORT_DYLIB_PATH").map_or(true, |v| v.trim().is_empty()) =>
{
eprintln!("skipping: magika runtime unavailable on this host: {reason}");
return;
}
Err(e) => panic!("magika detection failed: {e}"),
}
// Let the short-lived `magika-init` thread finish exiting.
std::thread::sleep(Duration::from_millis(200));
let after = os_thread_count();
// ORT and macOS may leave up to 2 idle background threads (ORT telemetry,
// libdispatch); neither spins. A pool adds its workers on top (7 on a
// 16-core Mac), but on very small hosts a 1-2 worker pool can hide inside
// this allowance, so a pass there is not proof of no spinning.
let extra = after.saturating_sub(before);
assert!(
extra <= 2,
"magika session left {extra} extra OS thread(s) running (before={before}, after={after})"
);
}
+3 -6
View File
@@ -58,12 +58,9 @@ aws-smithy-runtime-api = { workspace = true }
crc32fast = "1"
# Native savings stats: Bedrock InvokeModel EventStream chunks wrap
# their Anthropic SSE payloads in base64 (`{"bytes": "<b64>"}`);
# the usage-capture tee decodes them. Already in the tree via the
# HTTP stack (reqwest/axum/hyper-util/gcp_auth all pull base64
# 0.22) — promoted to direct for the explicit use, so no new
# major-version bucket. (The AWS crates use `base64-simd`, a
# different crate — this is not that one.)
base64 = "0.22"
# the usage-capture tee decodes them with base64 0.23. The HTTP stack
# may retain its separate 0.22 dependency; the AWS crates use base64-simd.
base64 = "0.23"
# Phase D PR-D3: Prometheus metrics for Bedrock observability. The
# `prometheus` crate's default-features pull in `protobuf`, which we
# don't need (we serve text-format scrapes only), so we disable
+75 -85
View File
@@ -5,53 +5,53 @@
"": {
"name": "headroom-docs",
"dependencies": {
"@radix-ui/react-slot": "1.3.3",
"@radix-ui/react-slot": "1.5.0",
"class-variance-authority": "0.7.1",
"clsx": "2.1.1",
"dotted-map": "^3.1.0",
"fumadocs-core": "16.15.15",
"fumadocs-mdx": "15.4.5",
"fumadocs-twoslash": "^4.0.1",
"fumadocs-typescript": "^5.4.1",
"fumadocs-ui": "16.15.15",
"fumadocs-core": "16.17.1",
"fumadocs-mdx": "15.4.7",
"fumadocs-twoslash": "^4.0.2",
"fumadocs-typescript": "^5.5.1",
"fumadocs-ui": "16.17.1",
"lucide-react": "^1.48.0",
"next": "^16.3.8",
"next": "^16.4.0",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"recharts": "^3.10.1",
"tailwind-merge": "^3.7.0",
},
"devDependencies": {
"@ai-sdk/openai": "^4.0.79",
"@anthropic-ai/sdk": "^0.129.0",
"@ai-sdk/openai": "^4.0.91",
"@anthropic-ai/sdk": "^0.133.0",
"@tailwindcss/postcss": "^4.3.3",
"@types/mdx": "^2.0.14",
"@types/node": "^26.6.3",
"@types/node": "^26.6.5",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"ai": "7.0.119",
"openai": "^7.23.0",
"postcss": "^8.5.28",
"ai": "7.0.137",
"openai": "^7.32.0",
"postcss": "^8.5.29",
"tailwindcss": "^4.2.2",
"typescript": "^7.0.2",
},
},
},
"overrides": {
"postcss": "^8.5.28",
"postcss": "^8.5.29",
},
"packages": {
"@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.97", "", { "dependencies": { "@ai-sdk/provider": "4.0.19", "@ai-sdk/provider-utils": "5.0.50", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-YFS9McgEDHXPwXOWlu1JCylkFyDsgPNLwH9jXgMxdiaur3k6SaIUPKCRSciQQ5LbEZOSb4JAaPYYO7B5Cvq7ow=="],
"@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.110", "", { "dependencies": { "@ai-sdk/provider": "4.0.26", "@ai-sdk/provider-utils": "5.0.58", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-5IwnOR6v7KC+D9eddUqsCobXl/FbLUVb2LaQc/uyuQdpP3/n9s0YLc9zl4/W3IS/R2pjHrqUfCzEAeOu7bFLoQ=="],
"@ai-sdk/openai": ["@ai-sdk/openai@4.0.85", "", { "dependencies": { "@ai-sdk/provider": "4.0.23", "@ai-sdk/provider-utils": "5.0.55" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-bMdfU4LJilFiD6DR6PipbhaSwfy14Uep4cSTRgElsv9Upmv+fNddSeqkBiEfobMlaPNT6zGfMdagonFlqZEtmQ=="],
"@ai-sdk/openai": ["@ai-sdk/openai@4.0.95", "", { "dependencies": { "@ai-sdk/provider": "4.0.28", "@ai-sdk/provider-utils": "5.0.61" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-rx8agb3u+pvDDqvrDYrXfMJVlnlwigNcdgqbwH4oGVi/UZRMNVY+SYhGNI9ynwjmiGcl6QG/QJz73e6qaGL7jg=="],
"@ai-sdk/provider": ["@ai-sdk/provider@4.0.23", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-TdEzgE1ndBGhDDwZcg/WZG3IeUj8Yz7/DkUG4ctMyK5HdNXTEKpjkCdwX8ayvkgluTv7yjnqCdOkB8/q1nfaNQ=="],
"@ai-sdk/provider": ["@ai-sdk/provider@4.0.28", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-6ThcmkJQXSMlBrf6mirIjUUS04Q5/kApbYTOzd5lZfYXLa1XPpnDLxP/G96/DKc00fDIUOW9S2ls0mSzb0+l9w=="],
"@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@5.0.55", "", { "dependencies": { "@ai-sdk/provider": "4.0.23", "@standard-schema/spec": "^1.1.0", "@workflow/serde": "4.1.0", "eventsource-parser": "^3.0.8", "undici": "^7.29.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-VeY9IqwJGcHSmezQTZknaYUT3sRcaXpuIt5VWyGOlJtoc5wkpDPstXZtfa41bGUsbQwCijvN6ASbggUCeTcMkw=="],
"@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@5.0.61", "", { "dependencies": { "@ai-sdk/provider": "4.0.28", "@standard-schema/spec": "^1.1.0", "@workflow/serde": "4.1.0", "eventsource-parser": "^3.0.8", "undici": "^7.29.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-Y+Z3539UXw0ctFDNepTtG23VqBQHr2A6yI2qUxvQcg75DJYgJoD2F9U2Vp5OgQjX7lxto1BLgFtKuOhzrr52vQ=="],
"@alloc/quick-lru": ["@alloc/quick-lru@5.2.0", "", {}, ""],
"@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.129.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-MH7LB20kNpGLUpPTe2OG5XvL/KhX8HUO9XyBaFjgFk6TLS4Xjt0VPIuMKywe7POKKPslX+QxSlVok9e+8kG5Nw=="],
"@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.133.0", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-jlqUN8p8ESTJj+GJnA4KjzbEfF1waEoGzRT8jwytlYGFFgv+/DUQOxlYGvYw10UzhD1kwLqYzxvA3FrTB2YWuQ=="],
"@babel/runtime": ["@babel/runtime@7.29.2", "", {}, ""],
@@ -123,7 +123,7 @@
"@fuma-translate/react": ["@fuma-translate/react@1.0.2", "", { "peerDependencies": { "@types/react": "*", "react": "^19.2.0", "react-dom": "^19.2.0" } }, "sha512-uOiOtBx3nRXR8Nu1GzBf1tApgF1FErDBTHxRIAQeyQdyOoZbrNRN6H4kDCWObY4qyGeGbHydG0DHzgeUgFDMIw=="],
"@fumadocs/tailwind": ["@fumadocs/tailwind@0.1.2", "", { "peerDependencies": { "tailwindcss": "^4.0.0" }, "optionalPeers": ["tailwindcss"] }, "sha512-VppeXgIRXjZMgpf2qijj1hcfxyeYl1s0ok8k6N3jyjiX64M7sDwnt2zGPd6dbfDybgbBvDw6C6J1e42gB5NzsA=="],
"@fumadocs/tailwind": ["@fumadocs/tailwind@0.1.3", "", { "peerDependencies": { "tailwindcss": "^4.0.0" }, "optionalPeers": ["tailwindcss"] }, "sha512-gDgLbTnY5b+nogCg2y/pP7GsaQS4Zt/0vftJAu07Wy7Wsb3/lwd9GwoGqccCnPElTFwMG+pPwrmHXBPexEfE8A=="],
"@fumari/image-size": ["@fumari/image-size@0.1.1", "", {}, "sha512-iaiV2wyzJ4mW358NX4CX3yGit+WjKYzpaQ+rldK9BjL/5jFpeV6ruWnZVq7MEyMn3Gd0DLi8g/79NZAAQaGscw=="],
@@ -255,7 +255,7 @@
"@radix-ui/react-scroll-area": ["@radix-ui/react-scroll-area@1.2.18", "", { "dependencies": { "@radix-ui/number": "1.1.3", "@radix-ui/primitive": "1.1.7", "@radix-ui/react-compose-refs": "1.1.5", "@radix-ui/react-context": "1.2.2", "@radix-ui/react-direction": "1.1.4", "@radix-ui/react-presence": "1.1.10", "@radix-ui/react-primitive": "2.1.10", "@radix-ui/react-use-callback-ref": "1.1.4", "@radix-ui/react-use-layout-effect": "1.1.4" }, "peerDependencies": { "@types/react": "*", "@types/react-dom": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react", "@types/react-dom"] }, "sha512-Zn5Cd171wxsO3Dfg8HaW6RifTb9CYTKQJHs/G4+LN1GfmJpaQMZQyQxMprVPHpaz7QY4l9BxK2JwQuzHsXC8nA=="],
"@radix-ui/react-slot": ["@radix-ui/react-slot@1.3.3", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.5" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-qx7oqnYbxnK9kYI9m317qmFmEgo6ywqWvbTogdj7cL9p3/yx4M48p7Rnw5z3H890cL/ow/EeWJsuTykeZVXP5Q=="],
"@radix-ui/react-slot": ["@radix-ui/react-slot@1.5.0", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.5" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-tyYd9ddPXAysAbdbD9eYxgwpCSv6f3PncqVSNKQFSR5lcJVLz3cb/pANDoYrLiHBpXv7skortyUgGUWsYuPPFQ=="],
"@radix-ui/react-tabs": ["@radix-ui/react-tabs@1.1.21", "", { "dependencies": { "@radix-ui/primitive": "1.1.7", "@radix-ui/react-context": "1.2.2", "@radix-ui/react-direction": "1.1.4", "@radix-ui/react-id": "1.1.4", "@radix-ui/react-presence": "1.1.10", "@radix-ui/react-primitive": "2.1.10", "@radix-ui/react-roving-focus": "1.1.19", "@radix-ui/react-use-controllable-state": "1.2.6" }, "peerDependencies": { "@types/react": "*", "@types/react-dom": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react", "@types/react-dom"] }, "sha512-UKxJlZid7FVtsk/WTxj4i4uSEgj2Au+KBbS7SQyTlzMhhn+86Cz3tISZdTa87bfEfcuvZezf2ZsxD4xuEKtkog=="],
@@ -281,19 +281,19 @@
"@reduxjs/toolkit": ["@reduxjs/toolkit@2.11.2", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "@standard-schema/utils": "^0.3.0", "immer": "^11.0.0", "redux": "^5.0.1", "redux-thunk": "^3.1.0", "reselect": "^5.1.0" }, "peerDependencies": { "react": "^16.9.0 || ^17.0.0 || ^18 || ^19", "react-redux": "^7.2.1 || ^8.1.3 || ^9.0.0" } }, ""],
"@shikijs/core": ["@shikijs/core@4.4.3", "", { "dependencies": { "@shikijs/primitive": "4.4.3", "@shikijs/types": "4.4.3", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5", "hast-util-to-html": "^9.0.5" } }, "sha512-QCR4q2ZO/ILJEuwiBMel4wdcTDb1JGwfjKTxPDF6x8ixOaluPrVqIn06C99AcRPhmYlBR56d/Fb+GN58GzExpg=="],
"@shikijs/core": ["@shikijs/core@4.5.0", "", { "dependencies": { "@shikijs/primitive": "4.5.0", "@shikijs/types": "4.5.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5", "hast-util-to-html": "^9.0.5" } }, "sha512-6CIgwq+bt2JZ3OSjb/nBkkwEf/CfpHcbam+Mg5Pllco7HAGRQ2/EFhZrrJtbyNTgKwknfVS+llsXGygiDGwJWw=="],
"@shikijs/engine-javascript": ["@shikijs/engine-javascript@4.4.3", "", { "dependencies": { "@shikijs/types": "4.4.3", "@shikijs/vscode-textmate": "^10.0.2", "oniguruma-to-es": "^4.3.6" } }, "sha512-FbOjFJp9VLdo1Wevs10BBtVxiTWwNLqZh5Gkhjgda/ioL15YOgeSl9n+6XMa3qRlPQzfhFNe641SrynFHYG0nQ=="],
"@shikijs/engine-javascript": ["@shikijs/engine-javascript@4.5.0", "", { "dependencies": { "@shikijs/types": "4.5.0", "@shikijs/vscode-textmate": "^10.0.2", "oniguruma-to-es": "^4.3.6" } }, "sha512-Ed6UdEj84LyYkwnxM5CvSMWAD+id9ExTYri0/+x41U9zrgNifPSS9lZm0JqBP0VfYI8yr8tY5nbNq9+p9R0kFA=="],
"@shikijs/engine-oniguruma": ["@shikijs/engine-oniguruma@4.4.3", "", { "dependencies": { "@shikijs/types": "4.4.3", "@shikijs/vscode-textmate": "^10.0.2" } }, "sha512-EcOQkxdxGQrc1Row/cC2c96/v1dbZqGnEVu1qTuT/MJmp6+cXCvQussowVmCv5Tqr3KuY3c7IbM6HTW3LJ1k9w=="],
"@shikijs/engine-oniguruma": ["@shikijs/engine-oniguruma@4.5.0", "", { "dependencies": { "@shikijs/types": "4.5.0", "@shikijs/vscode-textmate": "^10.0.2" } }, "sha512-dKVmbJecVdB9recl8a/CU4jdpNXyjJQrIcesIkpS70s5HS02ohpnCSpMUbotPnEUzbAcLQ+S4hwZYbkBBiTcJw=="],
"@shikijs/langs": ["@shikijs/langs@4.4.3", "", { "dependencies": { "@shikijs/types": "4.4.3" } }, "sha512-ePic0yfAJGOF83D5wBHK/00EjK65oahBYxFk5epgq33WRv7X9UuxLEV8PtR0szC0z8dl7INIpIodB99JRFlR+A=="],
"@shikijs/langs": ["@shikijs/langs@4.5.0", "", { "dependencies": { "@shikijs/types": "4.5.0" } }, "sha512-wwBTqwduXSz0X4v9Qa2EWeFaYJEw1clCncWjoRNQRbVDu3SPRTRWucnouYapKj3b8Q+sk/41Vbc4B5c8nuYzLA=="],
"@shikijs/primitive": ["@shikijs/primitive@4.4.3", "", { "dependencies": { "@shikijs/types": "4.4.3", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5" } }, "sha512-m0wBeLDQDeIxRdUmrCPdQqfuUamDwRL5isCfYbguKD6NiaKpVbsv+3J81DyIKgNW5h4WAIIr8T4EkgQrBBxvaQ=="],
"@shikijs/primitive": ["@shikijs/primitive@4.5.0", "", { "dependencies": { "@shikijs/types": "4.5.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5" } }, "sha512-UM7ShlA8oz0OWxLLO8BmO9Ip6fVqdkt8yF0EH7nOCqHfrx1eEAzF0ZUVK7L+I8NEgeu1PEWSRlxaiPPeCb4iDg=="],
"@shikijs/themes": ["@shikijs/themes@4.4.3", "", { "dependencies": { "@shikijs/types": "4.4.3" } }, "sha512-w8UHjeUnIR965KMWJHUPXOc2mNJUnK3vpVLYLvw5IYU2mnTTJ89E24OrJDBNiJDQ0qzb0tc4l7mrIXx5cFeIyw=="],
"@shikijs/themes": ["@shikijs/themes@4.5.0", "", { "dependencies": { "@shikijs/types": "4.5.0" } }, "sha512-zGb87H3UBbpuI4yoh5UguB1XbU+2BDU3kflM7UfZ+Cy2hWo9lBtqjSVK20gmLY6ukYl040hAypGXMgud9vul8Q=="],
"@shikijs/types": ["@shikijs/types@4.4.3", "", { "dependencies": { "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5" } }, "sha512-UEJxmRR++MAGR6hugn0vgVS2W/6lWAts84FFSrnlH9sP0LNol7E5+NQ792pH8liWUhyMyjhTgSUH3k7iD7tc5g=="],
"@shikijs/types": ["@shikijs/types@4.5.0", "", { "dependencies": { "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5" } }, "sha512-drtPrtD8N0DENyD2cyt6Ajy+IWsiCLgMxODwLTpvH1UsN6a9jf90tNTPjqwHvA+0Lzu9e0txk8DjfqH1p9UJRw=="],
"@shikijs/vscode-textmate": ["@shikijs/vscode-textmate@10.0.2", "", {}, ""],
@@ -375,7 +375,7 @@
"@types/ms": ["@types/ms@2.1.0", "", {}, ""],
"@types/node": ["@types/node@26.6.4", "", { "dependencies": { "undici-types": "~8.9.0" } }, "sha512-ldVPDCzj7fsaGZrLB0NuHuTvJcsNasysBAqMolr/cgxrLd1xbqxIr3XJiPnHHJUCxj5sNF1vnRj9aWnrVh5Jcg=="],
"@types/node": ["@types/node@26.6.5", "", { "dependencies": { "undici-types": "~8.9.0" } }, "sha512-uMzsv9stDdofIZBx4UGh4Z9ZgXnGC9seRDscilBcTHAeOFk67MZg/k9bWVfO+bk4qZmG+l52hRnLwUiH2LnJTg=="],
"@types/react": ["@types/react@19.3.0", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg=="],
@@ -431,37 +431,37 @@
"@workflow/serde": ["@workflow/serde@4.1.0", "", {}, "sha512-pav4F2BoirECWR7Nf1TKt+2eETcBj7jj4cBefQ8VXQCA6NPkaKeLfj/zMgi+3zYV5ZIBT4GuUiphsj0/b9hPQQ=="],
"@yuku-analyzer/binding-android-arm64": ["@yuku-analyzer/binding-android-arm64@0.10.2", "", { "os": "android", "cpu": "arm64" }, "sha512-xt4Vy3RTBw1NfszBlf4A0Rr6ZjA/th2Pj9XlWFLQHW9A1qOCtxNCoIWSzn/INtnZLMB4jO2gWdEtSaHUtK73wA=="],
"@yuku-core/binding-android-arm64": ["@yuku-core/binding-android-arm64@0.17.0", "", { "os": "android", "cpu": "arm64" }, "sha512-Uge3U7s9vdCcYb9IiIWBIQmGEttlvWkvWYb9Qu6iUNS2IhAu4/D/g4ucbEmjemkflWYGpWsKZlX+JxcacIlR+g=="],
"@yuku-analyzer/binding-darwin-arm64": ["@yuku-analyzer/binding-darwin-arm64@0.10.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-ftokSqvYXZxfmA/bfIbp8c1BJ8QxNax371kUOQNFyvR5hmtKqQyTqSKtMk+WaixHM3w4tKj/JdyY+ud1bGamXA=="],
"@yuku-core/binding-darwin-arm64": ["@yuku-core/binding-darwin-arm64@0.17.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-jpWhRhfsAFUKXR/dUFoA9NgHeeIl5Yn0hmBEDt4QUEmnYuYZSDXeKQeSCazvIvfzbI0lyIkFSf5/TQeRPwiNuA=="],
"@yuku-analyzer/binding-darwin-x64": ["@yuku-analyzer/binding-darwin-x64@0.10.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-yUrmmhmF5R4Xmbfo8gUxJKr3YbvbLcE2JvLhDLzFJkMN29/fGm6K3dZX6YpNecfgBDnQ+VywGp8K9xjRaBFZ3Q=="],
"@yuku-core/binding-darwin-x64": ["@yuku-core/binding-darwin-x64@0.17.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-AoWoVw8rktzCHXvpoygUu2QZ37LVlCp77p0oZ8EijCMUIaWzTMNUnkRGosEGvzXJOOpzB4wuXYVkphcV55Er+g=="],
"@yuku-analyzer/binding-freebsd-x64": ["@yuku-analyzer/binding-freebsd-x64@0.10.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-cy9+KvVoK5Xad3Vs5pLwAeZf3JC/1y0XJElgv1q6g7W7g/n52FRjedpYmQiJeMZdnhJiAshq7Vz/Xj3jC5Ns2Q=="],
"@yuku-core/binding-freebsd-x64": ["@yuku-core/binding-freebsd-x64@0.17.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-CpyBhwZSzkRX6ZPt3AYVlG0TYk11cTP6rZ7Rz0Ux1BLxHgy4TmEW4UGsiKnL5FMAY/nM3HudevWmvaUVV4Qgng=="],
"@yuku-analyzer/binding-linux-arm-gnu": ["@yuku-analyzer/binding-linux-arm-gnu@0.10.2", "", { "os": "linux", "cpu": "arm" }, "sha512-AgVZ6VCV2XP4yHCwyv78KLV76gcu2neiEF2+RBTPQN7sqYY+bLvMxphGPmfG+9qk5Uf1PJAhZYIUnMGVbbRCZw=="],
"@yuku-core/binding-linux-arm-gnu": ["@yuku-core/binding-linux-arm-gnu@0.17.0", "", { "os": "linux", "cpu": "arm" }, "sha512-H6SQK917PjtWpbQmqUsRAqDDToutDqoXWzLKKAFY+6PSfNnzRPLrydm6SG/GkHT91L8Z2/yJPwXzzF98t1UlbQ=="],
"@yuku-analyzer/binding-linux-arm-musl": ["@yuku-analyzer/binding-linux-arm-musl@0.10.2", "", { "os": "linux", "cpu": "arm" }, "sha512-5qAj2GjoSN6+HuH75+g5r40CFhWmMvH0K8VKWmPfQyOgA/LonoDMr5H5O5feJwzdnfdCytPDAh1RAf7/SSg7dg=="],
"@yuku-core/binding-linux-arm-musl": ["@yuku-core/binding-linux-arm-musl@0.17.0", "", { "os": "linux", "cpu": "arm" }, "sha512-sAxyv9p/3+fxJgXcUsaJ+8IRQWvZ4F264Gx7Kj/VBuIQX95Ih7jP/zUZPGr2UM/3NHFnXIb74Rhyuk6WLufIrQ=="],
"@yuku-analyzer/binding-linux-arm64-gnu": ["@yuku-analyzer/binding-linux-arm64-gnu@0.10.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-eJvQ4Ja5oPf/HOjmBkCLYyhOHUkL7U+iMAN8sX44x8exBBpPRyqnhEgTsuU73HzxPLrGPdRhybFnAE63Omib/Q=="],
"@yuku-core/binding-linux-arm64-gnu": ["@yuku-core/binding-linux-arm64-gnu@0.17.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-hDcx5Nt04jMwkllwZVtxiWt1qQI5gCqaFcT1JLP6Lw9eOqx1Yt8p21NuqZuqknmnW5napB3dSwF7Op+eySHdrQ=="],
"@yuku-analyzer/binding-linux-arm64-musl": ["@yuku-analyzer/binding-linux-arm64-musl@0.10.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-TppF2j194mOQ/kBXvNr9u5TYO+eR9r8ieg4lTIEyJIVYHAR9GWeB0oFHLcJiLXVa3qUJGzE4bmzSntCW5ylA7A=="],
"@yuku-core/binding-linux-arm64-musl": ["@yuku-core/binding-linux-arm64-musl@0.17.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-SGWvwtPe3uXVGjpKk6LTjO4ieGzad/a5h3cbSeduSIiNDfotM200kifB5cPUfg2LhfbM4uCImsApYZOqXW8lkw=="],
"@yuku-analyzer/binding-linux-x64-gnu": ["@yuku-analyzer/binding-linux-x64-gnu@0.10.2", "", { "os": "linux", "cpu": "x64" }, "sha512-03xu6ocJuwhm1a/JKmrHiaJUO1Oj86rABsm4FAl8AvfewfW/9idIUmPiFxZfb6RfiIONegebsTGJhFx0NbBNpA=="],
"@yuku-core/binding-linux-x64-gnu": ["@yuku-core/binding-linux-x64-gnu@0.17.0", "", { "os": "linux", "cpu": "x64" }, "sha512-Vq258yq8+UZQwdD26b6lz9FtqwHwOVWyjy+lcbYKlAhFuN/0FNO2UzlkG5F/0pXR0iRK/Xyxkq5IZpLJHS+2HQ=="],
"@yuku-analyzer/binding-linux-x64-musl": ["@yuku-analyzer/binding-linux-x64-musl@0.10.2", "", { "os": "linux", "cpu": "x64" }, "sha512-f7W2sAWWQN8x8YB0RRxIche7mLImH7lDgzUy9+B69cM2I6VFJ4a5+0pgAuMLROPOqimaxFPdXqLdDE/vpgGltg=="],
"@yuku-core/binding-linux-x64-musl": ["@yuku-core/binding-linux-x64-musl@0.17.0", "", { "os": "linux", "cpu": "x64" }, "sha512-luEtfpzTP3Xph+HHz2rIVGH1VLbext5SFYrUyhKlbgoahkZ8MDzKI9TYsOVt0HukQkyEtW7+fG7yXJcdKqD4GA=="],
"@yuku-analyzer/binding-win32-arm64": ["@yuku-analyzer/binding-win32-arm64@0.10.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-f534qNc5YaJI29e1oryxEnxPkp7WCYJ1j7ChSec8pQNlYqTm8Tao7hij7NxRF+9BuxzeZCZ+WsbaAfLlklR0Eg=="],
"@yuku-core/binding-win32-arm64": ["@yuku-core/binding-win32-arm64@0.17.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-CaqorOjCPJgUoDwS5nztgeZW4ay21enm3A4A42EY/CotiyDbFO7lKfrqTftGb+ZXrwJ41gNtY1gQ0AaWm0Wvwg=="],
"@yuku-analyzer/binding-win32-x64": ["@yuku-analyzer/binding-win32-x64@0.10.2", "", { "os": "win32", "cpu": "x64" }, "sha512-sKHkmLK8BsindMfyIThoN0bWC5uqSJEVNaLRD/ifA99mtb0UDin1ZCg4WYSVQAmM4k2iOTl4UZx/p3zcBiBgYw=="],
"@yuku-core/binding-win32-x64": ["@yuku-core/binding-win32-x64@0.17.0", "", { "os": "win32", "cpu": "x64" }, "sha512-gPDXHz0dPwvgj1GO7xzK8jPktrCh9xyMXZKmwqq+5bemxrSXSDUK/osSw93xmHha/PQP2WcJ1WiJ8+XEx+ciHg=="],
"@yuku-toolchain/types": ["@yuku-toolchain/types@0.10.2", "", {}, "sha512-sSeo4SSSToiS+sSD+bwn/s94EEcaLJ7tG5LCp8gFYC1G5VzxzX7fqB6m9RU1yMD8KTpu6zdU/I1NlQf8hVBJ9Q=="],
"@yuku-toolchain/types": ["@yuku-toolchain/types@0.17.0", "", {}, "sha512-3T4eKUuFAtuwbyRc2OIpanxPTl4CZdbmOvg1HB9UmRrPb3bsF3fFfbLSyIFYtZrE9/cNqLyEq/7g3Hm6nHIekA=="],
"acorn": ["acorn@8.16.0", "", { "bin": "bin/acorn" }, ""],
"acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, ""],
"ai": ["ai@7.0.119", "", { "dependencies": { "@ai-sdk/gateway": "4.0.97", "@ai-sdk/provider": "4.0.19", "@ai-sdk/provider-utils": "5.0.50" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-KlHbkKMmdb2g0DXdkhBXzSvLSkdoAg0MdShhTTOyuoHKJetEUlgjn2juZ05lHY97EqCwBuSK8dgiEeB0ty5xZw=="],
"ai": ["ai@7.0.137", "", { "dependencies": { "@ai-sdk/gateway": "4.0.110", "@ai-sdk/provider": "4.0.26", "@ai-sdk/provider-utils": "5.0.58" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-JxrPkSQknxIN/gYqS3UQksExS6eWI23QMPBrKMGXeeFHhru6xFtF4MuMq17WaHD+lXPh0lne6H0BM2Z2VMW9EQ=="],
"aria-hidden": ["aria-hidden@1.2.6", "", { "dependencies": { "tslib": "^2.0.0" } }, ""],
@@ -491,7 +491,7 @@
"clsx": ["clsx@2.1.1", "", {}, "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA=="],
"cn": ["cn@0.2.6", "", { "bin": { "cn": "bin/cn.mjs" } }, "sha512-+i4L0zUGgRcEnhsxueVrP7iBGxBx5iD0WOTYg1MwFEu2ZyCmH5Ov2V1cul2Ht5UchRQQgftCf4be/RxspuW6QQ=="],
"cn": ["cn@0.4.0", "", { "bin": { "cn": "bin/cn.mjs" } }, "sha512-qOAeUhPwPzBxx6jaeQdo646XIKliKHc2j1ZF7Ngb1o0pJZKH5gq8FkA0aVdUdPFUDXNXyUCXpCtoJISo6dhizg=="],
"collapse-white-space": ["collapse-white-space@2.1.0", "", {}, ""],
@@ -541,8 +541,6 @@
"enhanced-resolve": ["enhanced-resolve@5.24.5", "", { "dependencies": { "graceful-fs": "^4.2.4", "tapable": "^2.3.3" } }, "sha512-L1l8TNvomm6UVW5B253AGxQagSQr+vGwhMlrrfRS2qmhx46AMpMVJKQYLvWYbysTMY8VoicOvzHzoHMbyzB+4A=="],
"entities": ["entities@6.0.1", "", {}, ""],
"es-toolkit": ["es-toolkit@1.45.1", "", {}, ""],
"esast-util-from-estree": ["esast-util-from-estree@2.0.0", "", { "dependencies": { "@types/estree-jsx": "^1.0.0", "devlop": "^1.0.0", "estree-util-visit": "^2.0.0", "unist-util-position-from-estree": "^2.0.0" } }, ""],
@@ -579,17 +577,17 @@
"fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" } }, ""],
"framer-motion": ["framer-motion@13.5.1", "", { "dependencies": { "motion-dom": "13.5.1", "motion-utils": "13.5.0", "tslib": "^2.4.0" }, "peerDependencies": { "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["react", "react-dom"] }, "sha512-HeWOaeHD3kyTSIEMT6+nw7fBn4saIfxxabZyAITbycAl4xr1kzGJKIvGt/OWghSlvIA9qTnZ1zTGelHAe6S8DA=="],
"framer-motion": ["framer-motion@14.3.0", "", { "dependencies": { "motion-dom": "14.3.0", "motion-utils": "14.1.1", "tslib": "^2.4.0" }, "peerDependencies": { "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["react", "react-dom"] }, "sha512-d8WCrU0ZQn7ukKMykCsDyIOwb/taZeDqqrDBK0du5GO0AO/ynz8fdR/LIIz9Pyy3n3tGwrneR+n0egyrrLa3fw=="],
"fumadocs-core": ["fumadocs-core@16.15.15", "", { "dependencies": { "@fumari/image-size": "^0.1.1", "estree-util-value-to-estree": "^3.5.0", "github-slugger": "^2.0.0", "hast-util-to-estree": "^3.1.3", "hast-util-to-jsx-runtime": "^2.3.6", "mdast-util-mdx": "^3.0.0", "mdast-util-to-markdown": "^2.1.2", "npm-to-yarn": "3.2.0", "remark": "^15.0.1", "remark-gfm": "^4.0.1", "remark-rehype": "^11.1.2", "scroll-into-view-if-needed": "^3.1.0", "shiki": "^4.4.3", "tinyglobby": "^0.2.17", "unified": "^11.0.5", "unist-util-visit": "^5.1.0", "vfile": "^6.0.3", "yaml": "^2.9.1", "zbsearch": "^4.0.0" }, "peerDependencies": { "@mdx-js/mdx": "*", "@mixedbread/sdk": "0.x.x", "@modelcontextprotocol/server": "2.x.x", "@orama/core": "1.x.x", "@oramacloud/client": "2.x.x", "@tanstack/react-router": "1.x.x", "@types/estree-jsx": "*", "@types/hast": "*", "@types/mdast": "*", "@types/react": "*", "algoliasearch": "5.x.x", "flexsearch": "*", "lucide-react": "*", "next": "16.x.x", "react": "^19.2.0", "react-dom": "^19.2.0", "react-router": "7.x.x || 8.x.x", "waku": "*", "zod": "4.x.x" }, "optionalPeers": ["@mdx-js/mdx", "@mixedbread/sdk", "@modelcontextprotocol/server", "@orama/core", "@oramacloud/client", "@tanstack/react-router", "@types/estree-jsx", "@types/hast", "@types/mdast", "@types/react", "algoliasearch", "flexsearch", "lucide-react", "next", "react", "react-dom", "react-router", "waku", "zod"] }, "sha512-kEQLKRlpRl16MfMrlAYiEpk3FPadn4725R3QHYVnF3tJhflRXvznWaJ5pP33F09d6qnOss5onEIgMpAO6rOrpA=="],
"fumadocs-core": ["fumadocs-core@16.17.1", "", { "dependencies": { "@fumari/image-size": "^0.1.1", "estree-util-value-to-estree": "^3.5.0", "github-slugger": "^2.0.0", "hast-util-from-dom": "^5.0.1", "hast-util-to-estree": "^3.1.3", "hast-util-to-jsx-runtime": "^2.3.6", "mdast-util-mdx": "^3.0.0", "micromark": "^4.0.2", "micromark-extension-gfm-table": "^2.1.2", "npm-to-yarn": "3.2.0", "remark": "^15.0.1", "remark-gfm": "^4.0.1", "remark-rehype": "^11.1.2", "scroll-into-view-if-needed": "^3.1.0", "shiki": "^4.5.0", "tinyglobby": "^0.2.17", "unified": "^11.0.5", "vfile": "^6.0.3", "yaml": "^2.9.1", "zbsearch": "^4.0.1" }, "peerDependencies": { "@mdx-js/mdx": "*", "@mixedbread/sdk": "0.x.x", "@modelcontextprotocol/server": "2.x.x", "@orama/core": "1.x.x", "@oramacloud/client": "2.x.x", "@tanstack/react-router": "1.x.x", "@types/estree-jsx": "*", "@types/hast": "*", "@types/mdast": "*", "@types/react": "*", "algoliasearch": "5.x.x", "flexsearch": "*", "lucide-react": "*", "meilisearch": ">=0.50.0 <1.0.0", "next": "16.x.x", "react": "^19.2.0", "react-dom": "^19.2.0", "react-router": "7.x.x || 8.x.x", "waku": "*", "zod": "4.x.x" }, "optionalPeers": ["@mdx-js/mdx", "@mixedbread/sdk", "@modelcontextprotocol/server", "@orama/core", "@oramacloud/client", "@tanstack/react-router", "@types/estree-jsx", "@types/hast", "@types/mdast", "@types/react", "algoliasearch", "flexsearch", "lucide-react", "meilisearch", "next", "react", "react-dom", "react-router", "waku", "zod"] }, "sha512-zquUMPZaCEdsxFZ6ReZPzVN2yCP9tS3GZRndK0WtxbsvZ9KvvUDCeoLIpOZ6d3JU0uwSsclaIUGxI5ifvTftOQ=="],
"fumadocs-mdx": ["fumadocs-mdx@15.4.5", "", { "dependencies": { "@mdx-js/mdx": "^3.1.1", "@standard-schema/spec": "^1.1.0", "chokidar": "^5.0.0", "esbuild": "^0.28.2", "estree-util-value-to-estree": "^3.5.0", "github-slugger": "^2.0.0", "magic-string": "^1.4.1", "mdast-util-mdx": "^3.0.0", "picocolors": "^1.1.1", "picomatch": "^4.0.7", "tinyexec": "^1.3.1", "tinyglobby": "^0.2.17", "unified": "^11.0.5", "unist-util-remove-position": "^5.0.0", "unist-util-visit": "^5.1.0", "vfile": "^6.0.3", "yaml": "^2.9.1", "yuku-analyzer": "^0.10.2", "zod": "^4.6.5" }, "peerDependencies": { "@fumadocs/satteri": "0.x.x", "@types/mdast": "*", "@types/mdx": "*", "@types/react": "*", "fumadocs-core": "^16.15.3", "mdast-util-directive": "*", "next": "^15.3.0 || ^16.0.0", "react": "^19.2.0", "rolldown": "*", "satteri": "^0.10.5", "vite": "7.x.x || 8.x.x" }, "optionalPeers": ["@fumadocs/satteri", "@types/mdast", "@types/mdx", "@types/react", "mdast-util-directive", "next", "react", "rolldown", "satteri", "vite"], "bin": { "fumadocs-mdx": "./bin.js" } }, "sha512-r8gzaqleN+YXgPIbkYSZ05zr89dsr67/64Ar/00Uu7dRWTIHzbgmN1nC0lB8RFNeWnrL41bOTJilhLM4PAsrbw=="],
"fumadocs-mdx": ["fumadocs-mdx@15.4.7", "", { "dependencies": { "@mdx-js/mdx": "^3.1.1", "@standard-schema/spec": "^1.1.0", "chokidar": "^5.0.0", "esbuild": "^0.28.2", "estree-util-value-to-estree": "^3.5.0", "github-slugger": "^2.0.0", "magic-string": "^1.4.2", "mdast-util-mdx": "^3.0.0", "picocolors": "^1.1.1", "picomatch": "^4.0.7", "tinyexec": "^1.3.1", "tinyglobby": "^0.2.17", "unified": "^11.0.5", "unist-util-remove-position": "^5.0.0", "vfile": "^6.0.3", "yaml": "^2.9.1", "yuku-analyzer": "^0.17.0", "zod": "^4.6.5" }, "peerDependencies": { "@fumadocs/satteri": "0.x.x", "@types/mdast": "*", "@types/mdx": "*", "@types/react": "*", "fumadocs-core": "^16.17.0", "mdast-util-directive": "*", "next": "^15.3.0 || ^16.0.0", "react": "^19.2.0", "rolldown": "*", "satteri": "^0.10.5", "vite": "7.x.x || 8.x.x" }, "optionalPeers": ["@fumadocs/satteri", "@types/mdast", "@types/mdx", "@types/react", "mdast-util-directive", "next", "react", "rolldown", "satteri", "vite"], "bin": { "fumadocs-mdx": "./bin.js" } }, "sha512-54lE+dIlIkebSxcN1Lqe0yn5lkKI4zm/Fxl+Se+IqSGyANsBVoa7XaDFFUSLfklxfkSM1NKkrbw0yzvRWVb9rw=="],
"fumadocs-twoslash": ["fumadocs-twoslash@4.0.1", "", { "dependencies": { "@base-ui/react": "^1.8.0", "@types/hast": "^3.0.5", "cn": "^0.2.6", "mdast-util-from-markdown": "^2.0.3", "mdast-util-to-hast": "^13.2.1", "typescript": "~7.0.2" }, "peerDependencies": { "@types/react": "*", "fumadocs-core": "^16.15.7", "fumadocs-ui": "^16.7.16", "react": "^19.2.0", "react-dom": "^19.2.0", "shiki": "^4.4.3" }, "optionalPeers": ["@types/react"] }, "sha512-9+mDaQJZGSI657IsX+kfvtGHYulvHdI0uVgD2hd32i5RMERH2TOgHaq7zz/TKTI7L4WDhx8MZ0BRjyOiso1KMQ=="],
"fumadocs-twoslash": ["fumadocs-twoslash@4.0.2", "", { "dependencies": { "@base-ui/react": "^1.8.0", "@types/hast": "^3.0.5", "cn": "^0.4.0", "mdast-util-from-markdown": "^2.0.3", "mdast-util-to-hast": "^13.2.1", "typescript": "~7.0.2" }, "peerDependencies": { "@types/react": "*", "fumadocs-core": "^16.15.7", "fumadocs-ui": "^16.7.16", "react": "^19.2.0", "react-dom": "^19.2.0", "shiki": "^4.4.3" }, "optionalPeers": ["@types/react"] }, "sha512-SZVadHkuPO8CbtNvM8K9VzgzWAWUi3MDGAQYKVtgi/11Ni3OgZJ3H5YV+P1UwF/HapaSnJKUnLVRH2TM8VsUTg=="],
"fumadocs-typescript": ["fumadocs-typescript@5.4.1", "", { "dependencies": { "estree-util-value-to-estree": "^3.5.0", "hast-util-to-estree": "^3.1.3", "hast-util-to-jsx-runtime": "^2.3.6", "remark": "^15.0.1", "remark-rehype": "^11.1.2", "shiki": "^4.4.3", "typescript": "~7.0.2", "unified": "^11.0.5", "unist-util-visit": "^5.1.0" }, "peerDependencies": { "@types/estree": "*", "@types/hast": "*", "@types/mdast": "*", "@types/react": "*", "fumadocs-core": "^16.7.0", "fumadocs-ui": "^16.7.0", "react": "^19.2.0", "react-dom": "^19.2.0" }, "optionalPeers": ["@types/estree", "@types/hast", "@types/mdast", "@types/react", "fumadocs-ui"] }, "sha512-qW61uHWNnK7XWFpINeWedX9UMQotPOLDC5oHybwA5l39CAR0xC/G6hlyGgTF2WH4AQjsFDwDAwgVuuU4dbmNJQ=="],
"fumadocs-typescript": ["fumadocs-typescript@5.5.2", "", { "dependencies": { "estree-util-value-to-estree": "^3.5.0", "hast-util-to-estree": "^3.1.3", "hast-util-to-jsx-runtime": "^2.3.6", "remark": "^15.0.1", "remark-rehype": "^11.1.2", "shiki": "^4.5.0", "typescript": "~7.0.2", "unified": "^11.0.5" }, "peerDependencies": { "@types/estree": "*", "@types/hast": "*", "@types/mdast": "*", "@types/react": "*", "fumadocs-core": "^16.17.1", "fumadocs-ui": "^16.7.0", "react": "^19.2.0", "react-dom": "^19.2.0" }, "optionalPeers": ["@types/estree", "@types/hast", "@types/mdast", "@types/react", "fumadocs-ui"] }, "sha512-QbKLRpx2Hfyq3R4NpPHKEz0TW+csBuT9IFLhrjyalfP89HpsZBwpHRVCOl//d2Smcbpmj9N4UCp03p97od+NkA=="],
"fumadocs-ui": ["fumadocs-ui@16.15.15", "", { "dependencies": { "@fuma-translate/react": "^1.0.2", "@fumadocs/tailwind": "0.1.2", "@radix-ui/react-accordion": "^1.2.20", "@radix-ui/react-collapsible": "^1.1.20", "@radix-ui/react-dialog": "^1.1.23", "@radix-ui/react-direction": "^1.1.4", "@radix-ui/react-navigation-menu": "^1.2.22", "@radix-ui/react-popover": "^1.1.23", "@radix-ui/react-presence": "^1.1.10", "@radix-ui/react-scroll-area": "^1.2.18", "@radix-ui/react-slot": "^1.3.3", "@radix-ui/react-tabs": "^1.1.21", "class-variance-authority": "^0.7.1", "cn": "^0.3.0", "lucide-react": "^1.47.0", "motion": "^13.4.0", "next-themes": "^0.4.6", "react-remove-scroll": "^2.7.2", "rehype-raw": "^7.0.0", "scroll-into-view-if-needed": "^3.1.0", "shiki": "^4.4.3", "unist-util-visit": "^5.1.0" }, "peerDependencies": { "@types/mdx": "*", "@types/react": "*", "fumadocs-core": "16.15.15", "next": "16.x.x", "react": "^19.2.0", "react-dom": "^19.2.0", "takumi-js": "*" }, "optionalPeers": ["@types/mdx", "@types/react", "next", "takumi-js"] }, "sha512-wE9gTz+JYoz9wwxaNCfj7jqN7c7oAY7lCyuFootpY8jmGiyZHfy6db2cxlRwjm+qEaLdsV/KOsAjbuuT/n8elg=="],
"fumadocs-ui": ["fumadocs-ui@16.17.1", "", { "dependencies": { "@fuma-translate/react": "^1.0.2", "@fumadocs/tailwind": "0.1.3", "@radix-ui/react-accordion": "^1.2.20", "@radix-ui/react-collapsible": "^1.1.20", "@radix-ui/react-dialog": "^1.1.23", "@radix-ui/react-direction": "^1.1.4", "@radix-ui/react-navigation-menu": "^1.2.22", "@radix-ui/react-popover": "^1.1.23", "@radix-ui/react-presence": "^1.1.10", "@radix-ui/react-scroll-area": "^1.2.18", "@radix-ui/react-slot": "^1.3.3", "@radix-ui/react-tabs": "^1.1.21", "class-variance-authority": "^0.7.1", "cn": "^0.4.0", "hast-util-to-jsx-runtime": "^2.3.6", "lucide-react": "^1.50.0", "motion": "^14.0.0", "next-themes": "^0.4.6", "react-remove-scroll": "^2.7.2", "scroll-into-view-if-needed": "^3.1.0", "shiki": "^4.5.0" }, "peerDependencies": { "@types/mdx": "*", "@types/react": "*", "fumadocs-core": "16.17.1", "next": "16.x.x", "react": "^19.2.0", "react-dom": "^19.2.0", "takumi-js": "*" }, "optionalPeers": ["@types/mdx", "@types/react", "next", "takumi-js"] }, "sha512-ByW1NbvEbMfsZfW+DkWewSEX7Ituv732K0y2ga1ri+Zghf+4zu2sa0QjJetC3DaKffyvx5vbPVxwjyYCeNtRhg=="],
"get-nonce": ["get-nonce@1.0.1", "", {}, ""],
@@ -597,20 +595,16 @@
"graceful-fs": ["graceful-fs@4.2.11", "", {}, ""],
"hast-util-from-parse5": ["hast-util-from-parse5@8.0.3", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "devlop": "^1.0.0", "hastscript": "^9.0.0", "property-information": "^7.0.0", "vfile": "^6.0.0", "vfile-location": "^5.0.0", "web-namespaces": "^2.0.0" } }, ""],
"hast-util-from-dom": ["hast-util-from-dom@5.0.1", "", { "dependencies": { "@types/hast": "^3.0.0", "hastscript": "^9.0.0", "web-namespaces": "^2.0.0" } }, "sha512-N+LqofjR2zuzTjCPzyDUdSshy4Ma6li7p/c3pA78uTwzFgENbgbUrm2ugwsOdcjI1muO+o6Dgzp9p8WHtn/39Q=="],
"hast-util-parse-selector": ["hast-util-parse-selector@4.0.0", "", { "dependencies": { "@types/hast": "^3.0.0" } }, ""],
"hast-util-raw": ["hast-util-raw@9.1.0", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "@ungap/structured-clone": "^1.0.0", "hast-util-from-parse5": "^8.0.0", "hast-util-to-parse5": "^8.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "parse5": "^7.0.0", "unist-util-position": "^5.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0", "web-namespaces": "^2.0.0", "zwitch": "^2.0.0" } }, ""],
"hast-util-to-estree": ["hast-util-to-estree@3.1.3", "", { "dependencies": { "@types/estree": "^1.0.0", "@types/estree-jsx": "^1.0.0", "@types/hast": "^3.0.0", "comma-separated-tokens": "^2.0.0", "devlop": "^1.0.0", "estree-util-attach-comments": "^3.0.0", "estree-util-is-identifier-name": "^3.0.0", "hast-util-whitespace": "^3.0.0", "mdast-util-mdx-expression": "^2.0.0", "mdast-util-mdx-jsx": "^3.0.0", "mdast-util-mdxjs-esm": "^2.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "style-to-js": "^1.0.0", "unist-util-position": "^5.0.0", "zwitch": "^2.0.0" } }, ""],
"hast-util-to-html": ["hast-util-to-html@9.0.5", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-whitespace": "^3.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "stringify-entities": "^4.0.0", "zwitch": "^2.0.4" } }, ""],
"hast-util-to-jsx-runtime": ["hast-util-to-jsx-runtime@2.3.6", "", { "dependencies": { "@types/estree": "^1.0.0", "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "comma-separated-tokens": "^2.0.0", "devlop": "^1.0.0", "estree-util-is-identifier-name": "^3.0.0", "hast-util-whitespace": "^3.0.0", "mdast-util-mdx-expression": "^2.0.0", "mdast-util-mdx-jsx": "^3.0.0", "mdast-util-mdxjs-esm": "^2.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "style-to-js": "^1.0.0", "unist-util-position": "^5.0.0", "vfile-message": "^4.0.0" } }, ""],
"hast-util-to-parse5": ["hast-util-to-parse5@8.0.1", "", { "dependencies": { "@types/hast": "^3.0.0", "comma-separated-tokens": "^2.0.0", "devlop": "^1.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "web-namespaces": "^2.0.0", "zwitch": "^2.0.0" } }, ""],
"hast-util-whitespace": ["hast-util-whitespace@3.0.0", "", { "dependencies": { "@types/hast": "^3.0.0" } }, ""],
"hastscript": ["hastscript@9.0.1", "", { "dependencies": { "@types/hast": "^3.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-parse-selector": "^4.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0" } }, ""],
@@ -719,7 +713,7 @@
"micromark-extension-gfm-strikethrough": ["micromark-extension-gfm-strikethrough@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-classify-character": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, ""],
"micromark-extension-gfm-table": ["micromark-extension-gfm-table@2.1.1", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, ""],
"micromark-extension-gfm-table": ["micromark-extension-gfm-table@2.1.2", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-pRzm4kDTu0MjlmBkxmS9yYhw60nncfcEwu9NNdPFSQEFXS95ZKyIIyTSHu/o3ReBUrLKYEq+7YaXCRn/bPB4MA=="],
"micromark-extension-gfm-tagfilter": ["micromark-extension-gfm-tagfilter@2.0.0", "", { "dependencies": { "micromark-util-types": "^2.0.0" } }, ""],
@@ -777,11 +771,11 @@
"micromark-util-types": ["micromark-util-types@2.0.2", "", {}, ""],
"motion": ["motion@13.5.1", "", { "dependencies": { "framer-motion": "13.5.1", "tslib": "^2.4.0" }, "peerDependencies": { "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["react", "react-dom"] }, "sha512-eV9SUem6KnzEa9+eT+dVBeDlhy5TTdn09YWR1WhUsKoZCJPw/n4TcYhjbxq2Gy5PTwDr//4H3r5vxkcZnNnO1w=="],
"motion": ["motion@14.3.0", "", { "dependencies": { "framer-motion": "14.3.0", "tslib": "^2.4.0" }, "peerDependencies": { "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["react", "react-dom"] }, "sha512-yh/nHYjikl68+FTxAMywFYzzj21/oGY7RGCfkqN5zpuT1rk3rp0lKfVU8EUq0A64qQeGnxuKUJWP85MipqdLBw=="],
"motion-dom": ["motion-dom@13.5.1", "", { "dependencies": { "motion-utils": "13.5.0" } }, "sha512-/7CVCD20Mz1KobktorpdgvowV0V41J7UxqE+qWS3GkSJqrRr5ft+2RloOYtEKv+wvBp3JaSFBclhxt4ja8ovHg=="],
"motion-dom": ["motion-dom@14.3.0", "", { "dependencies": { "motion-utils": "14.1.1" } }, "sha512-rcKO4aEJzAqDEsrH6qFzhLZxs7bNqZpiUEuEATz9LaRwt6dG7hZEbcFUSHNR8NECaKYM0Iuw6Iv6NpWEGXDI+w=="],
"motion-utils": ["motion-utils@13.5.0", "", {}, "sha512-Hqe/sqjIKliPZg8sVjWAkdySDPJNIeKH+euVkDOG8ri3DUUU7ZjndmHsGqEPz2iHpiyVaV5I22iguCMHU2he+Q=="],
"motion-utils": ["motion-utils@14.1.1", "", {}, "sha512-3VvN5Uvf8B6qG+OfOui6Nht5EWp+vLuU3IqcAj7ItZGKqtmTjCebl5sGZF7/08gEHRnEl1AP/fIwbcEyVrcQGQ=="],
"ms": ["ms@2.1.3", "", {}, ""],
@@ -797,12 +791,10 @@
"oniguruma-to-es": ["oniguruma-to-es@4.3.6", "", { "dependencies": { "oniguruma-parser": "^0.12.2", "regex": "^6.1.0", "regex-recursion": "^6.0.2" } }, "sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA=="],
"openai": ["openai@7.30.0", "", { "peerDependencies": { "@aws-sdk/credential-provider-node": ">=3.972.0 <4", "@smithy/hash-node": ">=4.3.0 <5", "@smithy/signature-v4": ">=5.4.0 <6", "undici": ">=5 <9", "ws": "^8.21.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["@aws-sdk/credential-provider-node", "@smithy/hash-node", "@smithy/signature-v4", "undici", "ws", "zod"] }, "sha512-tvvcPdhS56B/79o0mJS5h4JndAov5Sz78T7CFl4gJ+C9S3GoSqHNLO6lG/8kdK+/c13zWEI97Srf66ar0V242g=="],
"openai": ["openai@7.34.0", "", { "peerDependencies": { "@aws-sdk/credential-provider-node": ">=3.972.0 <4", "@smithy/hash-node": ">=4.3.0 <5", "@smithy/signature-v4": ">=5.4.0 <6", "undici": ">=5 <9", "ws": "^8.21.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["@aws-sdk/credential-provider-node", "@smithy/hash-node", "@smithy/signature-v4", "undici", "ws", "zod"] }, "sha512-PMwuTQ/3cVyWZJOVpb6bzlrQj17uImlnUGQWqh5zHlN/snwK5ww4ZUHW8NYGtH6f9PQOEPxyD/f8WJVIHp1q2A=="],
"parse-entities": ["parse-entities@4.0.2", "", { "dependencies": { "@types/unist": "^2.0.0", "character-entities-legacy": "^3.0.0", "character-reference-invalid": "^2.0.0", "decode-named-character-reference": "^1.0.0", "is-alphanumerical": "^2.0.0", "is-decimal": "^2.0.0", "is-hexadecimal": "^2.0.0" } }, ""],
"parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, ""],
"picocolors": ["picocolors@1.1.1", "", {}, ""],
"picomatch": ["picomatch@4.0.7", "", {}, "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA=="],
@@ -851,8 +843,6 @@
"regex-utilities": ["regex-utilities@2.3.0", "", {}, "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng=="],
"rehype-raw": ["rehype-raw@7.0.0", "", { "dependencies": { "@types/hast": "^3.0.0", "hast-util-raw": "^9.0.0", "vfile": "^6.0.0" } }, ""],
"rehype-recma": ["rehype-recma@1.0.0", "", { "dependencies": { "@types/estree": "^1.0.0", "@types/hast": "^3.0.0", "hast-util-to-estree": "^3.0.0" } }, ""],
"remark": ["remark@15.0.1", "", { "dependencies": { "@types/mdast": "^4.0.0", "remark-parse": "^11.0.0", "remark-stringify": "^11.0.0", "unified": "^11.0.0" } }, ""],
@@ -879,7 +869,7 @@
"sharp": ["sharp@0.35.5", "", { "dependencies": { "@img/colour": "^1.1.0", "detect-libc": "^2.1.2", "semver": "^7.8.5" }, "optionalDependencies": { "@img/sharp-darwin-arm64": "0.35.5", "@img/sharp-darwin-x64": "0.35.5", "@img/sharp-freebsd-wasm32": "0.35.5", "@img/sharp-libvips-darwin-arm64": "1.3.4", "@img/sharp-libvips-darwin-x64": "1.3.4", "@img/sharp-libvips-linux-arm": "1.3.4", "@img/sharp-libvips-linux-arm64": "1.3.4", "@img/sharp-libvips-linux-ppc64": "1.3.4", "@img/sharp-libvips-linux-riscv64": "1.3.4", "@img/sharp-libvips-linux-s390x": "1.3.4", "@img/sharp-libvips-linux-x64": "1.3.4", "@img/sharp-libvips-linuxmusl-arm64": "1.3.4", "@img/sharp-libvips-linuxmusl-x64": "1.3.4", "@img/sharp-linux-arm": "0.35.5", "@img/sharp-linux-arm64": "0.35.5", "@img/sharp-linux-ppc64": "0.35.5", "@img/sharp-linux-riscv64": "0.35.5", "@img/sharp-linux-s390x": "0.35.5", "@img/sharp-linux-x64": "0.35.5", "@img/sharp-linuxmusl-arm64": "0.35.5", "@img/sharp-linuxmusl-x64": "0.35.5", "@img/sharp-webcontainers-wasm32": "0.35.5", "@img/sharp-win32-arm64": "0.35.5", "@img/sharp-win32-ia32": "0.35.5", "@img/sharp-win32-x64": "0.35.5" }, "peerDependencies": { "@types/node": "*" }, "optionalPeers": ["@types/node"] }, "sha512-Ywn4OnzGukp7CDMrp08RQ50YKmuwG47brZgIVPTvBaaAfQlRlygrRqSrxdCiL9M+LlzLBiJ68IR1QqvzHyjC7g=="],
"shiki": ["shiki@4.4.3", "", { "dependencies": { "@shikijs/core": "4.4.3", "@shikijs/engine-javascript": "4.4.3", "@shikijs/engine-oniguruma": "4.4.3", "@shikijs/langs": "4.4.3", "@shikijs/themes": "4.4.3", "@shikijs/types": "4.4.3", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5" } }, "sha512-Mb/GvXPHBAXdgGIcnfU5L3ldpn1XcxrGkPHwqgRx17/I2XRfqlFKk2vGkHWINn1kdXvzJZeuO3is6I9KLPFm0g=="],
"shiki": ["shiki@4.5.0", "", { "dependencies": { "@shikijs/core": "4.5.0", "@shikijs/engine-javascript": "4.5.0", "@shikijs/engine-oniguruma": "4.5.0", "@shikijs/langs": "4.5.0", "@shikijs/themes": "4.5.0", "@shikijs/types": "4.5.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.5" } }, "sha512-OcRW72ngQvc+MSVWBRIovC/BTW589iUE/Vxav7VeM4RcY9MUjqB+IR6ILG1k9nuW6LiG/nct9uma4/MBtnZbmQ=="],
"source-map": ["source-map@0.7.6", "", {}, ""],
@@ -947,8 +937,6 @@
"vfile": ["vfile@6.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile-message": "^4.0.0" } }, ""],
"vfile-location": ["vfile-location@5.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile": "^6.0.0" } }, ""],
"vfile-message": ["vfile-message@4.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-stringify-position": "^4.0.0" } }, ""],
"victory-vendor": ["victory-vendor@37.3.6", "", { "dependencies": { "@types/d3-array": "^3.0.3", "@types/d3-ease": "^3.0.0", "@types/d3-interpolate": "^3.0.1", "@types/d3-scale": "^4.0.2", "@types/d3-shape": "^3.1.0", "@types/d3-time": "^3.0.0", "@types/d3-timer": "^3.0.0", "d3-array": "^3.1.6", "d3-ease": "^3.0.1", "d3-interpolate": "^3.0.1", "d3-scale": "^4.0.2", "d3-shape": "^3.1.0", "d3-time": "^3.0.0", "d3-timer": "^3.0.1" } }, ""],
@@ -959,9 +947,11 @@
"yaml": ["yaml@2.9.1", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw=="],
"yuku-analyzer": ["yuku-analyzer@0.10.2", "", { "dependencies": { "@yuku-toolchain/types": "^0.10.2", "yuku-ast": "^0.10.2" }, "optionalDependencies": { "@yuku-analyzer/binding-android-arm64": "0.10.2", "@yuku-analyzer/binding-darwin-arm64": "0.10.2", "@yuku-analyzer/binding-darwin-x64": "0.10.2", "@yuku-analyzer/binding-freebsd-x64": "0.10.2", "@yuku-analyzer/binding-linux-arm-gnu": "0.10.2", "@yuku-analyzer/binding-linux-arm-musl": "0.10.2", "@yuku-analyzer/binding-linux-arm64-gnu": "0.10.2", "@yuku-analyzer/binding-linux-arm64-musl": "0.10.2", "@yuku-analyzer/binding-linux-x64-gnu": "0.10.2", "@yuku-analyzer/binding-linux-x64-musl": "0.10.2", "@yuku-analyzer/binding-win32-arm64": "0.10.2", "@yuku-analyzer/binding-win32-x64": "0.10.2" } }, "sha512-UBRcDcZtIn14g88loZUZ123d6MOkc2hMTawUle5MkuWboowM90KbWHN3Zz+HfuS06sw935ygecBpcJlXHB/pOA=="],
"yuku-analyzer": ["yuku-analyzer@0.17.0", "", { "dependencies": { "@yuku-toolchain/types": "^0.17.0", "yuku-ast": "^0.17.0", "yuku-core": "0.17.0" } }, "sha512-MJWtt5HvXVR51mGOR2uMXQ45t1X1oMkmx4vaP/Li1HNC69OFG/qYmxf++aVazkXH5pdxTYTHYRUPl67b7NYxjA=="],
"yuku-ast": ["yuku-ast@0.10.2", "", { "dependencies": { "@yuku-toolchain/types": "^0.10.2" } }, "sha512-UnG9mA6giglCvSErft2/40TVFX750Sj1xgwddPLpG7J7rlr/P1wPADg9G2RK+d/1tNLtRVoLdMMOMVBB9561TQ=="],
"yuku-ast": ["yuku-ast@0.17.0", "", { "dependencies": { "@yuku-toolchain/types": "^0.17.0" } }, "sha512-htIzp3bLNdBtOSh8L8pJ7nkTft2kw/C3ghTToSg3FKtzi0YGkvAdEUUza9c744tnbeXtKUMEupFOYHuVNXn1yQ=="],
"yuku-core": ["yuku-core@0.17.0", "", { "dependencies": { "@yuku-toolchain/types": "^0.17.0" }, "optionalDependencies": { "@yuku-core/binding-android-arm64": "0.17.0", "@yuku-core/binding-darwin-arm64": "0.17.0", "@yuku-core/binding-darwin-x64": "0.17.0", "@yuku-core/binding-freebsd-x64": "0.17.0", "@yuku-core/binding-linux-arm-gnu": "0.17.0", "@yuku-core/binding-linux-arm-musl": "0.17.0", "@yuku-core/binding-linux-arm64-gnu": "0.17.0", "@yuku-core/binding-linux-arm64-musl": "0.17.0", "@yuku-core/binding-linux-x64-gnu": "0.17.0", "@yuku-core/binding-linux-x64-musl": "0.17.0", "@yuku-core/binding-win32-arm64": "0.17.0", "@yuku-core/binding-win32-x64": "0.17.0" } }, "sha512-4BgHT4euQ62wr/9h5UWoMzt4QTrmT3WUo96aRiY2R6RRCyKjCveU23MNwNJISzYvNnbFGZ7O2E1SU5zgWqzS+Q=="],
"zbsearch": ["zbsearch@4.0.1", "", {}, "sha512-lmnEEnb93QQcNv7qARDr7jBVPxYdZbZ9XdZ0dbZ0qaOvGne4jJMW4fjwPfVaUKQXv3FNWvGbDwRDgyaSb1pc8w=="],
@@ -969,9 +959,9 @@
"zwitch": ["zwitch@2.0.4", "", {}, ""],
"@ai-sdk/gateway/@ai-sdk/provider": ["@ai-sdk/provider@4.0.19", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-ryVZSSfmpEsr4bM8rbt9cSBWal+KGYRrm57C+k/hiPQHMiMahaqg2bPF0MpxSUWY8mGpt7s/ajM6PAqNTMKqPQ=="],
"@ai-sdk/gateway/@ai-sdk/provider": ["@ai-sdk/provider@4.0.26", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-BZ443uBEq6HuMA+Z4b7Hpm65GpZSo7pWqnYqpf/7tAO3C48JbtvAhOE2JnODFj+jodsZzfRHkAyQb64xuD2tZQ=="],
"@ai-sdk/gateway/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@5.0.50", "", { "dependencies": { "@ai-sdk/provider": "4.0.19", "@standard-schema/spec": "^1.1.0", "@workflow/serde": "4.1.0", "eventsource-parser": "^3.0.8", "undici": "^7.29.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-qg2LutM5RlUT/tuuFf+VkhFGNZ2sEJHL0oDIrFN/sMoVbDBANglqtGCJUOnBqGMoFBH8IfAXMrFZvbFWx4dMOg=="],
"@ai-sdk/gateway/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@5.0.58", "", { "dependencies": { "@ai-sdk/provider": "4.0.26", "@standard-schema/spec": "^1.1.0", "@workflow/serde": "4.1.0", "eventsource-parser": "^3.0.8", "undici": "^7.29.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-iXSwKR/7LpHzAlyrUl+bTinwzmZ3Nmup1viwPisM5Gn5cogRdIG4rV9w1ZDuKFcrXyu/AeVs42E1CX/0aNwrfQ=="],
"@base-ui/react/@babel/runtime": ["@babel/runtime@7.29.7", "", {}, "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw=="],
@@ -983,6 +973,14 @@
"@mdx-js/mdx/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"@radix-ui/react-collection/@radix-ui/react-slot": ["@radix-ui/react-slot@1.3.3", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.5" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-qx7oqnYbxnK9kYI9m317qmFmEgo6ywqWvbTogdj7cL9p3/yx4M48p7Rnw5z3H890cL/ow/EeWJsuTykeZVXP5Q=="],
"@radix-ui/react-dialog/@radix-ui/react-slot": ["@radix-ui/react-slot@1.3.3", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.5" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-qx7oqnYbxnK9kYI9m317qmFmEgo6ywqWvbTogdj7cL9p3/yx4M48p7Rnw5z3H890cL/ow/EeWJsuTykeZVXP5Q=="],
"@radix-ui/react-popover/@radix-ui/react-slot": ["@radix-ui/react-slot@1.3.3", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.5" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-qx7oqnYbxnK9kYI9m317qmFmEgo6ywqWvbTogdj7cL9p3/yx4M48p7Rnw5z3H890cL/ow/EeWJsuTykeZVXP5Q=="],
"@radix-ui/react-primitive/@radix-ui/react-slot": ["@radix-ui/react-slot@1.3.3", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.5" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-qx7oqnYbxnK9kYI9m317qmFmEgo6ywqWvbTogdj7cL9p3/yx4M48p7Rnw5z3H890cL/ow/EeWJsuTykeZVXP5Q=="],
"@reduxjs/toolkit/immer": ["immer@11.1.4", "", {}, ""],
"@reduxjs/toolkit/reselect": ["reselect@5.1.1", "", {}, ""],
@@ -1007,26 +1005,18 @@
"@tailwindcss/postcss/tailwindcss": ["tailwindcss@4.3.3", "", {}, "sha512-gOhV3P7ufE62QDGg1zVaTgCR+EtPv92k2nIhVcVKcLmxT1sUBsQGhnZj175j+MqRt4zLF7ic+sCYjfhxMxj7YQ=="],
"ai/@ai-sdk/provider": ["@ai-sdk/provider@4.0.19", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-ryVZSSfmpEsr4bM8rbt9cSBWal+KGYRrm57C+k/hiPQHMiMahaqg2bPF0MpxSUWY8mGpt7s/ajM6PAqNTMKqPQ=="],
"ai/@ai-sdk/provider": ["@ai-sdk/provider@4.0.26", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-BZ443uBEq6HuMA+Z4b7Hpm65GpZSo7pWqnYqpf/7tAO3C48JbtvAhOE2JnODFj+jodsZzfRHkAyQb64xuD2tZQ=="],
"ai/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@5.0.50", "", { "dependencies": { "@ai-sdk/provider": "4.0.19", "@standard-schema/spec": "^1.1.0", "@workflow/serde": "4.1.0", "eventsource-parser": "^3.0.8", "undici": "^7.29.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-qg2LutM5RlUT/tuuFf+VkhFGNZ2sEJHL0oDIrFN/sMoVbDBANglqtGCJUOnBqGMoFBH8IfAXMrFZvbFWx4dMOg=="],
"fumadocs-ui/cn": ["cn@0.3.3", "", { "bin": { "cn": "bin/cn.mjs" } }, "sha512-OEiyJkSpYm2kOuNOKQ+c2wmzZRG8orrb9fnObtHTbCGNx/E9KLnGcmcocItOzREKk5KzQN5I2e3BUCj563KEpw=="],
"hast-util-from-parse5/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"ai/@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@5.0.58", "", { "dependencies": { "@ai-sdk/provider": "4.0.26", "@standard-schema/spec": "^1.1.0", "@workflow/serde": "4.1.0", "eventsource-parser": "^3.0.8", "undici": "^7.29.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-iXSwKR/7LpHzAlyrUl+bTinwzmZ3Nmup1viwPisM5Gn5cogRdIG4rV9w1ZDuKFcrXyu/AeVs42E1CX/0aNwrfQ=="],
"hast-util-parse-selector/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"hast-util-raw/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"hast-util-to-estree/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"hast-util-to-html/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"hast-util-to-jsx-runtime/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"hast-util-to-parse5/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"hast-util-whitespace/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"hastscript/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
@@ -1039,9 +1029,9 @@
"mdast-util-to-hast/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, ""],
"micromark-extension-gfm/micromark-extension-gfm-table": ["micromark-extension-gfm-table@2.1.1", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, ""],
"rehype-raw/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, ""],
"rehype-recma/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
+4
View File
@@ -82,6 +82,10 @@ The client never sees CCR tool calls on the Anthropic and OpenAI proxy paths; He
also return `finish_reason=MALFORMED_FUNCTION_CALL` on large function-response
continuations after CCR retrieval; that separate limitation remains tracked in
[issue #2041](https://github.com/headroomlabs-ai/headroom/issues/2041).
Native Google batch contexts retain the effective forwarded Tool objects,
including injected retrieval declarations and sibling Google Search or code
execution tools. Continuations use those declarations alongside the original
conversation rather than rebuilding a function-declaration wrapper.
</Callout>
## Phase 4: Context Tracker
+1 -1
View File
@@ -73,7 +73,7 @@ Headroom runs on the developer's machine and talks to the same services the AI t
|---|---|---|
| `api.anthropic.com` | Claude / Claude Code | yes, for Anthropic |
| `api.openai.com`, `chatgpt.com` | OpenAI API, Codex | yes, for OpenAI / Codex |
| `api.githubcopilot.com`, `api.github.com` | GitHub Copilot | for Copilot |
| `api.githubcopilot.com` (or `api.business.githubcopilot.com` / `api.enterprise.githubcopilot.com` for those plans), `api.github.com` | GitHub Copilot | for Copilot |
| `huggingface.co` and the storage hosts it redirects to (`cdn-lfs.hf.co`, `cas-bridge.xethub.hf.co`) | Compression models (downloaded once) | recommended |
| `openaipublic.blob.core.windows.net` | Tokenizer vocabulary (downloaded once) | recommended |
+4
View File
@@ -24,6 +24,10 @@ dependencies may impose their own Python/platform limits. Platforms outside
that matrix fall back to the source distribution and need a Rust/native
toolchain.
Use the distribution name `headroom-ai` for every install, including extras such as
`"headroom-ai[langchain]"`. The Python import and CLI command remain `headroom`;
the PyPI distribution named `headroom` is a different project.
On Intel macOS, ONNX Runtime wheels are available through Python 3.13, using
the pre-1.24 runtime. Python 3.14 and newer omit optional ONNX backends from
`proxy`, `voice`, `relevance`, and `image` extras because compatible wheels are
+4 -2
View File
@@ -174,10 +174,12 @@ this page's "nothing leaves the machine" framing as universal:
compression ratios, skip reasons, provider and model ids, failure counts, plus
OS and architecture. Never prompts, completions, code, or file paths -- the
collector allowlists fields server-side and drops the rest. Disable it with
`HEADROOM_BEACON=off`, the cross-tool `DO_NOT_TRACK=1` convention, or by
`HEADROOM_BEACON=off`, `HEADROOM_TELEMETRY=off`, the cross-tool `DO_NOT_TRACK=1` convention, or by
running offline. `is_beacon_enabled()` is fail-open: an unrecognized value
uploads rather than staying silent. See [Proxy](/docs/proxy) for the full
field list.
These are deliberately separate so that enabling local `/stats` does not
silently start an upload on the next release.
silently start an upload on the next release. The one crossing only ever turns
the upload off: an explicit `HEADROOM_TELEMETRY=off` also stops the beacon
(unless `HEADROOM_BEACON=on`).
+2 -2
View File
@@ -24,7 +24,7 @@ headroom proxy \
--budget 100.0
```
Two independent telemetry switches exist. `HEADROOM_TELEMETRY=on` (or `--telemetry`) turns on **local-only** in-process usage stats that power your own `/stats`, `/metrics`, and dashboard — off by default, and nothing under this switch leaves the machine.
Two telemetry switches exist. `HEADROOM_TELEMETRY=on` (or `--telemetry`) turns on **local-only** in-process usage stats that power your own `/stats`, `/metrics`, and dashboard — off by default, and nothing under this switch leaves the machine.
Separately, an **anonymous usage beacon is on by default** (opt-out). Once a session goes idle it POSTs a small summary of how compression behaved to a Headroom Labs collector.
@@ -36,7 +36,7 @@ Separately, an **anonymous usage beacon is on by default** (opt-out). Once a ses
The install id is a random UUID generated on first run and stored in your config directory. It is deliberately not derived from hostname, MAC address, or any hardware property — delete the file and you get a new one.
Disable it with `HEADROOM_BEACON=off`, the `DO_NOT_TRACK=1` convention, or `HEADROOM_OFFLINE=1` (which also disables update checks and license reporting).
Disable it with `HEADROOM_BEACON=off`, `HEADROOM_TELEMETRY=off` (or `--no-telemetry`), the `DO_NOT_TRACK=1` convention, or `HEADROOM_OFFLINE=1` (which also disables update checks and license reporting). `HEADROOM_BEACON=on` keeps the beacon on even with local stats off. `headroom telemetry` names the setting that turned it off.
## CLI options
+11 -7
View File
@@ -284,6 +284,7 @@ accept arbitrary environment variables — writes are restricted to a hardcoded
| `HEADROOM_INTERCEPT_READ_MIN_CHARS` | ast-grep read-interception threshold |
| `HEADROOM_VERIFY_TRUNCATION_ON_DISK` | Verify ast-grep Read truncation against disk when no client banner is found. Always returns `UNKNOWN` on Windows, where `dir_fd` / `O_NOFOLLOW` support is unavailable. |
| `HEADROOM_VERIFY_TRUNCATION_MAX_BYTES` | Max on-disk file size (bytes) the disk-verify fallback will read |
| `HEADROOM_BUFFERED_UPSTREAM_STREAM` | Send buffered CCR requests (and their continuations) upstream as `stream: true` and fold the reply (default on; `0` sends `stream: false`) |
Keys outside this list are ignored, and `/admin/upstream` is read-only — there is no
write route on the admin surface, specifically so a caller cannot redirect
@@ -342,7 +343,7 @@ Beyond your configured LLM providers, Headroom may contact:
| Destination | Purpose | Default | Disable / pre-provision |
|---|---|---|---|
| `headroom-beacon.headroom-beacon.workers.dev` | Anonymous session summaries to Headroom Labs | **On** — see [The beacon](#the-beacon-is-on-by-default) | `HEADROOM_BEACON=off`, `DO_NOT_TRACK=1`, or `HEADROOM_OFFLINE` |
| `headroom-beacon.headroom-beacon.workers.dev` | Anonymous session summaries to Headroom Labs | **On** — see [The beacon](#the-beacon-is-on-by-default) | `HEADROOM_BEACON=off`, `HEADROOM_TELEMETRY=off`, `DO_NOT_TRACK=1`, or `HEADROOM_OFFLINE` |
| `pypi.org` | Daily version check for update notices | On | `HEADROOM_UPDATE_CHECK=off`; also skipped in `--stateless`, in CI, and from source checkouts |
| `huggingface.co` | Downloads models for the optional ML compression paths | On first use of those features | Pre-provision the model cache, or leave the features disabled |
| `app.headroomlabs.ai` | License validation and usage reporting | Only with a license key configured | Omit the license key |
@@ -378,14 +379,17 @@ Prompts, completions, file contents, tool results, and file paths are **not** in
payload. The install id is a random UUID rather than a machine fingerprint, and resets
if you delete `<config dir>/install_id`.
Three controls switch it off, checked in this order:
Four controls switch it off, checked in this order:
```bash
HEADROOM_OFFLINE=1 # offline mode — disables all egress, not just the beacon
DO_NOT_TRACK=1 # the cross-tool convention, honoured
HEADROOM_BEACON=off # also false / 0 / no / disable / disabled
HEADROOM_OFFLINE=1 # offline mode — disables all egress, not just the beacon
DO_NOT_TRACK=1 # the cross-tool convention, honoured
HEADROOM_BEACON=off # also false / 0 / no / disable / disabled; =on keeps it on
HEADROOM_TELEMETRY=off # same off-values; also what --no-telemetry sets
```
`headroom telemetry` names the setting that turned it off.
The destination can also be redirected with `HEADROOM_TELEMETRY_ENDPOINT`, which is
useful if you would rather terminate the reports at a receiver you control than block
them outright.
@@ -400,8 +404,8 @@ assuming a typo fails safe.
`HEADROOM_TELEMETRY` is a **different switch**, off by default and opt-in. It aggregates
stats locally for the in-process collector and the `/stats` and `/v1/telemetry`
endpoints, and sends nothing off-host. Enabling it does not authorise beacon upload, and
disabling it does not suppress the beacon — the two are deliberately independent.
endpoints, and sends nothing off-host. Enabling it does not authorise beacon upload; an
explicit `HEADROOM_TELEMETRY=off` does suppress the beacon, unless `HEADROOM_BEACON=on`.
Operational metrics are separate again: OpenTelemetry export
(`HEADROOM_OTEL_METRICS_*`) is opt-in and targets a collector you specify.
+16
View File
@@ -73,6 +73,22 @@ print(result.strategy) # e.g. "lossless:table(...)" or "smart_sample(1000->15)"
</Tab>
</Tabs>
### Recovered tool output in the Python message transform
`SmartCrusher.apply(messages, tokenizer)` preserves recognized
`headroom_retrieve` results byte for byte when their call ID matches the
originating assistant call. The originating identity is resolved with the
shared wrapper parser for both OpenAI `tool_calls`/`arguments` and Anthropic
`tool_use`/`input`, including Hermes `tool_call` bridges and retrieval calls
inside `execute`, `exec`, or `functions.exec`.
Other wrapper output remains compressible; an unrecognized or ambiguous
wrapper does not gain a blanket recovery exemption. Keep the originating
assistant call in the message history so the result can be identified.
The context-free `crush(json_string)` API has no originating-call history and
does not provide this message-level exemption.
## Configuration
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
+13 -4
View File
@@ -144,10 +144,19 @@ remote, and profile-specific settings should use `--settings-file` explicitly.
## Enterprise
GitHub.com Enterprise Cloud normally requires no override; Headroom uses the API
URL advertised during token exchange. For GitHub Enterprise Server/custom domains,
set `GITHUB_COPILOT_ENTERPRISE_URL` or `GITHUB_COPILOT_ENTERPRISE_DOMAIN` before
both `copilot-auth login` and `wrap vscode`.
GitHub.com Enterprise Cloud normally requires no override. Copilot Business and
Enterprise seats are routed to the host GitHub advertises during token exchange
(`api.business.githubcopilot.com` or `api.enterprise.githubcopilot.com`), which is
the host GitHub's own clients use. This matters on networks that follow GitHub's
[subscription-based network routing](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-access/manage-network-access):
their firewall allows only the plan host, and the generic `api.githubcopilot.com`
is blocked. If the plan host rejects a model the generic host serves, set
`GITHUB_COPILOT_USE_ADVERTISED_HOST=0` to route through the generic host again.
An explicit `GITHUB_COPILOT_API_URL` still wins over both.
For GitHub Enterprise Server/custom domains, set `GITHUB_COPILOT_ENTERPRISE_URL`
or `GITHUB_COPILOT_ENTERPRISE_DOMAIN` before both `copilot-auth login` and
`wrap vscode`.
## Verification and troubleshooting
+393 -444
View File
File diff suppressed because it is too large Load Diff
+13 -13
View File
@@ -13,33 +13,33 @@
"postinstall": "fumadocs-mdx"
},
"dependencies": {
"@radix-ui/react-slot": "1.3.3",
"@radix-ui/react-slot": "1.5.0",
"class-variance-authority": "0.7.1",
"clsx": "2.1.1",
"dotted-map": "^3.1.0",
"fumadocs-core": "16.15.15",
"fumadocs-mdx": "15.4.5",
"fumadocs-twoslash": "^4.0.1",
"fumadocs-typescript": "^5.4.1",
"fumadocs-ui": "16.15.15",
"fumadocs-core": "16.17.1",
"fumadocs-mdx": "15.4.7",
"fumadocs-twoslash": "^4.0.2",
"fumadocs-typescript": "^5.5.1",
"fumadocs-ui": "16.17.1",
"lucide-react": "^1.48.0",
"next": "^16.3.8",
"next": "^16.4.0",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"recharts": "^3.10.1",
"tailwind-merge": "^3.7.0"
},
"devDependencies": {
"@ai-sdk/openai": "^4.0.79",
"@anthropic-ai/sdk": "^0.129.0",
"@ai-sdk/openai": "^4.0.91",
"@anthropic-ai/sdk": "^0.133.0",
"@tailwindcss/postcss": "^4.3.3",
"@types/mdx": "^2.0.14",
"@types/node": "^26.6.3",
"@types/node": "^26.6.5",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"ai": "7.0.119",
"openai": "^7.23.0",
"postcss": "^8.5.28",
"ai": "7.0.137",
"openai": "^7.32.0",
"postcss": "^8.5.29",
"tailwindcss": "^4.2.2",
"typescript": "^7.0.2"
},
+2825 -336
View File
File diff suppressed because it is too large Load Diff
+4 -3
View File
@@ -4,10 +4,11 @@
"private": true,
"description": "Locked CLI dependencies for the Docker wrap E2E harness",
"dependencies": {
"@openai/codex": "0.158.0",
"openclaw": "2026.9.6"
"@openai/codex": "0.162.1",
"openclaw": "2026.10.2"
},
"overrides": {
"@modelcontextprotocol/sdk": "1.32.1"
"@modelcontextprotocol/sdk": "1.32.1",
"npm": "12.2.1"
}
}
+42 -15
View File
@@ -29,6 +29,7 @@ from pathlib import Path
from typing import TYPE_CHECKING, Any
from ...fileperms import ensure_private_file
from ...log_safety import WarnOnce, safe_id
if TYPE_CHECKING:
from ..compression_store import CompressionEntry
@@ -51,6 +52,11 @@ DROP INDEX IF EXISTS idx_ccr_expiry;
# Purge expired rows at most this often (seconds). Purging is hygiene,
# not correctness — CompressionStore checks TTL on every get().
_PURGE_INTERVAL = 60.0
# items() decodes every row on each eviction pass, so an unreadable row warns
# once per hash per hour (WarnOnce's window), for at most this many hashes per
# hour; further ones log at debug only. A row that stays broken warns again
# about once an hour, which keeps it visible without flooding.
_MAX_REPORTED_UNREADABLE = 1000
def default_db_path() -> Path:
@@ -83,6 +89,9 @@ class SQLiteBackend:
self._path.parent.mkdir(parents=True, exist_ok=True)
self._lock = threading.Lock()
self._last_purge = 0.0
self._unreadable_warned = WarnOnce(
_MAX_REPORTED_UNREADABLE, "unreadable CCR SQLite entries"
)
self._conn = self._open()
@staticmethod
@@ -147,7 +156,9 @@ class SQLiteBackend:
log and treat the operation as a miss; never destroy data over a
transient error."""
if not self._is_corruption(error):
logger.warning("CCR SQLite %s failed (transient, no reset): %s", op, error)
logger.warning(
"CCR SQLite %s failed on %s (transient, no reset): %s", op, self._path, error
)
return
logger.warning(
"CCR SQLite store at %s is corrupt (%s); recreating. "
@@ -161,26 +172,42 @@ class SQLiteBackend:
except Exception: # noqa: BLE001 - best-effort close on corrupt handle
pass
self._path.unlink(missing_ok=True)
self._unreadable_warned = WarnOnce(
_MAX_REPORTED_UNREADABLE, "unreadable CCR SQLite entries"
)
self._conn = self._open()
def _entry_from_json(self, raw: str) -> CompressionEntry | None:
def _report_unreadable(self, hash_key: str, reason: object) -> None:
first = self._unreadable_warned.first(hash_key, logger)
logger.log(
logging.WARNING if first else logging.DEBUG,
"CCR SQLite entry %s in %s is unreadable (%s); treating as a miss",
safe_id(hash_key),
self._path,
reason,
)
def _entry_from_json(self, raw: str, hash_key: str) -> CompressionEntry | None:
from ..compression_store import CompressionEntry
try:
data = json.loads(raw)
except (json.JSONDecodeError, TypeError):
except (json.JSONDecodeError, TypeError) as e:
self._report_unreadable(hash_key, type(e).__name__)
return None
if not isinstance(data, dict):
self._report_unreadable(hash_key, "not a JSON object")
return None
known = {f.name for f in fields(CompressionEntry)}
try:
return CompressionEntry(**{k: v for k, v in data.items() if k in known})
except (TypeError, ValueError):
except (TypeError, ValueError) as e:
# A blob that parses as JSON but is missing a required field (schema
# drift across an upgrade, a partially written row) must degrade to a
# miss, not raise. Otherwise a single bad row crashes get() — and,
# via items(), _clean_expired() runs it on every store's eviction, so
# one poison row would break all reads, evictions, and stores.
self._report_unreadable(hash_key, type(e).__name__)
return None
def _purge_expired(self, now: float) -> int:
@@ -217,11 +244,11 @@ class SQLiteBackend:
(hash_key,),
).fetchone()
except sqlite3.DatabaseError as e:
self._handle_db_error(e, "get")
self._handle_db_error(e, f"get {safe_id(hash_key)}")
return None
if row is None:
return None
return self._entry_from_json(row[0])
return self._entry_from_json(row[0], hash_key)
def set(self, hash_key: str, entry: CompressionEntry) -> None:
payload = json.dumps(asdict(entry), ensure_ascii=False)
@@ -235,7 +262,7 @@ class SQLiteBackend:
self._conn.commit()
self._maybe_purge()
except sqlite3.DatabaseError as e:
self._handle_db_error(e, "set")
self._handle_db_error(e, f"set {safe_id(hash_key)}")
def delete(self, hash_key: str) -> bool:
with self._lock:
@@ -247,7 +274,7 @@ class SQLiteBackend:
self._conn.commit()
return cur.rowcount > 0
except sqlite3.DatabaseError as e:
self._handle_db_error(e, "op")
self._handle_db_error(e, f"delete {safe_id(hash_key)}")
return False
def exists(self, hash_key: str) -> bool:
@@ -258,7 +285,7 @@ class SQLiteBackend:
(hash_key,),
).fetchone()
except sqlite3.DatabaseError as e:
self._handle_db_error(e, "op")
self._handle_db_error(e, f"exists {safe_id(hash_key)}")
return False
return row is not None
@@ -268,14 +295,14 @@ class SQLiteBackend:
self._conn.execute("DELETE FROM ccr_entries")
self._conn.commit()
except sqlite3.DatabaseError as e:
self._handle_db_error(e, "op")
self._handle_db_error(e, "clear")
def count(self) -> int:
with self._lock:
try:
row = self._conn.execute("SELECT COUNT(*) FROM ccr_entries").fetchone()
except sqlite3.DatabaseError as e:
self._handle_db_error(e, "op")
self._handle_db_error(e, "count")
return 0
return int(row[0])
@@ -294,7 +321,7 @@ class SQLiteBackend:
try:
rows = self._conn.execute("SELECT hash FROM ccr_entries").fetchall()
except sqlite3.DatabaseError as e:
self._handle_db_error(e, "op")
self._handle_db_error(e, "keys")
return []
return [r[0] for r in rows]
@@ -303,11 +330,11 @@ class SQLiteBackend:
try:
rows = self._conn.execute("SELECT hash, entry_json FROM ccr_entries").fetchall()
except sqlite3.DatabaseError as e:
self._handle_db_error(e, "op")
self._handle_db_error(e, "items")
return []
out: list[tuple[str, CompressionEntry]] = []
for hash_key, raw in rows:
entry = self._entry_from_json(raw)
entry = self._entry_from_json(raw, hash_key)
if entry is not None:
out.append((hash_key, entry))
return out
@@ -317,7 +344,7 @@ class SQLiteBackend:
try:
count_row = self._conn.execute("SELECT COUNT(*) FROM ccr_entries").fetchone()
except sqlite3.DatabaseError as e:
self._handle_db_error(e, "op")
self._handle_db_error(e, "stats")
count_row = (0,)
try:
bytes_used = self._path.stat().st_size
+12 -1
View File
@@ -43,6 +43,8 @@ from contextvars import ContextVar
from dataclasses import dataclass, field, replace
from typing import TYPE_CHECKING, Any
from ..log_safety import describe_exception, safe_id
if TYPE_CHECKING:
from ..memory.tracker import ComponentStats
from .backends import CompressionStoreBackend
@@ -1164,7 +1166,16 @@ def _create_default_ccr_backend() -> CompressionStoreBackend | None:
backend: CompressionStoreBackend = fn(**kwargs)
return backend
except Exception as e:
logger.warning("Failed to load CCR backend %s: %s", backend_type, e)
# The backend's exception can echo HEADROOM_REDIS_URL (credentials included),
# so no level logs its message; DEBUG gets describe_exception (types and frames).
logger.warning(
"Failed to load CCR backend %s (%s); falling back to the in-process store. "
"Retrieval will not survive proxy restarts or cross worker processes.",
backend_type,
safe_id(e),
)
if logger.isEnabledFor(logging.DEBUG):
logger.debug("CCR backend %s load failure: %s", backend_type, describe_exception(e))
return None
+142 -22
View File
@@ -23,7 +23,8 @@ import json
import logging
import os
import time
from collections import OrderedDict
from collections import OrderedDict, deque
from contextvars import ContextVar
from dataclasses import dataclass
from typing import Any
@@ -63,6 +64,22 @@ _PROVIDER_CACHE_TTL_SECONDS = {
# cold-prefix detection, but never below the configured session cleanup floor.
_CACHE_TTL_CLEANUP_MARGIN_SECONDS = 60
# Recent request snapshots kept per lineage. A Claude Code fork (the subagent
# progress summary, the parent's side query) re-sends the history plus one
# prompt, so the next real turn extends the snapshot BEFORE the fork. A
# request that resumes an older snapshot keeps it next-newest, so any number
# of forks off one turn leaves that turn resumable.
_LINEAGE_HISTORY = 3
# (tracker, turn, resumed state) the current request resolved to. Each proxied
# request runs in its own asyncio task, so it reads the state it resumed and
# ``update_from_response`` records its response against its own turn, even
# while a fork of the same conversation is in flight on the same tracker. Same
# pattern as the request-scoped tenant key and CCR store.
_resolved_turn: ContextVar[tuple[Any, int, tuple[Any, ...] | None] | None] = ContextVar(
"headroom_resolved_lineage_turn", default=None
)
@dataclass
class PrefixFreezeConfig:
@@ -1153,6 +1170,11 @@ class PrefixCacheTracker:
# net-cost/TTL P_alive gate could never see idle time. The handler reads
# this and forwards it to the pipeline as `idle_seconds`.
self._idle_seconds_at_fetch: float = 0.0
# Turn state after each recent request's response (None while it is in
# flight), keyed by the turn SessionTrackerStore issued it. A request
# resumes the state of the turn it extends, so a fork's response never
# becomes the main line's frozen prefix or replay source.
self._turn_states: dict[int, tuple[Any, ...] | None] = {}
# Session-scoped ReadMaturationManager (Mechanism B), created
# lazily by the handler when read maturation is enabled. Rides
@@ -1169,13 +1191,14 @@ class PrefixCacheTracker:
Returns 0 on turn 0 (cold start) or if caching is disabled/below threshold.
"""
turn_number, cached_tokens, cached_messages, _, _ = self._request_turn_state()
if not self.config.enabled:
return 0
if self._turn_number == 0:
if turn_number == 0:
return 0
if self._cached_token_count < self.config.min_cached_tokens:
if cached_tokens < self.config.min_cached_tokens:
return 0
return self._cached_message_count
return int(cached_messages)
def update_from_response(
self,
@@ -1208,6 +1231,7 @@ class PrefixCacheTracker:
if total_cached == 0:
self._cached_token_count = 0
self._cached_message_count = 0
self._record_turn_state()
return
# Estimate per-message token counts if not provided
@@ -1227,6 +1251,7 @@ class PrefixCacheTracker:
self._cached_token_count = total_cached
self._cached_message_count = frozen_count
self._record_turn_state()
logger.debug(
"PrefixCacheTracker[%s]: turn=%d, cached=%d tokens, "
@@ -1241,10 +1266,56 @@ class PrefixCacheTracker:
)
def get_last_original_messages(self) -> list[dict[str, Any]]:
return copy.deepcopy(self._last_original_messages)
return copy.deepcopy(self._request_turn_state()[3])
def get_last_forwarded_messages(self) -> list[dict[str, Any]]:
return copy.deepcopy(self._last_forwarded_messages)
return copy.deepcopy(self._request_turn_state()[4])
def _turn_state(self) -> tuple[Any, ...]:
return (
self._turn_number,
self._cached_token_count,
self._cached_message_count,
self._last_original_messages,
self._last_forwarded_messages,
)
def _request_turn_state(self) -> tuple[Any, ...]:
"""The state this request resumed at resolve time, else the current one.
A handler may read after an ``await`` (OpenAI's overlay runs after
compression), by which time a sibling request on this lineage may have
resumed a different turn.
"""
resolved = _resolved_turn.get()
if resolved is not None and resolved[0] is self and resolved[2] is not None:
return resolved[2]
return self._turn_state()
def _record_turn_state(self) -> None:
"""Remember this response's state under the turn that sent it."""
resolved = _resolved_turn.get()
if resolved is not None and resolved[0] is self:
if resolved[1] in self._turn_states:
self._turn_states[resolved[1]] = self._turn_state()
# The request has its response; later reads see the current state.
_resolved_turn.set((self, resolved[1], None))
def _resume_turn(self, turn: int | None) -> None:
"""Continue from ``turn``'s response, not whichever response came last.
A turn still in flight (or one recorded before turn tracking) has no
state yet; the current state stands, as it did before.
"""
state = self._turn_states.get(turn) if turn is not None else None
if state is not None:
(
self._turn_number,
self._cached_token_count,
self._cached_message_count,
self._last_original_messages,
self._last_forwarded_messages,
) = state
def record_returned(
self,
@@ -1311,7 +1382,8 @@ class PrefixCacheTracker:
if idle_seconds is None:
idle_seconds = self.seconds_since_activity()
ttl = self.resolved_cache_ttl_seconds()
expected = self._cached_token_count
# The turn this request resumed, not whichever sibling answered last.
expected = self._request_turn_state()[1]
# Nothing was cached last turn → cold start, not a miss.
if expected <= 0:
@@ -1366,7 +1438,7 @@ class PrefixCacheTracker:
content. Anything else (a frozen message rewritten, the prefix
reordered, the list now shorter) counts as a prefix change.
"""
prev = self._last_forwarded_messages
prev: list[dict[str, Any]] = self._request_turn_state()[4]
if not prev:
# No recorded prefix to compare — can't claim it changed.
return True
@@ -1565,6 +1637,10 @@ class SessionTrackerStore:
# but different tool profiles must never share frozen-prefix state.
self._lineage_affinities: dict[str, str | None] = {}
self._lineage_counter = itertools.count(1)
# Recent (snapshot, turn) per tracker key, newest first; the newest
# snapshot is the one in ``_lineages``.
self._lineage_history: dict[str, deque[tuple[list[Any], int]]] = {}
self._turn_counter = itertools.count(1)
def peek(self, session_id: str) -> PrefixCacheTracker | None:
"""Return the live tracker for ``session_id``, else None.
@@ -1614,6 +1690,7 @@ class SessionTrackerStore:
def _discard_tracker(self, tracker_key: str) -> None:
"""Remove a tracker and any lineage indexes that point to it."""
self._trackers.pop(tracker_key, None)
self._lineage_history.pop(tracker_key, None)
for session_id, family in list(self._lineages.items()):
family.pop(tracker_key, None)
self._lineage_affinities.pop(tracker_key, None)
@@ -1707,22 +1784,48 @@ class SessionTrackerStore:
for key in expired_keys:
family.pop(key, None)
self._lineage_affinities.pop(key, None)
self._lineage_history.pop(key, None)
self._trackers.pop(key, None)
by_length = sorted(family.items(), key=lambda item: len(item[1]), reverse=True)
best_key: str | None = None
for accepted in (
(RELATION_EXACT, RELATION_MESSAGE_APPEND),
(RELATION_BLOCK_APPEND,),
):
for key, chain in by_length:
if self._lineage_affinities.get(key) != cache_affinity:
continue
relation = _classify_history_canonical(snap, chain)
if relation.kind in accepted:
best_key = key
break
if best_key is not None:
break
def continuation(
candidates: list[tuple[str, list[Any], int | None]],
) -> tuple[str | None, int | None]:
for accepted in (
(RELATION_EXACT, RELATION_MESSAGE_APPEND),
(RELATION_BLOCK_APPEND,),
):
for key, chain, turn in candidates:
if self._lineage_affinities.get(key) != cache_affinity:
continue
if _classify_history_canonical(snap, chain).kind in accepted:
return key, turn
return None, None
def latest_turn(key: str) -> int | None:
history = self._lineage_history.get(key)
return history[0][1] if history else None
best_key, best_turn = continuation(
[(key, chain, latest_turn(key)) for key, chain in by_length]
)
if best_key is None:
# A fork (Claude Code's subagent summary or side query: the
# history plus one prompt) became a lineage's latest snapshot, so
# this turn extends the snapshot before it. Resume that turn
# instead of starting a cold lineage that recompresses history the
# provider already cached.
best_key, best_turn = continuation(
sorted(
(
(key, chain, turn)
for key in family
for chain, turn in list(self._lineage_history.get(key, ()))[1:]
),
key=lambda item: len(item[1]),
reverse=True,
)
)
if best_key is None:
rewrite_candidates: list[tuple[tuple[int, int, int], str]] = []
@@ -1808,6 +1911,22 @@ class SessionTrackerStore:
family = self._lineages.setdefault(session_id, family)
family[best_key] = snap
self._lineage_affinities[best_key] = cache_affinity
if isinstance(tracker, PrefixCacheTracker): # test stubs keep no turns
tracker._resume_turn(best_turn if best_turn is not None else latest_turn(best_key))
turn = next(self._turn_counter)
history = self._lineage_history.setdefault(best_key, deque(maxlen=_LINEAGE_HISTORY))
branch = next((entry for entry in history if entry[1] == best_turn), None)
if branch is not None and branch is not history[0]:
# A fork off an older turn: that turn stays the branch point the
# next main turn extends, so keep it behind this request rather
# than let successive forks push it out.
history.remove(branch)
history.appendleft(branch)
history.appendleft((snap, turn))
live = {t for _, t in history}
tracker._turn_states = {t: s for t, s in tracker._turn_states.items() if t in live}
tracker._turn_states[turn] = None
_resolved_turn.set((tracker, turn, tracker._turn_state()))
return tracker
def compute_session_id(
@@ -1877,6 +1996,7 @@ class SessionTrackerStore:
for key in [k for k in family if k not in self._trackers]:
del family[key]
self._lineage_affinities.pop(key, None)
self._lineage_history.pop(key, None)
if not family:
del self._lineages[base]
logger.debug("SessionTrackerStore: cleaned up %d expired sessions", len(expired))
+2 -2
View File
@@ -403,7 +403,7 @@ class BatchResultProcessor:
"""Make Google/Gemini continuation call.
Note: Google format uses 'contents' not 'messages',
and 'parts' format for messages.
and 'parts' format for messages. Tools are already native Google Tool objects.
"""
model = request_context.model
url = f"{self.api_urls['google']}/v1beta/models/{model}:generateContent"
@@ -424,7 +424,7 @@ class BatchResultProcessor:
# Add tools
if tools:
body["tools"] = [{"functionDeclarations": tools}]
body["tools"] = tools
response = await self.http_client.post(
url,
+10 -5
View File
@@ -91,9 +91,9 @@ class BatchContextStore:
Features:
- TTL-based expiration
- Automatic cleanup of expired entries
- Expired entries reclaimed before live contexts are evicted at capacity
- Thread-safe operations
- Memory limits
- Memory limits; replacing a batch refreshes its TTL without evicting another batch
Usage:
store = BatchContextStore()
@@ -135,7 +135,7 @@ class BatchContextStore:
"""
async with self._lock:
# Enforce memory limit
if len(self._contexts) >= self._max_contexts:
if context.batch_id not in self._contexts and len(self._contexts) >= self._max_contexts:
# Remove oldest entries
await self._cleanup_oldest()
@@ -205,10 +205,15 @@ class BatchContextStore:
async def _cleanup_oldest(self) -> None:
"""Remove oldest entries to make room for new ones."""
# Sort by creation time, remove oldest 10%
if not self._contexts:
now = time.time()
expired = [batch_id for batch_id, ctx in self._contexts.items() if ctx.expires_at < now]
for batch_id in expired:
del self._contexts[batch_id]
if len(self._contexts) < self._max_contexts:
return
# Sort remaining live contexts by creation time, remove oldest 10%.
sorted_entries = sorted(
self._contexts.items(),
key=lambda x: x[1].created_at,
+42 -14
View File
@@ -36,6 +36,7 @@ from typing import TYPE_CHECKING, Any
from headroom import paths as _paths
from headroom import savings_ledger
from headroom.cache.compression_store import format_retrieval_miss_detail
from headroom.log_safety import describe_exception, redact_url, safe_id
from headroom.telemetry import session as telemetry_session
if TYPE_CHECKING:
@@ -226,8 +227,13 @@ def _append_shared_event(event: dict[str, Any]) -> None:
f.write(line)
if _HAS_FCNTL:
fcntl.flock(f, fcntl.LOCK_UN)
except Exception:
pass # Never break compression because of stats
except Exception as exc:
# Never break compression because of stats
logger.debug(
"MCP session stats: append to %s failed: %s",
SHARED_STATS_FILE,
describe_exception(exc),
)
def _read_shared_events(window_seconds: int = SESSION_WINDOW_SECONDS) -> list[dict[str, Any]]:
@@ -265,10 +271,18 @@ def _read_shared_events(window_seconds: int = SESSION_WINDOW_SECONDS) -> list[di
f.writelines(keep_lines)
if _HAS_FCNTL:
fcntl.flock(f, fcntl.LOCK_UN)
except Exception:
pass
except Exception:
pass
except Exception as exc:
logger.debug(
"MCP session stats: pruning %s failed: %s",
SHARED_STATS_FILE,
describe_exception(exc),
)
except Exception as exc:
logger.debug(
"MCP session stats: reading %s failed: %s",
SHARED_STATS_FILE,
describe_exception(exc),
)
return events
@@ -529,8 +543,14 @@ class HeadroomMCPServer:
result["source"] = "proxy"
self._stats.record_retrieval(hash_key)
return result
except Exception:
pass # Proxy unavailable, that's fine
except Exception as exc:
# Proxy unavailable is expected; log so a bug here is not silent.
logger.debug(
"MCP retrieve: proxy fallback failed for hash=%s via %s: %s",
safe_id(hash_key),
redact_url(self.proxy_url),
describe_exception(exc),
)
if expired_entry_status:
ttl_seconds = expired_entry_status.get(
@@ -795,8 +815,8 @@ class HeadroomMCPServer:
# restarts. Best-effort: never let savings bookkeeping break the tool.
try:
self._record_savings(result)
except Exception:
logger.debug("durable savings recording failed", exc_info=True)
except Exception as exc:
logger.debug("durable savings recording failed: %s", describe_exception(exc))
proxy_status = await self._probe_proxy_unreachable()
if proxy_status:
@@ -845,8 +865,11 @@ class HeadroomMCPServer:
name = getattr(info, "name", None)
if name:
return str(name)
except Exception:
pass
except (LookupError, AttributeError) as exc:
# Outside a request there is no request context; fall back to "unknown".
logger.debug(
"MCP client name unavailable; reporting 'unknown': %s", describe_exception(exc)
)
return "unknown"
async def _handle_retrieve(self, arguments: dict[str, Any]) -> list[TextContent]:
@@ -945,7 +968,12 @@ class HeadroomMCPServer:
return None
result: dict[str, Any] = response.json()
return result
except Exception:
except Exception as exc:
logger.debug(
"MCP stats: proxy /stats fetch failed via %s: %s",
redact_url(self.proxy_url),
describe_exception(exc),
)
return None
@staticmethod
@@ -1113,7 +1141,7 @@ class HeadroomMCPServer:
watchdog forces shutdown once we are reparented.
"""
async with stdio_server() as (read_stream, write_stream):
logger.info(f"Headroom MCP Server starting (proxy: {self.proxy_url})")
logger.info("Headroom MCP Server starting (proxy: %s)", redact_url(self.proxy_url))
serve_task = asyncio.create_task(
self.server.run(
read_stream,
+2 -2
View File
@@ -449,7 +449,7 @@ def _run_memory_eval(
from headroom.memory import MemoryConfig
except ImportError as e:
click.echo("Error: Memory eval dependencies not installed.")
click.echo("Run: pip install headroom[memory,evals]")
click.echo('Run: pip install "headroom-ai[memory,evals]"')
click.echo(f"Details: {e}")
raise SystemExit(1) from None
@@ -621,7 +621,7 @@ def _run_memory_eval_v2(
)
except ImportError as e:
click.echo("Error: Memory eval V2 dependencies not installed.")
click.echo("Run: pip install headroom[memory,evals]")
click.echo('Run: pip install "headroom-ai[memory,evals]"')
click.echo(f"Details: {e}")
raise SystemExit(1) from None
+4 -3
View File
@@ -604,7 +604,8 @@ def _build_deployment_manifest(
region=region,
proxy_mode=proxy_mode,
memory_enabled=memory,
telemetry_enabled=telemetry and not no_telemetry,
# --no-telemetry wins when both are given; neither leaves it unset.
telemetry_enabled=False if no_telemetry else (True if telemetry else None),
no_rate_limit=no_rate_limit,
image=image,
no_http2=no_http2,
@@ -875,7 +876,7 @@ def _echo_installed(manifest: DeploymentManifest, *, prefix: str = "Installed pe
@click.option(
"--no-telemetry",
is_flag=True,
help="Force anonymous telemetry off in the runtime (already the default).",
help="Turn off local stats and the anonymous upload beacon in the runtime.",
)
@click.option(
"--no-rate-limit",
@@ -1092,7 +1093,7 @@ def install_apply(
@click.option(
"--no-telemetry",
is_flag=True,
help="Force anonymous telemetry off in the runtime (already the default).",
help="Turn off local stats and the anonymous upload beacon in the runtime.",
)
@click.option(
"--image",
+7 -4
View File
@@ -120,16 +120,19 @@ def candidate_ports(
return seen[:_MAX_CANDIDATES]
def probe_headroom_proxy(port: int, timeout: float = _PROBE_TIMEOUT_SECONDS) -> bool:
"""True when a Headroom proxy answers ``/livez`` on loopback ``port``.
def probe_headroom_proxy(
port: int, timeout: float = _PROBE_TIMEOUT_SECONDS, *, host: str = "127.0.0.1"
) -> bool:
"""True when a Headroom proxy answers ``/livez`` on ``host:port`` (loopback by default).
Requires the ``service: headroom-proxy`` identity (or the legacy
``alive``+``version`` shape) so an unrelated local server on the port is
never mistaken for Headroom.
never mistaken for Headroom. ``host`` is a numeric IPv4 or IPv6 address.
"""
from headroom.install.health import probe_json
return is_headroom_livez(probe_json(f"http://127.0.0.1:{port}/livez", timeout=timeout))
netloc = f"[{host}]" if ":" in host else host
return is_headroom_livez(probe_json(f"http://{netloc}:{port}/livez", timeout=timeout))
def is_headroom_livez(payload: Mapping[str, Any] | None) -> bool:
+99 -1
View File
@@ -1,8 +1,11 @@
"""Proxy server CLI commands."""
import errno
import ipaddress
import logging
import os
import platform
import socket
import sys
import warnings
from importlib.util import find_spec
@@ -195,6 +198,99 @@ def _get_env_int(name: str, default: int) -> int:
return default if value is None else value
def _tcp_port_in_use(host: str, port: int, *, workers: int) -> tuple[OSError, Any] | None:
"""Return ``(EADDRINUSE error, busy address)`` uvicorn would hit binding ``host:port``.
Returns None when the bind would succeed.
Mirrors uvicorn's own bind so the probe never refuses a bind uvicorn would
accept: ``SO_REUSEADDR`` (both uvicorn paths set it on POSIX, so a port in
TIME_WAIT after a restart is not "in use"); a single process binds every
address ``host`` resolves to (asyncio ``create_server``), while
``--workers > 1`` binds one AF_INET/AF_INET6 socket in the parent.
Windows ``SO_REUSEADDR`` semantics differ, so Windows is left to uvicorn,
as is any error other than EADDRINUSE (unresolvable host, address not on
this machine); uvicorn reports those as before.
"""
if sys.platform == "win32":
return None
if workers > 1:
family = socket.AF_INET6 if ":" in host else socket.AF_INET
targets: list[tuple[Any, Any]] = [(family, (host, port))]
else:
try:
infos = socket.getaddrinfo(
host or None, port, type=socket.SOCK_STREAM, flags=socket.AI_PASSIVE
)
except (OSError, UnicodeError):
return None
targets = [(info[0], info[4]) for info in infos]
for family, address in targets:
try:
with socket.socket(family, socket.SOCK_STREAM) as probe:
probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
if family == socket.AF_INET6 and workers <= 1:
# asyncio binds v4 and v6 separately; match it.
probe.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
probe.bind(address)
except OSError as exc:
if exc.errno == errno.EADDRINUSE:
return exc, address
return None
_WILDCARD_PROBE_HOSTS = {"": "127.0.0.1", "0.0.0.0": "127.0.0.1", "::": "::1"}
def _probe_host_for(address: Any) -> str | None:
"""The numeric address to ask "is this Headroom?", or None when it can't be targeted.
A wildcard bind is reached through loopback of the same family. A
hostname (the ``--workers > 1`` path binds it unresolved) is resolved for
IPv4. A scoped IPv6 address cannot go in a probe URL.
"""
host = str(address[0])
if host in _WILDCARD_PROBE_HOSTS:
return _WILDCARD_PROBE_HOSTS[host]
if "%" in host:
return None
try:
ipaddress.ip_address(host)
except ValueError:
try:
infos = socket.getaddrinfo(host, None, socket.AF_INET, socket.SOCK_STREAM)
except (OSError, UnicodeError):
return None
return str(infos[0][4][0]) if infos else None
return host
def _refuse_busy_port(host: str, port: int, *, workers: int) -> None:
"""Fail before the banner when ``host:port`` is already taken.
Without this the banner prints "Press Ctrl+C to stop", then uvicorn's bind
error is buried among startup and shutdown log lines.
"""
busy = _tcp_port_in_use(host, port, workers=workers)
if busy is None:
return
error, address = busy
from headroom.cli.port_discovery import probe_headroom_proxy
reason = error.strerror or str(error)
probe_host = _probe_host_for(address)
if probe_host is None:
holder = f"({reason})"
elif probe_headroom_proxy(port, host=probe_host):
holder = "by a running Headroom proxy (reuse it, or stop it first)"
else:
holder = f"by another process ({reason})"
raise click.ClickException(
f"Port {port} on {host} is already in use {holder}. "
"Start this proxy on another port with --port N (env: HEADROOM_PORT)."
)
@main.command()
@click.option(
"--port",
@@ -1016,7 +1112,7 @@ def dashboard(port: int, no_open: bool) -> None:
@click.option(
"--no-telemetry",
is_flag=True,
help="Force anonymous usage telemetry off (already the default; env: HEADROOM_TELEMETRY=off)",
help="Turn off local stats and the anonymous upload beacon (env: HEADROOM_TELEMETRY=off)",
)
@click.option(
"--stateless",
@@ -1685,6 +1781,8 @@ Memory (Multi-Provider):
_bind = evaluate_bind_policy(config.host, config.proxy_token)
if _bind.refused:
raise click.ClickException(_bind.message())
if not config.uds:
_refuse_busy_port(config.host, config.port, workers=workers)
_auth_on = _bind.token_configured
_open_bind_note = (
f" · WARNING open bind, /v1/* UNAUTHENTICATED (acknowledged via {OPEN_BIND_ACK_ENV}=1)"
+8 -4
View File
@@ -85,7 +85,7 @@ def telemetry(show: bool, as_json: bool) -> None:
headroom telemetry Current state and the two switches
headroom telemetry --show The exact payload, field by field
"""
from headroom.telemetry.beacon import is_beacon_enabled, is_telemetry_enabled
from headroom.telemetry.beacon import beacon_off_reason, is_telemetry_enabled
from headroom.telemetry.session import (
DEFAULT_ENDPOINT,
SCHEMA_VERSION,
@@ -94,7 +94,8 @@ def telemetry(show: bool, as_json: bool) -> None:
resource_attributes,
)
beacon_on = is_beacon_enabled()
beacon_off_by = beacon_off_reason()
beacon_on = beacon_off_by is None
local_on = is_telemetry_enabled()
known_id = read_install_id()
# Reported because it changes what goes on the wire, and because while the
@@ -134,7 +135,7 @@ def telemetry(show: bool, as_json: bool) -> None:
)
return
click.echo(f"Upload beacon: {'ON (opt-out)' if beacon_on else 'OFF'}")
click.echo(f"Upload beacon: {'ON (opt-out)' if beacon_on else f'OFF ({beacon_off_by})'}")
click.echo(f"Local stats: {'ON' if local_on else 'OFF (opt-in)'}")
click.echo(f"Endpoint: {DEFAULT_ENDPOINT}")
click.echo(
@@ -143,5 +144,8 @@ def telemetry(show: bool, as_json: bool) -> None:
)
click.echo(f"Install ID: {known_id or '(none yet — created on first upload)'}")
click.echo()
click.echo("Turn the beacon off: HEADROOM_BEACON=off (or DO_NOT_TRACK=1)")
if beacon_on:
click.echo(
"Turn the beacon off: HEADROOM_BEACON=off (or HEADROOM_TELEMETRY=off, DO_NOT_TRACK=1)"
)
click.echo("See the exact payload: headroom telemetry --show")
+171 -17
View File
@@ -695,6 +695,57 @@ def _get_proxy_stdio_log_path(port: int | None = None) -> Path:
return _get_log_path(port).with_name(_paths.proxy_stdio_log_path(port).name)
# A proxy that dies during startup logs its shutdown summary after the error,
# so the end of the log is the summary box, not the cause. Quote from the first
# error-looking line instead.
# Click's own failures (``click.ClickException``) print ``Error: ...`` at the
# start of a line.
_PROXY_STARTUP_ERROR_RE = re.compile(
r"\b(?:ERROR|CRITICAL)\b|Traceback \(most recent call last\)|^Error: ", re.MULTILINE
)
_PROXY_STARTUP_EXCERPT_CHARS = 500
# Never read a runaway log whole: look at most at the first and the last 64 KiB
# of this run's output. The error usually comes early, before the shutdown
# summary; the tail catches one that follows a long burst of startup output.
_PROXY_STARTUP_READ_BYTES = 64 * 1024
def _proxy_startup_failure_excerpt(stdio_log_path: Path, start: int) -> str:
"""Return the part of this run's stdio log that best explains a startup exit.
Reads only what was written after byte offset ``start`` (the log is shared
across runs): the first ``_PROXY_STARTUP_READ_BYTES`` of it and, when the run
wrote more and the head has no error, the last ``_PROXY_STARTUP_READ_BYTES``.
Prefers the first ERROR/CRITICAL/Traceback/``Error:`` line onwards, and falls
back to the last few hundred characters of the first non-blank window.
"""
try:
with open(stdio_log_path, "rb") as fh:
fh.seek(start)
windows = [fh.read(_PROXY_STARTUP_READ_BYTES)]
end = fh.seek(0, os.SEEK_END)
tail_start = max(start + _PROXY_STARTUP_READ_BYTES, end - _PROXY_STARTUP_READ_BYTES)
if end > tail_start and not _PROXY_STARTUP_ERROR_RE.search(
windows[0].decode("utf-8", errors="replace")
):
fh.seek(tail_start)
windows.append(fh.read(_PROXY_STARTUP_READ_BYTES))
except OSError:
return "(no log output)"
texts = [raw.decode("utf-8", errors="replace").strip() for raw in windows]
for output in texts:
match = _PROXY_STARTUP_ERROR_RE.search(output)
if match is not None:
line_start = output.rfind("\n", 0, match.start()) + 1
return output[line_start : line_start + _PROXY_STARTUP_EXCERPT_CHARS]
# No recognised error: quote the end of the first non-blank window, the head
# when it has text (the startup output), otherwise the tail.
for output in texts:
if output:
return output[-_PROXY_STARTUP_EXCERPT_CHARS:]
return "(no log output)"
def _start_proxy(
port: int,
*,
@@ -712,6 +763,7 @@ def _start_proxy(
copilot_api_token: str | None = None,
copilot_refresh_oauth_token: str | None = None,
copilot_api_token_expires_at: float | None = None,
proxy_extensions: list[str] | None = None,
) -> subprocess.Popen:
"""Start Headroom proxy as a background subprocess.
@@ -773,9 +825,22 @@ def _start_proxy(
if vertex_api_url:
cmd.extend(["--vertex-api-url", vertex_api_url])
# Extensions carried over from the proxy this one replaces (see
# ``_dedicated_proxy_extensions``). The flag outranks the envvar in click,
# so callers must not pass this when HEADROOM_PROXY_EXTENSIONS is set;
# ``_ensure_proxy_unlocked`` checks that before asking.
if proxy_extensions:
cmd.extend(["--proxy-extension", ",".join(proxy_extensions)])
timeout_seconds = _resolve_wrap_proxy_timeout_seconds()
log_path = _get_log_path(port)
stdio_log_path = _get_proxy_stdio_log_path(port)
# The stdio log is appended to across runs; remember where this run starts
# so a startup failure quotes this run's output, not an earlier one.
try:
stdio_log_start = stdio_log_path.stat().st_size
except OSError:
stdio_log_start = 0
stdio_log_file = open(stdio_log_path, "a", encoding="utf-8") # noqa: SIM115
# Ensure proxy subprocess uses UTF-8 (Windows defaults to cp1252)
@@ -896,17 +961,17 @@ def _start_proxy(
return proc
# Check if process died
if proc.poll() is not None:
# Read last few lines of log for error context
try:
tail = _read_text(stdio_log_path)[-500:]
except Exception:
tail = "(no log output)"
raise RuntimeError(f"Proxy exited with code {proc.returncode}: {tail}")
excerpt = _proxy_startup_failure_excerpt(stdio_log_path, stdio_log_start)
raise RuntimeError(
f"Proxy exited with code {proc.returncode}: {excerpt}\n"
f" Full log: {stdio_log_path}"
)
proc.kill()
raise RuntimeError(
f"Proxy failed to start on port {port} within {timeout_seconds} seconds. "
f"Set {_WRAP_PROXY_TIMEOUT_ENV} to a larger number of seconds for slow startup."
f"Set {_WRAP_PROXY_TIMEOUT_ENV} to a larger number of seconds for slow startup.\n"
f" Full log: {stdio_log_path}"
)
finally:
stdio_log_file.close()
@@ -4527,6 +4592,68 @@ def _echo_unwrap_proxy_stop_status(status: str, port: int) -> None:
click.echo(f" Warning: failed to stop Headroom proxy on port {port}; stop it manually.")
def _manifest_proxy_extensions(manifest: Any) -> list[str] | None:
"""Extension names a persistent deployment was installed with.
Two places in the manifest can say: ``--proxy-extension`` flags in
``proxy_args``, which the runtime passes to the proxy verbatim (an operator
who edited the manifest by hand), and ``HEADROOM_PROXY_EXTENSIONS`` in
``base_env`` (``headroom install --env ...``, the only form the installer
writes). They are read the way the proxy reads them: click lets the flag
outrank the environment variable, so when ``proxy_args`` names any
extension that list is the whole answer and ``base_env`` is ignored.
A manifest with neither is no evidence either way: the deployment's
runtime env is layered on the launch environment, so the proxy may still
have inherited a set. Only an explicit value (possibly empty) is an answer.
"""
flags: list[str] = []
args = getattr(manifest, "proxy_args", None)
if isinstance(args, (list, tuple)):
for i, arg in enumerate(args):
if arg == "--proxy-extension" and i + 1 < len(args):
flags.append(str(args[i + 1]))
elif isinstance(arg, str) and arg.startswith("--proxy-extension="):
flags.append(arg.partition("=")[2])
if flags:
values = flags
else:
base_env = getattr(manifest, "base_env", None)
configured = (
base_env.get("HEADROOM_PROXY_EXTENSIONS") if isinstance(base_env, dict) else None
)
if not isinstance(configured, str):
return None
values = [configured]
return sorted({name.strip() for value in values for name in value.split(",") if name.strip()})
def _dedicated_proxy_extensions(port: int, manifest: Any) -> list[str] | None:
"""Extensions the proxy owning *port* runs with, for a dedicated proxy to carry.
A wrap that cannot reuse the proxy on its port (a Copilot subscription
seed, or a persistent deployment with other routing) starts a dedicated
proxy from the shell environment alone. An enterprise install enables its
savings sinks on the shared proxy as ``--proxy-extension``, so without
this the dedicated proxy would report nothing upstream while its local
dashboard fills (#3716). Prefers the running proxy's own answer over the
manifest. Returns ``None`` when neither says, so the caller warns rather
than start bare on a guess.
"""
helpers = _live_wrap_module()
payload = helpers._query_proxy_health(port)
if payload is not None and not helpers._is_headroom_health(payload):
return [] # a foreign service holds the port; it ran no extensions
running = helpers._proxy_health_config(payload)
found = running.get("proxy_extensions") if running is not None else None
if isinstance(found, list):
return sorted(str(name) for name in found)
# No config, or a proxy too old to report the field: the manifest is the
# next best witness.
if manifest is not None:
return _manifest_proxy_extensions(manifest)
return None
def _find_persistent_manifest(port: int) -> Any:
"""Return a matching persistent deployment manifest for the requested port."""
from headroom.install.state import list_manifests
@@ -4958,13 +5085,13 @@ def _ensure_proxy_unlocked(
f" Port {port} is in use by a non-Headroom service; selecting another port..."
)
proxy_listener = False
# Set False when the running proxy must not serve this session at all
# (unverifiable config, or a routing-level mismatch with live clients
# attached): fall through to a fresh start on a different port.
reuse_running = True
if proxy_listener:
# Proxy is running — check if it has the features we need
needs_restart = False
# Set False when the running proxy must not serve this session at
# all (routing-level mismatch with live clients attached): fall
# through to a fresh start on a different port.
reuse_running = True
routing_mismatches = (
None
if running_config is None
@@ -5166,6 +5293,30 @@ def _ensure_proxy_unlocked(
else:
click.echo(f" Port {port} is in use, using port {actual_port} instead.")
# This start leaves a running proxy on `port` in place and serves the
# session from `actual_port` beside it. Whatever that proxy reports
# through (an enterprise install's extensions) must come along, or the
# session's traffic vanishes from the team's dashboard while the local
# one fills (#3716).
replaces_running_proxy = (
isolated_copilot_subscription_proxy
or persistent_routing_mismatch
or (proxy_listener and not reuse_running)
)
proxy_extensions: list[str] | None = None
if replaces_running_proxy and "HEADROOM_PROXY_EXTENSIONS" not in os.environ:
proxy_extensions = helpers._dedicated_proxy_extensions(port, manifest)
if proxy_extensions is None:
click.echo(
f" Warning: could not read the extensions of the proxy on port {port}; "
f"the dedicated proxy on port {actual_port} starts without any. "
"Set HEADROOM_PROXY_EXTENSIONS=<names> to carry them."
)
elif proxy_extensions:
click.echo(
f" Extensions carried over from the proxy on port {port}: "
f"{','.join(proxy_extensions)}"
)
click.echo(f" Starting Headroom proxy on port {actual_port}...")
try:
proc = cast(
@@ -5186,6 +5337,7 @@ def _ensure_proxy_unlocked(
copilot_api_token=copilot_api_token,
copilot_refresh_oauth_token=copilot_refresh_oauth_token,
copilot_api_token_expires_at=copilot_api_token_expires_at,
proxy_extensions=proxy_extensions,
),
)
click.echo(_proxy_status_line("Proxy ready", actual_port))
@@ -6575,11 +6727,13 @@ def copilot(
headroom wrap copilot --subscription -- --model gpt-4.1
\b
Copilot hosted API (--subscription and the implicit OAuth path) routes to the
generic host https://api.githubcopilot.com, which serves the full model set.
Enterprise / data-residency accounts provisioned on a dedicated host pin it
explicitly with GITHUB_COPILOT_API_URL (the override flows through to upstream).
See TESTING-copilot-subscription.md for details.
Copilot hosted API: --subscription routes Business / Enterprise seats to
the plan host GitHub advertises (GITHUB_COPILOT_USE_ADVERTISED_HOST=0 folds
them back to the generic host) and individual seats to the generic host
https://api.githubcopilot.com; the implicit OAuth path always uses the
generic host. Data-residency accounts provisioned on a dedicated host pin
it explicitly with GITHUB_COPILOT_API_URL (the override flows through to
upstream). See TESTING-copilot-subscription.md for details.
"""
copilot_bin = _require_binary(
"copilot",
@@ -7057,7 +7211,7 @@ def _prepare_codex_wrap_state(
) -> None:
"""Prepare the active Codex home for a wrap or prepare-only invocation."""
# Ensure the Codex home exists before anything tries to detect or write it.
# ``CodexRegistrar.detect()`` is just ``self._codex_dir.is_dir()``, and until
# ``CodexRegistrar.detect()`` is just ``self._config_dir.is_dir()``, and until
# now the directory was created as a *side effect* of injecting the rtk
# guidance into ``$CODEX_HOME/AGENTS.md``. With the CLI context tools removed
# nothing creates it, so on a machine where Codex is installed but has never
+1 -1
View File
@@ -118,7 +118,7 @@ class RelevanceScorerConfig:
DEFAULT: "hybrid" - combines exact matching (UUIDs, IDs) with semantic
understanding. Falls back to BM25 if sentence-transformers not installed.
For full hybrid support, install: pip install headroom[relevance]
For full hybrid support, install: pip install "headroom-ai[relevance]"
WHY HYBRID IS DEFAULT:
- Missing important items during compression is catastrophic
+67 -14
View File
@@ -346,6 +346,28 @@ def is_copilot_completions_host(url: str | None) -> bool:
return host.startswith("proxy.") and host.endswith(".githubcopilot.com")
def copilot_nes_base_url(model: Any, upstream_base_url: str) -> str | None:
"""Return the completions host for a next-edit request aimed at public CAPI.
Copilot Chat serves ghost text and next edits by posting ``copilot-nes-*``
models to ``{overrideProxyUrl}/chat/completions``. ``headroom wrap vscode``
points that override at the same proxy as CAPI, but only the completions
host serves these models; CAPI answers ``400 model_not_supported``.
Returns ``None`` (keep the upstream) for any other model, for an upstream
that already is a completions host, and for a GHE or custom deployment,
whose traffic must not leave it (see :func:`copilot_completions_base_url`).
"""
if not (isinstance(model, str) and model.startswith("copilot-nes-")):
return None
if not _is_public_copilot_api_host(_url_host(upstream_base_url)):
return None
if is_copilot_completions_host(upstream_base_url):
return None
return copilot_completions_base_url()
def copilot_completions_base_url() -> str:
"""Return the base URL serving Copilot's inline-completions endpoint.
@@ -1065,6 +1087,28 @@ def _api_url_from_payload(payload: dict[str, Any] | None) -> str | None:
return None
#: Opt-out: ``0``/``false``/``no``/``off`` folds the Business and Enterprise
#: hosts below back into the generic host, for seats where the segmented host
#: still lags on model availability (#2455 folded them after a Business seat
#: got "model not supported" for Claude models on its plan host).
_USE_ADVERTISED_HOST_ENV = "GITHUB_COPILOT_USE_ADVERTISED_HOST"
#: Per-plan chat hosts GitHub advertises in ``endpoints.api`` for Business and
#: Enterprise seats. Honoured by default: they are the hosts GitHub's own
#: clients route with, and an enterprise on GitHub's subscription-based network
#: routing allows only its own plan host, so the generic host is unreachable
#: there and the failure looks like a random connection error. The individual
#: host is still folded (#610: it did not serve newer models on the Responses
#: API). An explicit ``GITHUB_COPILOT_API_URL`` or enterprise domain wins over
#: both.
_ADVERTISED_PLAN_HOSTS: frozenset[str] = frozenset(
{
"api.business.githubcopilot.com",
"api.enterprise.githubcopilot.com",
}
)
def _subscription_api_url_from_user_info_payload(payload: dict[str, Any] | None) -> str:
configured = _configured_api_url_override()
if configured:
@@ -1075,12 +1119,21 @@ def _subscription_api_url_from_user_info_payload(payload: dict[str, Any] | None)
return DEFAULT_API_URL
host = urlparse(api_url).netloc.lower()
if host in {
"api.githubcopilot.com",
"api.individual.githubcopilot.com",
"api.business.githubcopilot.com",
"api.enterprise.githubcopilot.com",
}:
if host in _ADVERTISED_PLAN_HOSTS:
opt_out = os.environ.get(_USE_ADVERTISED_HOST_ENV, "").strip().lower()
if opt_out in {"0", "false", "no", "off"}:
return DEFAULT_API_URL
# Named in the log so a "model not supported" 400 from the plan host
# sits next to the escape hatch instead of looking like a proxy fault.
logger.info(
"Routing Copilot subscription traffic to the advertised plan host %s "
"(set %s=0 to use %s instead)",
api_url,
_USE_ADVERTISED_HOST_ENV,
DEFAULT_API_URL,
)
return api_url
if host in {"api.githubcopilot.com", "api.individual.githubcopilot.com"}:
return DEFAULT_API_URL
if host.endswith(".githubcopilot.com"):
return api_url
@@ -1406,14 +1459,14 @@ def resolve_copilot_api_url(oauth_token: str | None = None) -> str:
(corporate proxy, enterprise / data-residency host, tests).
2. The generic public host ``https://api.githubcopilot.com``.
The account-specific ``endpoints.api`` advertised by ``/copilot_internal/user``
is intentionally NOT used to route. It returns a segmented host (e.g.
``api.individual.githubcopilot.com``) that does not serve newer models on the
responses API — wrapping such a request regressed after 0.22.4 (#610) — and it
is not the host the official Copilot client routes with (that comes from the
token-exchange endpoint, not user info). Accounts that genuinely require a
dedicated host set ``GITHUB_COPILOT_API_URL`` explicitly. ``oauth_token`` is
accepted for call-site compatibility but no longer triggers a network lookup.
This path performs no network lookup, so it cannot see the per-plan host a
token exchange advertises. The subscription lanes (``wrap vscode``,
``wrap copilot --subscription``, OpenCode) resolve that host through
:func:`resolve_subscription_bearer_token_details` and pin it into the proxy
as ``GITHUB_COPILOT_API_URL``, which step 1 then honours. The
``api.individual.githubcopilot.com`` host is never routed to (#610: it did
not serve newer models on the Responses API). ``oauth_token`` is accepted
for call-site compatibility but no longer triggers a network lookup.
"""
del oauth_token # reserved; routing no longer depends on a user-info lookup
+1 -1
View File
@@ -152,7 +152,7 @@
</div>
<template x-if="stats.anon_telemetry_shipping">
<div class="inline-flex items-center gap-1.5 rounded-full border border-amber-500/40 bg-amber-500/10 px-2.5 py-1"
title="The anonymous telemetry beacon is on: compression stats only, never prompts, code, or file paths. Turn it off with HEADROOM_BEACON=off or DO_NOT_TRACK=1.">
title="The anonymous telemetry beacon is on: compression stats only, never prompts, code, or file paths. Turn it off with HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off or DO_NOT_TRACK=1.">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"
class="w-3 h-3 text-amber-400 shrink-0">
<path fill-rule="evenodd"
+3 -1
View File
@@ -106,7 +106,9 @@ class DeploymentManifest:
proxy_mode: str = "cache"
memory_enabled: bool = False
memory_db_path: str = ""
telemetry_enabled: bool = True
# None: the operator chose neither --telemetry nor --no-telemetry. The
# default stays True for manifests saved before the field existed.
telemetry_enabled: bool | None = True
image: str = "ghcr.io/headroomlabs-ai/headroom:latest"
service_name: str = "headroom"
container_name: str = "headroom-persistent"
+9 -5
View File
@@ -150,7 +150,7 @@ def build_manifest(
region: str | None,
proxy_mode: str,
memory_enabled: bool,
telemetry_enabled: bool,
telemetry_enabled: bool | None,
image: str,
no_rate_limit: bool = False,
no_http2: bool = False,
@@ -201,9 +201,12 @@ def build_manifest(
base_env["HEADROOM_ANYLLM_PROVIDER"] = anyllm_provider
if region:
base_env["HEADROOM_REGION"] = region
# Telemetry is opt-in (off by default). Write the value explicitly so the
# generated manifest is unambiguous and doesn't depend on the runtime default.
base_env["HEADROOM_TELEMETRY"] = "on" if telemetry_enabled else "off"
# Write the operator's explicit choice only. ``off`` also stops the upload
# beacon (telemetry/beacon.py), so writing it by default would turn the
# beacon off for every install nobody asked to opt out. Local stats stay
# off without it: they are opt-in.
if telemetry_enabled is not None:
base_env["HEADROOM_TELEMETRY"] = "on" if telemetry_enabled else "off"
if memory_enabled:
base_env["HEADROOM_MEMORY_ENABLED"] = "1"
# Grok / Grok Build need proxy upstream = xAI. Only auto-set when no other
@@ -262,7 +265,8 @@ def build_manifest(
"--backend",
backend,
]
proxy_args.append("--telemetry" if telemetry_enabled else "--no-telemetry")
if telemetry_enabled is not None:
proxy_args.append("--telemetry" if telemetry_enabled else "--no-telemetry")
# Agentic CLI targets (Claude Code, Codex) burst well above 60 req/min.
# Persist the flag so reinstalls don't silently reintroduce throttling.
# (see: https://github.com/headroomlabs-ai/headroom/issues/1350)
+35 -16
View File
@@ -108,6 +108,15 @@ def _migrate_deprecated_image(image: Any) -> Any:
return image
def _manifest_from_payload(payload: dict[str, Any]) -> DeploymentManifest:
"""Build a manifest from its decoded JSON, migrating the retired image repo."""
payload["mutations"] = [ManagedMutation(**item) for item in payload.get("mutations", [])]
payload["artifacts"] = [ArtifactRecord(**item) for item in payload.get("artifacts", [])]
if "image" in payload:
payload["image"] = _migrate_deprecated_image(payload["image"])
return DeploymentManifest(**payload)
def load_manifest(profile: str = "default") -> DeploymentManifest | None:
"""Load a deployment manifest when present."""
@@ -119,13 +128,15 @@ def load_manifest(profile: str = "default") -> DeploymentManifest | None:
# command and the auto-run `init hook ensure` route through here. Raise a
# typed error so callers can report cleanly or degrade gracefully.
try:
payload = json.loads(path.read_text(encoding="utf-8"))
payload["mutations"] = [ManagedMutation(**item) for item in payload.get("mutations", [])]
payload["artifacts"] = [ArtifactRecord(**item) for item in payload.get("artifacts", [])]
if "image" in payload:
payload["image"] = _migrate_deprecated_image(payload["image"])
return DeploymentManifest(**payload)
except (json.JSONDecodeError, ValueError, TypeError, OSError) as e:
text = path.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as e:
raise ManifestError(
f"deployment profile '{profile}' could not be read ({path}): {e}. "
"Check the file's permissions and that it is UTF-8."
) from e
try:
return _manifest_from_payload(json.loads(text))
except (ValueError, TypeError) as e:
raise ManifestError(f"deployment profile '{profile}' is corrupt ({path}): {e}") from e
@@ -139,16 +150,24 @@ def list_manifests() -> list[DeploymentManifest]:
manifests: list[DeploymentManifest] = []
for candidate in sorted(root.glob("*/manifest.json")):
try:
payload = json.loads(candidate.read_text(encoding="utf-8"))
payload["mutations"] = [
ManagedMutation(**item) for item in payload.get("mutations", [])
]
payload["artifacts"] = [ArtifactRecord(**item) for item in payload.get("artifacts", [])]
if "image" in payload:
payload["image"] = _migrate_deprecated_image(payload["image"])
manifests.append(DeploymentManifest(**payload))
except (OSError, ValueError, TypeError):
text = candidate.read_text(encoding="utf-8")
except (OSError, UnicodeDecodeError) as e:
logger.warning(
"Skipping unreadable deployment manifest %s: %s. Check the file's "
"permissions and that it is UTF-8.",
candidate,
e,
)
continue
try:
manifests.append(_manifest_from_payload(json.loads(text)))
except (ValueError, TypeError) as e:
logger.warning(
"Skipping corrupt deployment manifest %s: %s. Fix or delete the file to "
"restore that profile.",
candidate,
e,
)
return manifests
+2 -2
View File
@@ -2,7 +2,7 @@
Available integrations:
LangChain (pip install headroom[langchain]):
LangChain (pip install "headroom-ai[langchain]"):
- HeadroomChatModel: Drop-in wrapper for any LangChain chat model
- HeadroomChatMessageHistory: Automatic conversation compression
- HeadroomDocumentCompressor: Relevance-based document filtering
@@ -19,7 +19,7 @@ CrewAI (pip install headroom-ai crewai):
- HeadroomToolWrapper: Tool output compression for CrewAI agents
- wrap_tools_with_headroom: Batch wrapper for CrewAI tools
AutoGen (pip install headroom[autogen]):
AutoGen (pip install "headroom-ai[autogen]"):
- HeadroomToolWrapper: Tool output compression for AutoGen agents
- wrap_tools_with_headroom: Batch wrapper for AutoGen tools
+152
View File
@@ -0,0 +1,152 @@
"""Local or Headroom Cloud compression, shared by the ASGI and LiteLLM integrations.
``CompressionMiddleware`` (asgi.py) and ``HeadroomCallback`` (litellm_callback.py)
compress the same way: in-process with ``headroom.compress()`` by default, or
through the Headroom Cloud API when an API key is set.
This module must not import starlette or litellm, so either integration can be
used without the other's dependency.
"""
from __future__ import annotations
import json
import logging
import os
from typing import Any
from headroom.log_safety import redact_url
from headroom.offline import guard_egress
_DEFAULT_CLOUD_URL = "https://api.headroomlabs.ai"
_DEFAULT_MODEL = "claude-sonnet-4-5-20250929"
_KNOWN_MEDIA_TYPES = frozenset(
{
"application/json",
"application/problem+json",
"application/octet-stream",
"text/plain",
"text/html",
}
)
def _media_type(content_type: str) -> str:
"""Return just the ``type/subtype`` of a Content-Type header, or ``<other>``.
Parameters and anything that is not a plain media type are dropped, so an
error response cannot smuggle echoed content into the log through a header.
"""
# Valid type/subtype syntax can still contain echoed private content.
media = content_type.split(";", 1)[0].strip().lower()
return media if media in _KNOWN_MEDIA_TYPES else "<other>"
class CompressBackend:
"""Mixin that picks local or cloud compression and holds the cloud client.
Subclasses call ``_init_compress_backend`` from ``__init__`` and set
``_log`` to their module logger, so log lines keep that logger's name.
"""
_log: logging.Logger
def _init_compress_backend(
self,
model_limit: int,
hooks: Any,
api_key: str | None,
api_url: str | None,
) -> None:
self._model_limit = model_limit
self._hooks = hooks
# Cloud mode: if api_key is set, compress via Headroom Cloud API
# Falls back to HEADROOM_API_KEY env var
self._api_key = api_key or os.environ.get("HEADROOM_API_KEY", "").strip() or None
self._api_url = (
api_url or os.environ.get("HEADROOM_API_URL", "").strip() or _DEFAULT_CLOUD_URL
).rstrip("/")
self._client: Any = None # Lazy-initialized httpx.AsyncClient
@property
def cloud_mode(self) -> bool:
"""Whether cloud compression is enabled."""
return self._api_key is not None
def _local_compress(self, messages: list[dict], model: str) -> dict[str, Any] | None:
"""Compress locally using headroom.compress()."""
from headroom.compress import compress
result = compress(
messages=messages,
model=model or _DEFAULT_MODEL,
model_limit=self._model_limit,
hooks=self._hooks,
)
return {
"messages": result.messages,
"tokens_before": result.tokens_before,
"tokens_after": result.tokens_after,
"tokens_saved": result.tokens_saved,
"compression_ratio": result.compression_ratio,
}
async def _cloud_compress(self, messages: list[dict], model: str) -> dict[str, Any] | None:
"""Compress via Headroom Cloud API (managed CCR, TOIN, analytics).
This is the one path in these integrations that puts the caller's
prompt content on the wire to a Headroom-operated host, so it is
exactly what HEADROOM_OFFLINE exists to stop. "Opt-in by configuration"
was the old reason for leaving it open, and it is not good enough: an
operator who sets an air-gap switch is overriding earlier configuration
on purpose. The refusal is loud rather than a silent fall-through to
local compression, because silently compressing locally would hide the
fact that the deployment is no longer doing what it was configured to do.
"""
guard_egress("Headroom Cloud compression", self._api_url)
if self._client is None:
try:
import httpx
except ImportError as e:
raise ImportError(
"httpx is required for Headroom Cloud mode: pip install httpx"
) from e
self._client = httpx.AsyncClient(timeout=30.0)
client = self._client
assert client is not None
resp = await client.post(
f"{self._api_url}/v1/saas/compress",
headers={
"X-Headroom-Key": self._api_key,
"Content-Type": "application/json",
},
content=json.dumps(
{
"messages": messages,
"model": model or _DEFAULT_MODEL,
"model_limit": self._model_limit,
}
),
)
if resp.status_code != 200:
# The response body can echo request content: log metadata only, at
# every level.
self._log.warning(
"Headroom Cloud API error: HTTP %d from %s; request sent uncompressed",
resp.status_code,
redact_url(self._api_url),
)
self._log.debug(
"Headroom Cloud API error response: content-type=%s, %d bytes",
_media_type(resp.headers.get("content-type", "")),
len(resp.content),
)
return None
result: dict[str, Any] = resp.json()
return result
+10 -83
View File
@@ -28,18 +28,20 @@ from __future__ import annotations
import json
import logging
import os
from collections.abc import MutableMapping
from typing import Any
from starlette.types import ASGIApp, Receive, Scope, Send
from headroom.offline import guard_egress
# _DEFAULT_CLOUD_URL and guard_egress stay importable from this module.
from headroom.integrations._compress_backend import ( # noqa: F401
_DEFAULT_CLOUD_URL,
CompressBackend,
)
from headroom.offline import guard_egress # noqa: F401
logger = logging.getLogger(__name__)
_DEFAULT_CLOUD_URL = "https://api.headroomlabs.ai"
# Paths that contain LLM messages to compress
_LLM_PATHS = (
"/v1/messages", # Anthropic
@@ -49,7 +51,7 @@ _LLM_PATHS = (
)
class CompressionMiddleware:
class CompressionMiddleware(CompressBackend):
"""ASGI middleware that compresses LLM request messages.
Two modes:
@@ -64,6 +66,8 @@ class CompressionMiddleware:
- x-headroom-compressed: "true" if compression occurred
"""
_log = logger
def __init__(
self,
app: ASGIApp,
@@ -75,20 +79,7 @@ class CompressionMiddleware:
) -> None:
self.app = app
self._min_tokens = min_tokens
self._model_limit = model_limit
self._hooks = hooks
# Cloud mode: if api_key is set, compress via Headroom Cloud API
self._api_key = api_key or os.environ.get("HEADROOM_API_KEY", "").strip() or None
self._api_url = (
api_url or os.environ.get("HEADROOM_API_URL", "").strip() or _DEFAULT_CLOUD_URL
).rstrip("/")
self._client: Any = None # Lazy-initialized httpx.AsyncClient
@property
def cloud_mode(self) -> bool:
"""Whether cloud compression is enabled."""
return self._api_key is not None
self._init_compress_backend(model_limit, hooks, api_key, api_url)
async def aclose(self) -> None:
"""Close the underlying httpx.AsyncClient, if one was created."""
@@ -186,67 +177,3 @@ class CompressionMiddleware:
await send(message)
await self.app(scope, modified_receive, metrics_send)
def _local_compress(self, messages: list[dict], model: str) -> dict[str, Any] | None:
"""Compress locally using headroom.compress()."""
from headroom.compress import compress
result = compress(
messages=messages,
model=model or "claude-sonnet-4-5-20250929",
model_limit=self._model_limit,
hooks=self._hooks,
)
return {
"messages": result.messages,
"tokens_before": result.tokens_before,
"tokens_after": result.tokens_after,
"tokens_saved": result.tokens_saved,
"compression_ratio": result.compression_ratio,
}
async def _cloud_compress(self, messages: list[dict], model: str) -> dict[str, Any] | None:
"""Compress via Headroom Cloud API (managed CCR, TOIN, analytics).
This is the one path in this file that puts the caller's prompt
content on the wire to a Headroom-operated host, so it is exactly what
HEADROOM_OFFLINE exists to stop. "Opt-in by configuration" was the old
reason for leaving it open, and it is not good enough: an operator who
sets an air-gap switch is overriding earlier configuration on purpose.
The refusal is loud rather than a silent fall-through to local
compression, because silently compressing locally would hide the fact
that the deployment is no longer doing what it was configured to do.
"""
guard_egress("Headroom Cloud compression", self._api_url)
if self._client is None:
try:
import httpx
except ImportError as e:
raise ImportError(
"httpx is required for Headroom Cloud mode: pip install httpx"
) from e
self._client = httpx.AsyncClient(timeout=30.0)
client = self._client
assert client is not None
resp = await client.post(
f"{self._api_url}/v1/saas/compress",
headers={
"X-Headroom-Key": self._api_key,
"Content-Type": "application/json",
},
content=json.dumps(
{
"messages": messages,
"model": model or "claude-sonnet-4-5-20250929",
"model_limit": self._model_limit,
}
),
)
if resp.status_code != 200:
logger.warning("Headroom Cloud API error: %d %s", resp.status_code, resp.text[:200])
return None
result: dict[str, Any] = resp.json()
return result
+1 -1
View File
@@ -20,7 +20,7 @@ Example:
# Use like normal - optimization happens automatically
response = llm.invoke("Hello!")
Install: pip install headroom[langchain]
Install: pip install "headroom-ai[langchain]"
"""
# Agent tool wrapping
+1 -1
View File
@@ -53,7 +53,7 @@ def _check_langchain_available() -> None:
if not LANGCHAIN_AVAILABLE:
raise ImportError(
"LangChain is required for this integration. "
"Install with: pip install headroom[langchain] "
'Install with: pip install "headroom-ai[langchain]" '
"or: pip install langchain-core"
)
@@ -76,7 +76,7 @@ def _check_langchain_available() -> None:
if not LANGCHAIN_AVAILABLE:
raise ImportError(
"LangChain is required for this integration. "
"Install with: pip install headroom[langchain] "
'Install with: pip install "headroom-ai[langchain]" '
"or: pip install langchain-core langchain-openai"
)
+1 -1
View File
@@ -60,7 +60,7 @@ def _check_langchain_available() -> None:
if not LANGCHAIN_AVAILABLE:
raise ImportError(
"LangChain is required for this integration. "
"Install with: pip install headroom[langchain] "
'Install with: pip install "headroom-ai[langchain]" '
"or: pip install langchain-core"
)
+1 -1
View File
@@ -72,7 +72,7 @@ def _check_langchain_available() -> None:
if not LANGCHAIN_AVAILABLE:
raise ImportError(
"LangChain is required for this integration. "
"Install with: pip install headroom[langchain] "
'Install with: pip install "headroom-ai[langchain]" '
"or: pip install langchain-core"
)
+1 -1
View File
@@ -53,7 +53,7 @@ def _check_langchain_available() -> None:
if not LANGCHAIN_AVAILABLE:
raise ImportError(
"LangChain is required for this integration. "
"Install with: pip install headroom[langchain] "
'Install with: pip install "headroom-ai[langchain]" '
"or: pip install langchain-core"
)
+1 -1
View File
@@ -93,7 +93,7 @@ def _check_langchain_available() -> None:
if not LANGCHAIN_AVAILABLE:
raise ImportError(
"LangChain is required for this integration. "
"Install with: pip install headroom[langchain] "
'Install with: pip install "headroom-ai[langchain]" '
"or: pip install langchain-core"
)
+1 -1
View File
@@ -45,7 +45,7 @@ def _check_langchain_available() -> None:
if not LANGCHAIN_AVAILABLE:
raise ImportError(
"LangChain is required for this integration. "
"Install with: pip install headroom[langchain] "
'Install with: pip install "headroom-ai[langchain]" '
"or: pip install langchain-core"
)
+10 -86
View File
@@ -16,16 +16,18 @@ Cloud mode requires httpx: pip install httpx
from __future__ import annotations
import json
import logging
from typing import Any
from headroom.offline import guard_egress
# _DEFAULT_CLOUD_URL and guard_egress stay importable from this module.
from headroom.integrations._compress_backend import ( # noqa: F401
_DEFAULT_CLOUD_URL,
CompressBackend,
)
from headroom.offline import guard_egress # noqa: F401
logger = logging.getLogger(__name__)
_DEFAULT_CLOUD_URL = "https://api.headroomlabs.ai"
try:
from litellm.integrations.custom_logger import CustomLogger as _CustomLogger
@@ -33,7 +35,7 @@ except ImportError: # litellm not installed — fall back to plain object
_CustomLogger = object # type: ignore[assignment,misc]
class HeadroomCallback(_CustomLogger):
class HeadroomCallback(CompressBackend, _CustomLogger):
"""LiteLLM callback that compresses messages before each API call.
Implements the LiteLLM callback hooks looked up by name:
@@ -63,6 +65,8 @@ class HeadroomCallback(_CustomLogger):
HEADROOM_API_KEY: "hdr_xxx"
"""
_log = logger
def __init__(
self,
min_tokens: int = 500,
@@ -73,30 +77,14 @@ class HeadroomCallback(_CustomLogger):
) -> None:
super().__init__()
self._min_tokens = min_tokens
self._model_limit = model_limit
self._hooks = hooks
self._total_saved = 0
# Cloud mode: if api_key is set, compress via Headroom Cloud API
# Falls back to HEADROOM_API_KEY env var
import os
self._api_key = api_key or os.environ.get("HEADROOM_API_KEY", "").strip() or None
self._api_url = (
api_url or os.environ.get("HEADROOM_API_URL", "").strip() or _DEFAULT_CLOUD_URL
).rstrip("/")
self._client: Any = None # Lazy-initialized httpx.AsyncClient
self._init_compress_backend(model_limit, hooks, api_key, api_url)
@property
def total_tokens_saved(self) -> int:
"""Total tokens saved across all calls."""
return self._total_saved
@property
def cloud_mode(self) -> bool:
"""Whether cloud compression is enabled."""
return self._api_key is not None
async def aclose(self) -> None:
"""Close the shared cloud HTTP client, if it was initialized.
@@ -167,70 +155,6 @@ class HeadroomCallback(_CustomLogger):
return data
def _local_compress(self, messages: list[dict], model: str) -> dict[str, Any] | None:
"""Compress locally using headroom.compress()."""
from headroom.compress import compress
result = compress(
messages=messages,
model=model or "claude-sonnet-4-5-20250929",
model_limit=self._model_limit,
hooks=self._hooks,
)
return {
"messages": result.messages,
"tokens_before": result.tokens_before,
"tokens_after": result.tokens_after,
"tokens_saved": result.tokens_saved,
"compression_ratio": result.compression_ratio,
}
async def _cloud_compress(self, messages: list[dict], model: str) -> dict[str, Any] | None:
"""Compress via Headroom Cloud API (managed CCR, TOIN, analytics).
This is the one path in this file that puts the caller's prompt
content on the wire to a Headroom-operated host, so it is exactly what
HEADROOM_OFFLINE exists to stop. "Opt-in by configuration" was the old
reason for leaving it open, and it is not good enough: an operator who
sets an air-gap switch is overriding earlier configuration on purpose.
The refusal is loud rather than a silent fall-through to local
compression, because silently compressing locally would hide the fact
that the deployment is no longer doing what it was configured to do.
"""
guard_egress("Headroom Cloud compression", self._api_url)
if self._client is None:
try:
import httpx
except ImportError as e:
raise ImportError(
"httpx is required for Headroom Cloud mode: pip install httpx"
) from e
self._client = httpx.AsyncClient(timeout=30.0)
client = self._client
assert client is not None
resp = await client.post(
f"{self._api_url}/v1/saas/compress",
headers={
"X-Headroom-Key": self._api_key,
"Content-Type": "application/json",
},
content=json.dumps(
{
"messages": messages,
"model": model or "claude-sonnet-4-5-20250929",
"model_limit": self._model_limit,
}
),
)
if resp.status_code != 200:
logger.warning("Headroom Cloud API error: %d %s", resp.status_code, resp.text[:200])
return None
result: dict[str, Any] = resp.json()
return result
async def async_post_call_success_hook(
self,
data: dict[str, Any],
+18 -4
View File
@@ -12,6 +12,7 @@ import importlib
import logging
import pkgutil
from ..log_safety import describe_exception, safe_id
from .base import LearnPlugin
logger = logging.getLogger(__name__)
@@ -34,8 +35,13 @@ def _discover() -> dict[str, LearnPlugin]:
if isinstance(p, LearnPlugin):
plugins[p.name] = p
logger.debug("Loaded built-in learn plugin: %s", p.name)
except Exception:
logger.debug("Failed to load built-in plugin: %s", mod_name, exc_info=True)
except Exception as e:
# Exception text can quote paths or credentials: type only at WARNING.
logger.warning("Failed to load built-in learn plugin %s (%s)", mod_name, safe_id(e))
if logger.isEnabledFor(logging.DEBUG):
logger.debug(
"Built-in learn plugin %s failure: %s", mod_name, describe_exception(e)
)
# 2. External: entry_points(group="headroom.learn_plugin")
try:
@@ -56,8 +62,16 @@ def _discover() -> dict[str, LearnPlugin]:
if isinstance(p, LearnPlugin):
plugins[p.name] = p # External overrides built-in on name collision
logger.debug("Loaded external learn plugin: %s (%s)", p.name, ep.name)
except Exception:
logger.warning("Failed to load external learn plugin: %s", ep.name, exc_info=True)
except Exception as e:
logger.warning(
"Failed to load external learn plugin %s (%s)", safe_id(ep.name), safe_id(e)
)
if logger.isEnabledFor(logging.DEBUG):
logger.debug(
"External learn plugin %s failure: %s",
safe_id(ep.name),
describe_exception(e),
)
except Exception:
logger.debug("Entry point discovery failed", exc_info=True)
+10
View File
@@ -61,6 +61,7 @@ _SUPPRESS_CONTEXT = vars(BaseException)["__suppress_context__"]
_TRACEBACK = vars(BaseException)["__traceback__"]
_ERRNO = vars(OSError)["errno"]
_QUALNAME = vars(type)["__qualname__"]
_CLASS_MODULE = vars(type)["__module__"]
# Ints above this many bits have more than 4300 digits, which repr refuses.
_MAX_ID_INT_BITS = 14_000
# The module __dict__ descriptor itself, so a ModuleType subclass cannot override it.
@@ -302,6 +303,15 @@ def _int_repr(value: int) -> str:
return int.__repr__(value)
def describe_class(cls: type) -> str:
"""Name a class without emitting arbitrary plugin-defined metadata."""
name = _class_name(cls)
module = _CLASS_MODULE.__get__(cls)
if name is None or type(module) is not str or not _QUALIFIED_NAME.fullmatch(module):
return "<class>"
return f"{module}.{name}"
def _class_name(cls: type) -> str | None:
"""The class's qualified name when it is plain identifiers, else None.
+10 -45
View File
@@ -36,7 +36,16 @@ from typing import Any
from headroom import fsutil
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
from .base import (
MCPRegistrar,
RegisterResult,
RegisterStatus,
ServerSpec,
_diff_specs,
_entry_to_spec,
_spec_to_entry,
_specs_equivalent,
)
logger = logging.getLogger(__name__)
@@ -202,47 +211,3 @@ class AntigravityRegistrar(MCPRegistrar):
except (json.JSONDecodeError, OSError, UnicodeDecodeError):
return None
return data if isinstance(data, dict) else None
def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:
args_value = entry.get("args", [])
args = tuple(str(x) for x in args_value) if isinstance(args_value, list) else ()
env_value = entry.get("env", {})
env = {str(k): str(v) for k, v in env_value.items()} if isinstance(env_value, dict) else {}
return ServerSpec(
name=name,
command=str(entry.get("command", "")),
args=args,
env=env,
)
def _spec_to_entry(spec: ServerSpec) -> dict[str, Any]:
entry: dict[str, Any] = {"command": spec.command}
if spec.args:
entry["args"] = list(spec.args)
if spec.env:
entry["env"] = dict(spec.env)
return entry
def _specs_equivalent(a: ServerSpec, b: ServerSpec) -> bool:
return (
a.name == b.name
and a.command == b.command
and tuple(a.args) == tuple(b.args)
and dict(a.env) == dict(b.env)
)
def _diff_specs(existing: ServerSpec, requested: ServerSpec) -> str:
parts: list[str] = []
if existing.command != requested.command:
parts.append(f"command {existing.command!r} -> {requested.command!r}")
if tuple(existing.args) != tuple(requested.args):
parts.append(f"args {list(existing.args)} -> {list(requested.args)}")
if dict(existing.env) != dict(requested.env):
parts.append(f"env {dict(existing.env)} -> {dict(requested.env)}")
if not parts:
return "spec differs in unidentified field(s)"
return "; ".join(parts)
+59
View File
@@ -16,6 +16,7 @@ from __future__ import annotations
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from enum import Enum
from typing import Any
class RegisterStatus(str, Enum):
@@ -104,3 +105,61 @@ class MCPRegistrar(ABC):
@abstractmethod
def unregister_server(self, server_name: str) -> bool:
"""Remove the named server. Returns True on success."""
# ----------------------------------------------------------------------
# Spec helpers shared by the registrars whose entries use the common
# ``{"command", "args", "env"}`` shape (Claude, Antigravity, Codex, Grok).
# OpenCode has its own entry format and keeps its own converters.
# ----------------------------------------------------------------------
def _spec_to_entry(spec: ServerSpec) -> dict[str, Any]:
entry: dict[str, Any] = {"command": spec.command}
if spec.args:
entry["args"] = list(spec.args)
if spec.env:
entry["env"] = dict(spec.env)
return entry
def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:
args_value = entry.get("args", [])
if isinstance(args_value, list):
args = tuple(str(x) for x in args_value)
else:
args = ()
env_value = entry.get("env", {})
env: dict[str, str] = {}
if isinstance(env_value, dict):
env = {str(k): str(v) for k, v in env_value.items()}
return ServerSpec(
name=name,
command=str(entry.get("command", "")),
args=args,
env=env,
)
def _specs_equivalent(a: ServerSpec, b: ServerSpec) -> bool:
"""Two specs match when every field is equal."""
return (
a.name == b.name
and a.command == b.command
and tuple(a.args) == tuple(b.args)
and dict(a.env) == dict(b.env)
)
def _diff_specs(existing: ServerSpec, requested: ServerSpec) -> str:
"""Render the difference between two specs for human consumption."""
parts: list[str] = []
if existing.command != requested.command:
parts.append(f"command {existing.command!r} -> {requested.command!r}")
if tuple(existing.args) != tuple(requested.args):
parts.append(f"args {list(existing.args)} -> {list(requested.args)}")
if dict(existing.env) != dict(requested.env):
parts.append(f"env {dict(existing.env)} -> {dict(requested.env)}")
if not parts:
return "spec differs in unidentified field(s)"
return "; ".join(parts)
+10 -52
View File
@@ -37,7 +37,16 @@ from typing import Any
from headroom import fsutil
from headroom._subprocess import run
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
from .base import (
MCPRegistrar,
RegisterResult,
RegisterStatus,
ServerSpec,
_diff_specs,
_entry_to_spec,
_spec_to_entry,
_specs_equivalent,
)
logger = logging.getLogger(__name__)
@@ -579,54 +588,3 @@ def _read_json_for_write(path: Path) -> dict[str, Any]:
def _write_json(path: Path, data: dict[str, Any]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
fsutil.write_text(path, json.dumps(data, indent=2) + "\n")
def _spec_to_entry(spec: ServerSpec) -> dict[str, Any]:
entry: dict[str, Any] = {"command": spec.command}
if spec.args:
entry["args"] = list(spec.args)
if spec.env:
entry["env"] = dict(spec.env)
return entry
def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:
args_value = entry.get("args", [])
if isinstance(args_value, list):
args = tuple(str(x) for x in args_value)
else:
args = ()
env_value = entry.get("env", {})
env: dict[str, str] = {}
if isinstance(env_value, dict):
env = {str(k): str(v) for k, v in env_value.items()}
return ServerSpec(
name=name,
command=str(entry.get("command", "")),
args=args,
env=env,
)
def _specs_equivalent(a: ServerSpec, b: ServerSpec) -> bool:
"""Two specs match when every field is equal."""
return (
a.name == b.name
and a.command == b.command
and tuple(a.args) == tuple(b.args)
and dict(a.env) == dict(b.env)
)
def _diff_specs(existing: ServerSpec, requested: ServerSpec) -> str:
"""Render the difference between two specs for human consumption."""
parts: list[str] = []
if existing.command != requested.command:
parts.append(f"command {existing.command!r} -> {requested.command!r}")
if tuple(existing.args) != tuple(requested.args):
parts.append(f"args {list(existing.args)} -> {list(requested.args)}")
if dict(existing.env) != dict(requested.env):
parts.append(f"env {dict(existing.env)} -> {dict(requested.env)}")
if not parts:
return "spec differs in unidentified field(s)"
return "; ".join(parts)
+38 -57
View File
@@ -6,7 +6,8 @@ Codex stores MCP server config in ``$CODEX_HOME/config.toml`` when
sub-tables). There is no general-purpose CLI for adding entries, so we
edit the file in place — using marker-delimited blocks so we can
idempotently inject, replace, and remove our entry without disturbing
anything else the user has configured.
anything else the user has configured. The Grok registrar reuses the
same marker-block logic.
"""
from __future__ import annotations
@@ -18,7 +19,15 @@ from typing import Any
from headroom import fsutil
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
from .base import (
MCPRegistrar,
RegisterResult,
RegisterStatus,
ServerSpec,
_diff_specs,
_entry_to_spec,
_specs_equivalent,
)
if sys.version_info >= (3, 11):
import tomllib
@@ -118,27 +127,23 @@ def _only_server_changed(old: str, new: str, server_name: str) -> bool:
return _without_server(before, server_name) == _without_server(after, server_name)
class CodexRegistrar(MCPRegistrar):
"""Register MCP servers with the OpenAI Codex CLI."""
class _TomlMarkerRegistrar(MCPRegistrar):
"""Marker-block registrar for ``<config_dir>/config.toml``.
name = "codex"
display_name = "OpenAI Codex CLI"
Codex and Grok both keep ``[mcp_servers.<name>]`` tables in a
``config.toml`` and differ only in where the config directory lives.
"""
def __init__(self, *, home_dir: Path | None = None) -> None:
if home_dir is not None:
self._codex_dir = home_dir / ".codex"
else:
from headroom.install.paths import codex_home_dir
self._codex_dir = codex_home_dir()
self._config_file = self._codex_dir / "config.toml"
def __init__(self, config_dir: Path) -> None:
self._config_dir = config_dir
self._config_file = config_dir / "config.toml"
# ------------------------------------------------------------------
# MCPRegistrar interface
# ------------------------------------------------------------------
def detect(self) -> bool:
return self._codex_dir.is_dir()
return self._config_dir.is_dir()
def get_server(self, server_name: str) -> ServerSpec | None:
data = self._load_toml()
@@ -189,7 +194,7 @@ class CodexRegistrar(MCPRegistrar):
# _write_block appends a `[mcp_servers.<name>]` table, so appending into
# an unparseable file corrupts it further, and appending alongside a
# non-table entry creates a duplicate `[mcp_servers.<name>]` key that
# tomllib/codex then reject — destroying a previously-valid user config.
# tomllib and the CLI then reject — destroying a previously-valid user config.
# Refuse rather than clobber, mirroring the claude (#1660) / opencode
# (#1661) guards.
if existing is None:
@@ -291,7 +296,7 @@ class CodexRegistrar(MCPRegistrar):
def _write_block(self, spec: ServerSpec) -> RegisterResult:
block = _render_block(spec)
try:
self._codex_dir.mkdir(parents=True, exist_ok=True)
self._config_dir.mkdir(parents=True, exist_ok=True)
marker_start = _marker_start(spec.name)
marker_end = _marker_end(spec.name)
original = self._read_text()
@@ -324,6 +329,22 @@ class CodexRegistrar(MCPRegistrar):
return RegisterResult(RegisterStatus.REGISTERED, f"wrote to {self._config_file}")
class CodexRegistrar(_TomlMarkerRegistrar):
"""Register MCP servers with the OpenAI Codex CLI."""
name = "codex"
display_name = "OpenAI Codex CLI"
def __init__(self, *, home_dir: Path | None = None) -> None:
if home_dir is not None:
config_dir = home_dir / ".codex"
else:
from headroom.install.paths import codex_home_dir
config_dir = codex_home_dir()
super().__init__(config_dir)
# ----------------------------------------------------------------------
# TOML rendering / parsing helpers (kept module-private)
# ----------------------------------------------------------------------
@@ -379,43 +400,3 @@ def _toml_str(s: str) -> str:
else:
out.append(ch)
return '"' + "".join(out) + '"'
def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:
args_value = entry.get("args", [])
if isinstance(args_value, list):
args = tuple(str(x) for x in args_value)
else:
args = ()
env_value = entry.get("env", {})
env: dict[str, str] = {}
if isinstance(env_value, dict):
env = {str(k): str(v) for k, v in env_value.items()}
return ServerSpec(
name=name,
command=str(entry.get("command", "")),
args=args,
env=env,
)
def _specs_equivalent(a: ServerSpec, b: ServerSpec) -> bool:
return (
a.name == b.name
and a.command == b.command
and tuple(a.args) == tuple(b.args)
and dict(a.env) == dict(b.env)
)
def _diff_specs(existing: ServerSpec, requested: ServerSpec) -> str:
parts: list[str] = []
if existing.command != requested.command:
parts.append(f"command {existing.command!r} -> {requested.command!r}")
if tuple(existing.args) != tuple(requested.args):
parts.append(f"args {list(existing.args)} -> {list(requested.args)}")
if dict(existing.env) != dict(requested.env):
parts.append(f"env {dict(existing.env)} -> {dict(requested.env)}")
if not parts:
return "spec differs in unidentified field(s)"
return "; ".join(parts)
+9 -218
View File
@@ -4,46 +4,20 @@ Grok stores MCP server config in ``$GROK_HOME/config.toml`` (default
``~/.grok/config.toml``) as ``[mcp_servers.<name>]`` tables. There is no
general-purpose CLI for adding entries, so we edit the file in place using
marker-delimited blocks so we can idempotently inject, replace, and remove
our entry without disturbing anything else the user has configured.
our entry without disturbing anything else the user has configured. The
file format matches Codex's, so the marker-block logic lives in
:mod:`headroom.mcp_registry.codex`.
"""
from __future__ import annotations
import logging
import os
import sys
from pathlib import Path
from typing import Any
from headroom import fsutil
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
from .codex import _evict_foreign_tables, _only_server_changed, _toml_str
if sys.version_info >= (3, 11):
import tomllib
else: # pragma: no cover — exercised only on 3.10
import tomli as tomllib # type: ignore[no-redef]
logger = logging.getLogger(__name__)
_MARKER_START = "# --- Headroom MCP server ---"
_MARKER_END = "# --- end Headroom MCP server ---"
from .codex import _TomlMarkerRegistrar
def _marker_start(server_name: str) -> str:
if server_name == "headroom":
return _MARKER_START
return f"# --- Headroom MCP server: {server_name} ---"
def _marker_end(server_name: str) -> str:
if server_name == "headroom":
return _MARKER_END
return f"# --- end Headroom MCP server: {server_name} ---"
class GrokRegistrar(MCPRegistrar):
class GrokRegistrar(_TomlMarkerRegistrar):
"""Register MCP servers with the Grok CLI."""
name = "grok"
@@ -51,192 +25,9 @@ class GrokRegistrar(MCPRegistrar):
def __init__(self, *, home_dir: Path | None = None) -> None:
if home_dir is not None:
self._grok_dir = home_dir / ".grok"
config_dir = home_dir / ".grok"
elif os.environ.get("GROK_HOME"):
self._grok_dir = Path(os.environ["GROK_HOME"]).expanduser()
config_dir = Path(os.environ["GROK_HOME"]).expanduser()
else:
self._grok_dir = Path.home() / ".grok"
self._config_file = self._grok_dir / "config.toml"
def detect(self) -> bool:
return self._grok_dir.is_dir()
def get_server(self, server_name: str) -> ServerSpec | None:
data = self._load_toml()
servers = data.get("mcp_servers", {})
if not isinstance(servers, dict):
return None
entry = servers.get(server_name)
if not isinstance(entry, dict):
return None
return _entry_to_spec(server_name, entry)
def register_server(self, spec: ServerSpec, *, force: bool = False) -> RegisterResult:
existing = self.get_server(spec.name)
if existing is not None and _specs_equivalent(existing, spec):
return RegisterResult(RegisterStatus.ALREADY, "matches current configuration")
if existing is not None and not force:
content = self._read_text()
if _marker_start(spec.name) not in content:
return RegisterResult(
RegisterStatus.MISMATCH,
"user-managed [mcp_servers."
f"{spec.name}] entry outside Headroom markers; "
f"{_diff_specs(existing, spec)}",
)
return RegisterResult(RegisterStatus.MISMATCH, _diff_specs(existing, spec))
if existing is not None and force:
content = self._read_text()
if _marker_start(spec.name) not in content:
return RegisterResult(
RegisterStatus.MISMATCH,
"user-managed [mcp_servers."
f"{spec.name}] entry outside Headroom markers; "
f"{_diff_specs(existing, spec)}",
)
self.unregister_server(spec.name)
return self._write_block(spec)
def unregister_server(self, server_name: str) -> bool:
if not self._config_file.exists():
return False
marker_start = _marker_start(server_name)
marker_end = _marker_end(server_name)
original = self._read_text()
content = _evict_foreign_tables(original, server_name, marker_start, marker_end)
if marker_start not in content or marker_end not in content:
return False
try:
start = content.index(marker_start)
end = content.index(marker_end) + len(marker_end)
except ValueError:
return False
before = content[:start].rstrip("\n")
after = content[end:].lstrip("\n")
if before and after:
new_content = before + "\n\n" + after
else:
new_content = (before or after).rstrip("\n") + ("\n" if (before or after) else "")
if not _only_server_changed(original, new_content, server_name):
logger.warning(
"Not removing the Headroom block for %s from %s: the file does not parse, "
"or the block holds entries Headroom could not move out safely.",
server_name,
self._config_file,
)
return False
try:
fsutil.write_text(self._config_file, new_content)
except OSError as exc:
logger.warning("could not remove %r from %s: %s", server_name, self._config_file, exc)
return False
return True
def _load_toml(self) -> dict[str, Any]:
if not self._config_file.exists():
return {}
try:
data = tomllib.loads(fsutil.read_text(self._config_file))
except (tomllib.TOMLDecodeError, OSError):
return {}
return data if isinstance(data, dict) else {}
def _read_text(self) -> str:
return fsutil.read_text(self._config_file, default="")
def _write_block(self, spec: ServerSpec) -> RegisterResult:
block = _render_block(spec)
try:
self._grok_dir.mkdir(parents=True, exist_ok=True)
marker_start = _marker_start(spec.name)
marker_end = _marker_end(spec.name)
original = self._read_text()
content = _evict_foreign_tables(original, spec.name, marker_start, marker_end)
if marker_start in content and marker_end in content:
start = content.index(marker_start)
end = content.index(marker_end) + len(marker_end)
content = (
content[:start].rstrip("\n")
+ ("\n\n" if content[:start].rstrip("\n") else "")
+ block
+ "\n"
+ content[end:].lstrip("\n")
)
elif content.strip():
content = content.rstrip("\n") + "\n\n" + block + "\n"
else:
content = block + "\n"
if not _only_server_changed(original, content, spec.name):
return RegisterResult(
RegisterStatus.FAILED,
f"{self._config_file} does not parse, or the Headroom block holds "
"entries Headroom could not move out safely; refusing to rewrite it.",
)
fsutil.write_text(self._config_file, content)
except OSError as exc:
return RegisterResult(
RegisterStatus.FAILED, f"could not write {self._config_file}: {exc}"
)
return RegisterResult(RegisterStatus.REGISTERED, f"wrote to {self._config_file}")
def _render_block(spec: ServerSpec) -> str:
lines: list[str] = [
_marker_start(spec.name),
f"[mcp_servers.{spec.name}]",
f"command = {_toml_str(spec.command)}",
]
if spec.args:
items = ", ".join(_toml_str(a) for a in spec.args)
lines.append(f"args = [{items}]")
if spec.env:
lines.append("")
lines.append(f"[mcp_servers.{spec.name}.env]")
for k, v in spec.env.items():
lines.append(f"{k} = {_toml_str(v)}")
lines.append(_marker_end(spec.name))
return "\n".join(lines)
def _entry_to_spec(name: str, entry: dict[str, Any]) -> ServerSpec:
args_value = entry.get("args", [])
if isinstance(args_value, list):
args = tuple(str(x) for x in args_value)
else:
args = ()
env_value = entry.get("env", {})
env: dict[str, str] = {}
if isinstance(env_value, dict):
env = {str(k): str(v) for k, v in env_value.items()}
return ServerSpec(
name=name,
command=str(entry.get("command", "")),
args=args,
env=env,
)
def _specs_equivalent(a: ServerSpec, b: ServerSpec) -> bool:
return (
a.name == b.name
and a.command == b.command
and tuple(a.args) == tuple(b.args)
and dict(a.env) == dict(b.env)
)
def _diff_specs(existing: ServerSpec, requested: ServerSpec) -> str:
parts: list[str] = []
if existing.command != requested.command:
parts.append(f"command {existing.command!r} -> {requested.command!r}")
if tuple(existing.args) != tuple(requested.args):
parts.append(f"args {list(existing.args)} -> {list(requested.args)}")
if dict(existing.env) != dict(requested.env):
parts.append(f"env {dict(existing.env)} -> {dict(requested.env)}")
if not parts:
return "spec differs in unidentified field(s)"
return "; ".join(parts)
config_dir = Path.home() / ".grok"
super().__init__(config_dir)
+8 -23
View File
@@ -17,7 +17,14 @@ from typing import Any
from headroom import fsutil
from headroom.install.paths import opencode_config_path
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
from .base import (
MCPRegistrar,
RegisterResult,
RegisterStatus,
ServerSpec,
_diff_specs,
_specs_equivalent,
)
logger = logging.getLogger(__name__)
@@ -128,28 +135,6 @@ def _spec_to_entry(spec: ServerSpec) -> dict[str, Any]:
return entry
def _specs_equivalent(a: ServerSpec, b: ServerSpec) -> bool:
return (
a.name == b.name
and a.command == b.command
and tuple(a.args) == tuple(b.args)
and dict(a.env) == dict(b.env)
)
def _diff_specs(existing: ServerSpec, requested: ServerSpec) -> str:
parts: list[str] = []
if existing.command != requested.command:
parts.append(f"command {existing.command!r} -> {requested.command!r}")
if tuple(existing.args) != tuple(requested.args):
parts.append(f"args {list(existing.args)} -> {list(requested.args)}")
if dict(existing.env) != dict(requested.env):
parts.append(f"env {dict(existing.env)} -> {dict(requested.env)}")
if not parts:
return "spec differs in unidentified field(s)"
return "; ".join(parts)
class OpencodeRegistrar(MCPRegistrar):
"""Register MCP servers with OpenCode."""
+32 -2
View File
@@ -57,6 +57,7 @@ from dataclasses import dataclass, field
from datetime import datetime, timezone
from typing import Any
from headroom.log_safety import describe_exception, safe_id
from headroom.memory import qdrant_env
from headroom.memory.models import Memory
from headroom.memory.ports import MemorySearchResult
@@ -921,7 +922,29 @@ class DirectMem0Adapter:
try:
await asyncio.to_thread(self._mem0_client.delete, memory_id=memory_id)
return True
except Exception:
except Exception as e:
# mem0 (Memory.delete, mem0ai 2.x) raises exactly
# ValueError(f"Memory with id {memory_id} not found") for an unknown id.
# The delete is model-driven, so a stale or invented id is expected. Any
# other ValueError (e.g. a missing collection) is a real failure.
if isinstance(e, ValueError) and str(e).startswith(
f"Memory with id {memory_id} not found"
):
logger.debug("DirectMem0: delete_memory(%s): memory not found", safe_id(memory_id))
return False
# Backend exception text can carry stored memory or connection details,
# so no level logs its message; DEBUG gets describe_exception.
logger.warning(
"DirectMem0: delete_memory(%s) failed (%s)",
safe_id(memory_id),
safe_id(e),
)
if logger.isEnabledFor(logging.DEBUG):
logger.debug(
"DirectMem0: delete_memory(%s) failure: %s",
safe_id(memory_id),
describe_exception(e),
)
return False
async def get_memory(self, memory_id: str) -> Memory | None:
@@ -949,7 +972,14 @@ class DirectMem0Adapter:
valid_from=_utcnow(),
metadata=result.get("metadata") or {},
)
except Exception:
except Exception as e:
logger.warning("DirectMem0: get_memory(%s) failed (%s)", safe_id(memory_id), safe_id(e))
if logger.isEnabledFor(logging.DEBUG):
logger.debug(
"DirectMem0: get_memory(%s) failure: %s",
safe_id(memory_id),
describe_exception(e),
)
return None
@property
+12 -9
View File
@@ -1374,7 +1374,8 @@ class TrafficLearner:
uri = f"file:{db_path}?mode=ro"
try:
conn = sqlite3.connect(uri, uri=True)
except sqlite3.OperationalError:
except sqlite3.OperationalError as e:
logger.warning("Traffic learner hydrate: failed to open %s: %s", db_path, e)
return []
try:
rows = conn.execute(
@@ -1390,13 +1391,14 @@ class TrafficLearner:
"LIMIT ?",
(self._dedup_window,),
).fetchall()
except sqlite3.DatabaseError:
except sqlite3.DatabaseError as e:
logger.warning("Traffic learner hydrate: failed to read %s: %s", db_path, e)
return []
finally:
try:
conn.close()
except Exception:
pass
except sqlite3.Error as e:
logger.debug("Traffic learner hydrate: closing %s failed: %s", db_path, e)
return [(row[0], row[1] or "", row[2] or "{}") for row in rows]
try:
@@ -1781,7 +1783,8 @@ def _load_persisted_patterns_from_sqlite(db_path: Path) -> list[ExtractedPattern
patterns: dict[str, ExtractedPattern] = {}
try:
conn = sqlite3.connect(uri, uri=True)
except sqlite3.OperationalError:
except sqlite3.OperationalError as e:
logger.warning("Traffic learner: failed to open persisted patterns %s: %s", db_path, e)
return []
try:
conn.row_factory = sqlite3.Row
@@ -1790,14 +1793,14 @@ def _load_persisted_patterns_from_sqlite(db_path: Path) -> list[ExtractedPattern
"FROM memories "
"WHERE json_extract(metadata, '$.source') = 'traffic_learner'"
).fetchall()
except sqlite3.DatabaseError:
conn.close()
except sqlite3.DatabaseError as e:
logger.warning("Traffic learner: failed to read persisted patterns %s: %s", db_path, e)
return []
finally:
try:
conn.close()
except Exception:
pass
except sqlite3.Error as e:
logger.debug("Traffic learner: closing persisted patterns %s failed: %s", db_path, e)
for row in rows:
content = row["content"] or ""
+9
View File
@@ -77,6 +77,15 @@ class OutcomeSnapshot:
cache_write_tokens: int = 0
turn_index: int = 0
transforms_applied: tuple[str, ...] = ()
#: Input tokens Headroom removed from THIS request's payload (the wire
#: figure PERF logs as ``tok_saved``), message compression only.
tokens_saved: int = 0
#: The share of ``tokens_saved`` new to this conversation, which is what
#: running totals book (PERF ``tok_novel``). The proxy funnel always sets
#: both; they differ only on ``/v1/responses``, where the whole transcript
#: is re-sent and recompressed every turn, and ``tokens_saved -
#: novel_tokens_saved`` is the re-sent history removed again.
novel_tokens_saved: int = 0
@property
def truncated(self) -> bool:
+37 -15
View File
@@ -374,6 +374,26 @@ def _canonical_cache_rate(litellm: Any, model: str, field: str, *, long_context:
return rate if math.isfinite(rate) and rate >= 0 else 0.0
def _catalog_row(model: str) -> tuple[Any, str, dict[str, Any]] | None:
"""``(litellm, resolved model, catalog row)``, or ``None``. Never raises."""
litellm = _litellm()
if litellm is None:
return None
try:
from headroom.pricing.litellm_pricing import resolve_litellm_model
resolved_model = resolve_litellm_model(model)
info = litellm.model_cost.get(resolved_model, {}) or {}
except Exception as exc:
logger.debug(
"counterfactual: LiteLLM catalog lookup failed for %s: %s",
safe_id(model),
describe_exception(exc),
)
return None
return litellm, resolved_model, info
@lru_cache(maxsize=_RATE_CACHE_MAXSIZE)
def resolve_rates(
model: str,
@@ -413,22 +433,10 @@ def resolve_rates(
catalog between cases must call ``resolve_rates.cache_clear()`` in between,
or the previous case's rates leak into the next.
"""
litellm = _litellm()
if litellm is None:
return None
try:
from headroom.pricing.litellm_pricing import resolve_litellm_model
resolved_model = resolve_litellm_model(model)
info = litellm.model_cost.get(resolved_model, {}) or {}
except Exception as exc:
logger.debug(
"counterfactual: LiteLLM catalog lookup failed for %s: %s",
safe_id(model),
describe_exception(exc),
)
row = _catalog_row(model)
if row is None:
return None
litellm, resolved_model, info = row
base = info.get("input_cost_per_token")
# `is None` distinguishes "unknown model" from "genuinely free". `not base`
@@ -530,6 +538,19 @@ def resolve_rates(
)
def catalog_min_cacheable_tokens(model: str) -> int | None:
"""The catalog's smallest prompt the provider will cache for ``model``.
LiteLLM publishes it as ``prompt_cache_min_tokens`` (Anthropic: 1024 for
Sonnet, 4096 for Haiku 4.5). ``None`` when litellm or the row lacks it.
"""
row = _catalog_row(model)
value = row[2].get("prompt_cache_min_tokens") if row is not None else None
if isinstance(value, bool) or not isinstance(value, int | float):
return None
return int(value) if math.isfinite(value) and value > 0 else None
@dataclass(frozen=True)
class PricedSavings:
"""What a set of counterfactual tokens was worth, and how sure we are.
@@ -641,6 +662,7 @@ __all__ = [
"PricedSavings",
"Region",
"TokenSplit",
"catalog_min_cacheable_tokens",
"price_savings",
"resolve_rates",
"split_tokens",
+4
View File
@@ -44,6 +44,10 @@ try:
del _os.environ[_leaked_key]
del _env_snapshot, _os
# Probing an unknown model makes litellm print() its "Provider List"
# banner to stdout, which corrupts `headroom perf --format json`.
litellm.suppress_debug_info = True
LITELLM_AVAILABLE = True
except ImportError:
litellm = None # type: ignore[assignment]
+60 -1
View File
@@ -59,6 +59,13 @@ _ACCUMULATED_FIELDS = {
"input_json_delta": "_partial_json",
"thinking_delta": "thinking",
}
# What a non-streaming Message carries for block types whose stream form adds
# placeholders: a thinking ``content_block_start`` carries
# ``estimated_tokens: null``, which the Message schema lacks.
_MESSAGE_BLOCK_FIELDS: dict[str, frozenset[str]] = {
"thinking": frozenset({"type", "thinking", "signature"}),
"redacted_thinking": frozenset({"type", "data"}),
}
_KNOWN_MESSAGE_FIELDS = frozenset(
{
"id",
@@ -421,7 +428,11 @@ def _response_from_events(frames: list[_SSEFrame]) -> _Reconstruction:
response[key] = copy.deepcopy(delta[key])
extensions.message_delta_delta.update(_extensions(delta, _MESSAGE_DELTA_FIELDS))
if isinstance(usage, dict):
response.setdefault("usage", {}).update(copy.deepcopy(usage))
# Merged the way the Anthropic SDK's MessageStream does: a null
# count here never overwrites the one message_start reported.
response.setdefault("usage", {}).update(
{key: copy.deepcopy(value) for key, value in usage.items() if value is not None}
)
for key in usage:
if key not in extensions.message_delta_usage_keys:
extensions.message_delta_usage_keys.append(key)
@@ -682,3 +693,51 @@ def render_anthropic_sse_response(response: dict[str, Any]) -> list[bytes]:
"""
return _render_known_response(response)
def fold_anthropic_stream(raw_sse_bytes: bytes) -> dict[str, Any] | None:
"""Fold a whole Anthropic event stream into the body ``stream: false`` returns.
Blocks are accumulated as the Anthropic SDK's ``MessageStream`` does (see
``_response_from_events``), then trimmed to the non-streaming Message
shape: a null member leaves every block, and thinking blocks keep only
their schema. The proxy's own continuations resend these blocks as
history, and Anthropic rejects a block carrying a stream-only member with
400 "Extra inputs are not permitted".
Args:
raw_sse_bytes: The complete Anthropic SSE reply.
Returns:
The Message; the stream's ``error`` event when it carried one (the
same shape as an Anthropic HTTP error body); or None when the stream
ended before ``message_stop`` or with a block still open.
Raises:
ValueError: The stream is complete but holds a known event this
module cannot fold, such as a delta type it does not know.
"""
envelope = AnthropicSSEEnvelope.parse(raw_sse_bytes)
if envelope.saw_error:
for raw in _split_frames(raw_sse_bytes):
event_type, payload = _json_payload(raw)
if event_type == "error" and payload is not None:
return payload
if not envelope.is_complete():
return None
if envelope.saw_unreconstructable_frame:
raise ValueError("the event stream holds a frame that cannot be folded")
message = envelope.message
content = []
for block in message["content"]:
fields = _MESSAGE_BLOCK_FIELDS.get(block.get("type"))
content.append(
{
key: value
for key, value in block.items()
if value is not None and (fields is None or key in fields)
}
)
message["content"] = content
return message
+14 -11
View File
@@ -76,18 +76,21 @@ class BufferedCCRErrorFormat:
heartbeat: bytes
# The wire types Anthropic documents; clients switch their retry behaviour
# on these, so a 429 must not arrive labelled `api_error`.
ANTHROPIC_ERROR_TYPES: dict[int, str] = {
400: "invalid_request_error",
401: "authentication_error",
403: "permission_error",
404: "not_found_error",
413: "request_too_large",
429: "rate_limit_error",
529: "overloaded_error",
}
def _anthropic_error_type(status: int) -> str:
# The wire types Anthropic documents; clients switch their retry behaviour
# on these, so a 429 must not arrive labelled `api_error`.
return {
400: "invalid_request_error",
401: "authentication_error",
403: "permission_error",
404: "not_found_error",
413: "request_too_large",
429: "rate_limit_error",
529: "overloaded_error",
}.get(status, "api_error")
return ANTHROPIC_ERROR_TYPES.get(status, "api_error")
def _openai_error_type(status: int) -> str:
+8
View File
@@ -89,6 +89,14 @@ class CompressTurn(Protocol):
def count_messages(self, messages: list[dict[str, Any]], fallback: int) -> int:
"""Recount with the turn's own tokenizer; ``fallback`` on failure."""
# Optional, not part of the required protocol: a turn may expose
# ``tool_growth_tokens``, the tool-definition tokens ``transform`` ADDED to
# the request (a hook's search tool, say). The handler adds it to
# ``tokens_after``, since those tokens are sent too; absent reads as 0.
# Likewise optional: ``message_growth_tokens`` (message tokens it added)
# and ``hook_tool_saved_tokens`` (tool tokens it removed and booked), so
# the handler can net the two before clamping the saving.
def finish(
self,
*,
+12
View File
@@ -141,6 +141,18 @@ class GatewayTurn:
return fallback
return self._transformer.count_messages(messages, fallback)
@property
def tool_growth_tokens(self) -> int:
return self._transformer.tool_growth_tokens if self._transformer is not None else 0
@property
def message_growth_tokens(self) -> int:
return self._transformer.message_growth_tokens if self._transformer is not None else 0
@property
def hook_tool_saved_tokens(self) -> int:
return self._transformer.hook_tool_saved_tokens if self._transformer is not None else 0
# -- event-loop side ---------------------------------------------------
def finish(
self,
+24 -4
View File
@@ -342,7 +342,9 @@ def normalize_usage(usage: dict[str, Any]) -> NormalizedUsage:
# ``input_tokens`` too, so the key name cannot be the discriminator. Keying
# off Anthropic's cache fields can misread only a relay that mixes the two
# vocabularies, and then it errs towards not inflating the prompt.
input_includes_cache = not (
# Responses' ``input_tokens_details`` marks an inclusive total even when a
# relay also flattened a top-level read beside it.
input_includes_cache = "input_tokens_details" in usage or not (
"cache_read_input_tokens" in usage or "cache_creation_input_tokens" in usage
)
output_tokens = _usage_int(usage, "output_tokens")
@@ -351,10 +353,16 @@ def normalize_usage(usage: dict[str, Any]) -> NormalizedUsage:
cache_read = _usage_int(usage, "cache_read_input_tokens")
cache_write = _usage_int(usage, "cache_creation_input_tokens")
if cache_write is None:
# Responses reports billed writes as input_tokens_details.cache_write_tokens;
# chat reports none. Read whether or not a top-level read was relayed.
details = usage.get("input_tokens_details")
if isinstance(details, dict):
cache_write = _usage_int(details, "cache_write_tokens")
if cache_read is None:
# OpenAI reports reads only (no write counter exists), nested under
# prompt_tokens_details (chat), input_tokens_details (Responses) or —
# in Kong's flattened log shape — at the top level.
# OpenAI nests reads under prompt_tokens_details (chat),
# input_tokens_details (Responses) or — in Kong's flattened log shape —
# puts them at the top level.
for details_key in ("prompt_tokens_details", "input_tokens_details"):
details = usage.get(details_key)
if isinstance(details, dict):
@@ -839,6 +847,14 @@ class RequestTransformer:
self.tags = tags
self.caps = caps
self.result: RequestTransformResult | None = None
# Tool-definition tokens the request hooks ADDED (e.g. a search tool).
# The compress handler adds it to ``tokens_after``: it is sent too.
self.tool_growth_tokens = 0
# Message tokens the request hooks ADDED (only counted by the handler
# when it did not recount the messages), and tool tokens they removed
# (booked on turn_hook_tools_saved_tokens), for signed netting.
self.message_growth_tokens = 0
self.hook_tool_saved_tokens = 0
self._tokenizer: Any = None
def _get_tokenizer(self) -> Any:
@@ -909,12 +925,16 @@ class RequestTransformer:
f"{int(self.tags.get('tool_search_deferred_tokens', 0) or 0)}tok"
)
msg_after = _safe_count(count_messages, messages)
if msg_before is not None and msg_after is not None:
self.message_growth_tokens = max(0, msg_after - msg_before)
if msg_before is not None and msg_after is not None and msg_after < msg_before:
transforms.append("turn_hook")
messages_rewritten = True
tools_after = _safe_count(count_tools, without_deferral_flags(tools))
if tools_before is not None and tools_after is not None:
self.tool_growth_tokens = max(0, tools_after - tools_before)
saved = max(0, tools_before - tools_after)
self.hook_tool_saved_tokens = saved
if saved > 0:
self.tags["turn_hook_tools_saved_tokens"] = (
int(self.tags.get("turn_hook_tools_saved_tokens", 0) or 0) + saved
@@ -0,0 +1,78 @@
"""Failure logging for the proxy request path.
Exceptions on this path can carry request content: a compression hook sees the
messages, and a catch-all handler catches whatever a compressor or router raised.
So no line, at any level, carries an exception message or a traceback. A failure
is named by the request id, provider, model, hook, stage and
``describe_exception`` (exception types, code locations, errno). That holds for
upstream transport errors too: an httpx ``ProxyError`` quotes the proxy's reason
phrase, which a peer controls. Messages and tracebacks appear only under the
operator's content opt-in, ``HEADROOM_DEBUG_DUMP=full``.
"""
from __future__ import annotations
import logging
from headroom.log_safety import WarnOnce, describe_class, describe_exception, safe_id
logger = logging.getLogger("headroom.proxy")
# One warning per (hook class, stage, exception type), so a hook failing on
# every request warns once and a different hook or stage still warns.
_HOOK_WARNINGS = WarnOnce(256, "failing compression hooks")
class _HookClassKey:
"""Use class identity without running plugin metaclass hashing/equality.
Retaining the class for the bounded warning window also prevents id reuse.
"""
def __init__(self, cls: type) -> None:
self.cls = cls
def __hash__(self) -> int:
return id(self.cls)
def __eq__(self, other: object) -> bool:
return type(other) is _HookClassKey and self.cls is other.cls
def _hook_name(hooks: object) -> str:
return describe_class(type(hooks))
def log_hook_failure(
request_id: str,
stage: str,
hooks: object,
err: BaseException,
outcome: str = "continuing without it",
) -> None:
"""Log one compression-hook failure: a warning the first time per key, else debug.
``outcome`` says what the caller does next, e.g. that it skips compression.
"""
hook = _hook_name(hooks)
first = _HOOK_WARNINGS.first((_HookClassKey(type(hooks)), stage, type(err).__name__), logger)
logger.log(
logging.WARNING if first else logging.DEBUG,
"[%s] hook %s %s failed; %s: %s%s",
request_id,
hook,
stage,
outcome,
describe_exception(err),
" (repeats log at debug)" if first else "",
)
def log_request_failure(request_id: str, what: str, err: BaseException, **context: object) -> None:
"""Log a request-path failure at error.
``what`` names the operation (``"Request"``, ``"OpenAI request"``); ``context``
adds ``key=value`` fields such as provider and model.
"""
fields = "".join(f"{key}={safe_id(value)} " for key, value in context.items())
logger.error("[%s] %s failed: %s%s", request_id, what, fields, describe_exception(err))
+244 -72
View File
@@ -12,16 +12,19 @@ import logging
import os
import time
import uuid
from collections.abc import Callable
from collections.abc import Awaitable, Callable
from datetime import datetime
from functools import lru_cache
from functools import lru_cache, partial
from pathlib import Path
from typing import TYPE_CHECKING, Any
from urllib.parse import urlsplit
from headroom.proxy.session_affinity import session_affinity_headers
from headroom.proxy.stage_timer import StageTimer, emit_stage_timings_log
from headroom.proxy.tool_schema_savings_policy import without_deferral_flags
from headroom.proxy.tool_schema_savings_policy import (
net_hook_tool_saving,
without_deferral_flags,
)
if TYPE_CHECKING:
from fastapi import Request
@@ -36,10 +39,12 @@ from headroom.ccr.context_tracker import looks_like_claude_code_compact_summary
from headroom.ccr.marker_resolution import resolve_markers_in_response
from headroom.ccr.tool_calls import has_ccr_retrieve_tool
from headroom.copilot_auth import apply_copilot_api_auth, is_copilot_upstream_url
from headroom.log_safety import describe_exception
from headroom.pipeline import PipelineStage, summarize_routing_markers
from headroom.proxy import public_errors
from headroom.proxy.anthropic_wire import (
build_anthropic_upstream_url,
fold_anthropic_stream,
is_safeguard_capable_request,
preserve_opaque_response_fields,
strip_safeguard_payload,
@@ -51,11 +56,13 @@ from headroom.proxy.auth_mode import (
)
from headroom.proxy.buffered_ccr_response import (
ANTHROPIC_ERROR_FORMAT,
ANTHROPIC_ERROR_TYPES,
DEFAULT_BUFFERED_CCR_GRACE_SECONDS,
buffered_ccr_asgi_call,
)
from headroom.proxy.compression_decision import CompressionDecision
from headroom.proxy.handlers._debug_dump import _debug_dump_mode, _redact_debug_value
from headroom.proxy.handlers._failure_logging import log_hook_failure, log_request_failure
from headroom.proxy.helpers import (
extract_tags,
invalid_request_body_message,
@@ -333,8 +340,15 @@ def _dump_prefix_mismatch(request_id: str, current: list, previous: list) -> Non
fh,
default=str,
)
except Exception: # noqa: BLE001 - debug aid only
pass
except (OSError, TypeError, ValueError, RecursionError) as e: # debug aid; never fail the turn
# describe_exception keeps an OSError's errno and strerror; other errors
# could quote message content, so no message is logged.
logger.warning(
"[%s] prefix_mismatch_debug dump to %s failed: %s",
request_id,
os.environ.get("HEADROOM_DEBUG_PREFIX_MISMATCH"),
describe_exception(e),
)
class AnthropicHandlerMixin:
@@ -402,6 +416,87 @@ class AnthropicHandlerMixin:
)
return httpx.Response(200, json=parsed, headers=headers)
async def _send_buffered_as_stream(
self,
send: Callable[[dict[str, str], dict[str, Any]], Awaitable[httpx.Response]],
headers: dict[str, str],
body: dict[str, Any],
*,
url: str,
request_id: str,
) -> httpx.Response:
"""Send a non-streaming request Headroom built as a stream, and fold the reply.
The buffered CCR path flips a streaming turn to ``stream: false`` so the
whole reply is in hand before server-side retrieval, and the CCR, memory
and turn-hook continuations are built from that body. Upstream then
sends nothing until the generation is complete, and a network that
drops HTTP connections idle for ~60s (TLS-inspecting antivirus, VPN,
corporate proxy; TCP keepalive does not reset an HTTP idle timer) cuts
every long turn: each retry fails at ~60s and the client gets a 502 it
resends forever. Asked for as a stream, upstream sends deltas and pings
for the whole generation; folded, the reply is the same Message JSON the
caller already reads.
``send(headers, body)`` makes one upstream call. A reply that is not a
200 event stream (an HTTP error, or an upstream that answered JSON
anyway) is returned unchanged. A connection dropped mid-stream raises
inside ``send``, as it does for a ``stream: false`` reply; a stream that
ends early gets the 502 of ``_adapt_event_stream_to_json``; an in-band
``error`` event comes back with its HTTP status. A complete stream this
proxy cannot fold is answered by sending the original ``stream: false``
body instead, so it costs one more generation rather than a 502 the
client would resend forever.
First-party Anthropic only: a gateway's event stream is not something
the fold has been checked against. Kill switch:
``HEADROOM_BUFFERED_UPSTREAM_STREAM=0``, a runtime-env knob, so
``headroom wrap`` also pushes it to a reused proxy.
"""
from headroom.providers.claude.runtime import is_custom_anthropic_base_url
from headroom.proxy import runtime_env
if (
body.get("stream")
or is_custom_anthropic_base_url(url)
or runtime_env.getenv("HEADROOM_BUFFERED_UPSTREAM_STREAM", "1").strip().lower()
in ("0", "false", "no", "off")
):
return await send(headers, body)
stream_headers = {k: v for k, v in headers.items() if k.lower() != "accept"}
stream_headers["accept"] = "text/event-stream"
response = await send(stream_headers, {**body, "stream": True})
if response.status_code != 200 or not _looks_like_sse_response(response):
return response
try:
folded = fold_anthropic_stream(response.content)
except ValueError as exc:
logger.warning(
f"[{request_id}] Could not fold the upstream event stream ({exc}); "
"sending the request again as stream:false"
)
return await send(headers, body)
if folded is None:
# Ended early: the strict 502 any truncated reply here gets (#3266).
return self._adapt_event_stream_to_json(response, request_id)
status_code = 200
if folded.get("type") == "error":
error_type = (folded.get("error") or {}).get("type")
status_code = {name: code for code, name in ANTHROPIC_ERROR_TYPES.items()}.get(
error_type, 500
)
logger.warning(
f"[{request_id}] Upstream event stream carried an in-band "
f"{error_type!r} error; answering {status_code}"
)
return httpx.Response(
status_code,
json=folded,
headers=sanitize_forwarded_response_headers(response.headers, "content-type"),
)
async def _count_tokens_offloaded(self, model, messages): # noqa: ANN001, ANN201
from headroom.proxy.token_counting import count_tokens_offloaded
@@ -1165,9 +1260,10 @@ class AnthropicHandlerMixin:
pipeline_path = request.url.path if upstream_base_url else "/v1/messages"
pipeline_stream = bool(body.get("stream", False) or force_stream)
# O1 (2026-09-27 perf audit): the snapshot of the original
# conversation aliases the live list unless hooks or pipeline
# extensions are configured - those can mutate `messages` in place
# (pre_compress receives the live list), so then the snapshot is an
# conversation aliases the live list unless hooks, pipeline
# extensions or turn hooks are configured - those can mutate
# `messages` in place (pre_compress receives the live list, skill
# search folds text in place), so then the snapshot is an
# independently owned copy (snapshot_original_messages). The
# deep_copy stage is always measured so the timing summary keeps
# its key.
@@ -1596,7 +1692,7 @@ class AnthropicHandlerMixin:
try:
messages = self.config.hooks.pre_compress(messages, _hook_ctx)
except Exception as e:
logger.debug(f"[{request_id}] pre_compress hook error: {e}")
log_hook_failure(request_id, "pre_compress", self.config.hooks, e)
else:
_hook_ctx = None
@@ -1894,21 +1990,31 @@ class AnthropicHandlerMixin:
scope=credential_scope_from_headers(headers),
)
result = None
biases = (
self.config.hooks.compute_biases(messages, _hook_ctx)
if self.config.hooks and _hook_ctx is not None
else None
)
biases = None
# Hard per-message veto. Separate from ``biases`` because a
# bias is a soft multiplier that several strategies clamp or
# ignore, so it cannot express "leave this one alone".
from headroom.hooks import collect_protected
protect = None
if self.config.hooks and _hook_ctx is not None:
from headroom.hooks import collect_protected
protect = (
collect_protected(self.config.hooks, messages, _hook_ctx)
if self.config.hooks and _hook_ctx is not None
else None
)
# A failure still aborts optimization for this request (the
# outer handler forwards it uncompressed); this only names
# the stage. Compressing without a veto would be unsafe.
_hook_stage = "compute_biases"
try:
biases = self.config.hooks.compute_biases(messages, _hook_ctx)
_hook_stage = "protect_messages"
protect = collect_protected(self.config.hooks, messages, _hook_ctx)
except Exception as e:
log_hook_failure(
request_id,
_hook_stage,
self.config.hooks,
e,
outcome="skipping compression for this turn",
)
raise
# F2.1 c5/5: derive the per-request CompressionPolicy
# from the auth_mode classified at request entry. The
@@ -2290,8 +2396,12 @@ class AnthropicHandlerMixin:
# enabled" with Before == After (issue #2357).
tags["passthrough_reason"] = "cache_mode_prefix_mismatch"
logger.info(
"[%s] Compression skipped: reason=cache_mode_prefix_mismatch",
"[%s] Compression skipped: reason=cache_mode_prefix_mismatch "
"model=%s current_len=%d previous_len=%d",
request_id,
model,
len(original_client_messages),
len(previous_original_messages),
)
if os.environ.get("HEADROOM_DEBUG_PREFIX_MISMATCH"):
_dump_prefix_mismatch(
@@ -2310,9 +2420,11 @@ class AnthropicHandlerMixin:
if result and result.waste_signals:
waste_signals_dict = result.waste_signals.to_dict()
except Exception as e:
# Include type so TimeoutError vs other failures is distinguishable
# in bug reports — str(asyncio.TimeoutError()) is empty otherwise.
logger.warning(f"[{request_id}] Optimization failed: {type(e).__name__}: {e}")
# Types and code locations only: a compressor or hook error can
# quote the messages it was given.
logger.warning(
"[%s] Optimization failed: %s", request_id, describe_exception(e)
)
# Flag compression failure for observability
_compression_failed = True
# Split timeout from other errors: a timeout means the
@@ -2538,7 +2650,7 @@ class AnthropicHandlerMixin:
)
)
except Exception as e:
logger.debug(f"[{request_id}] post_compress hook error: {e}")
log_hook_failure(request_id, "post_compress", self.config.hooks, e)
# CCR Tool Injection: Inject retrieval tool if compression occurred
# OR if this session has previously done CCR (PR-B7 sticky-on).
@@ -3056,7 +3168,12 @@ class AnthropicHandlerMixin:
def _count_tool_tokens(value: object) -> int:
try:
return tokenizer.count_text(json.dumps(value, default=str))
except Exception:
except Exception as e:
logger.debug(
"[%s] tool token count failed; tool savings not counted: %s",
request_id,
describe_exception(e),
)
return 0
_tools_compaction_started = time.time()
@@ -3309,6 +3426,11 @@ class AnthropicHandlerMixin:
)
_pre_hook_tokens: int | None = None
# Tool-definition tokens a turn hook ADDED (e.g. a search tool). Folded
# into the forwarded count below so the headline nets them; shrinkage
# stays on the turn_hook_tools_saved_tokens tag.
_th_tool_growth = 0
_th_saved = 0
_req_ctx: TurnContext | None = None
if registered_turn_hooks():
_req_ctx = TurnContext(
@@ -3351,6 +3473,7 @@ class AnthropicHandlerMixin:
else 0
)
_th_saved = max(0, _th_tok_before - _th_tok_after)
_th_tool_growth = max(0, _th_tok_after - _th_tok_before)
if _th_saved > 0:
tags["turn_hook_tools_saved_tokens"] = (
int(tags.get("turn_hook_tools_saved_tokens", 0) or 0) + _th_saved
@@ -3476,6 +3599,8 @@ class AnthropicHandlerMixin:
if 0 < _tool_tokens_after < _tool_tokens_before:
original_tokens += _tool_tokens_before
optimized_tokens += _tool_tokens_after
# A tool a turn hook added is sent too: it reduces the saving.
optimized_tokens += _th_tool_growth
# First-appearance accounting for matured Reads. The client
# re-sends the raw conversation every turn, so this diff would
# otherwise re-book a matured Read's removal on every request
@@ -3496,7 +3621,11 @@ class AnthropicHandlerMixin:
# Advisory, like the maturation pass itself: a failure
# here must not skip the recount around it.
logger.debug("maturation replay debt skipped", exc_info=True)
tokens_saved = max(0, original_tokens - optimized_tokens - _replay_debt)
# Signed, then clamped once: message text a hook added offsets
# the tool definitions it removed (booked on the tag above).
tokens_saved = net_hook_tool_saving(
original_tokens - optimized_tokens - _replay_debt, tags, _th_saved
)
# Attribute the fold to the hook ONLY when the hook itself reduced
# tokens (same-tokenizer pre vs post) — not when the recount above
# merely normalized a cross-estimator scale difference.
@@ -4212,11 +4341,10 @@ class AnthropicHandlerMixin:
async def _buffered_ccr_operation():
async with stage_timer.measure("upstream_connect"):
response = await self._retry_request(
send_upstream = partial(
self._retry_request,
"POST",
url,
headers,
body,
original_body_bytes=original_body_bytes,
body_mutated=body_mutation_tracker.mutated,
mutation_reasons=body_mutation_tracker.reasons,
@@ -4225,6 +4353,14 @@ class AnthropicHandlerMixin:
path_for_log="/v1/messages",
timeout=self._anthropic_buffered_request_timeout(),
)
# Only the CCR flip goes out as a stream: a client's
# own stream:false request keeps its bytes.
if buffered_stream_ccr:
response = await self._send_buffered_as_stream(
send_upstream, headers, body, url=url, request_id=request_id
)
else:
response = await send_upstream(headers, body)
self.pipeline_extensions.emit(
PipelineStage.POST_SEND,
operation="proxy.request",
@@ -4508,7 +4644,8 @@ class AnthropicHandlerMixin:
# Reuse main client for CCR continuations (connection pooling)
logger.info(
f"CCR: Making continuation request with {len(msgs)} messages"
f"[{request_id}] CCR: Making continuation request "
f"with {len(msgs)} messages"
)
assert self.http_client is not None, "HTTP client not initialized"
# Byte-faithful (PR-A3, fixes P0-2). The CCR
@@ -4520,13 +4657,6 @@ class AnthropicHandlerMixin:
)
from headroom.proxy.helpers import log_outbound_request
ccr_outbound_bytes, ccr_outbound_source = (
prepare_outbound_body_bytes(
body=continuation_body,
original_body_bytes=None,
body_mutated=True,
)
)
# A continuation is a non-streaming call, so it
# needs a matching Accept for the same reason the
# buffered flip above does (#3078).
@@ -4537,25 +4667,47 @@ class AnthropicHandlerMixin:
}
ccr_outbound_headers["content-type"] = "application/json"
ccr_outbound_headers["accept"] = "application/json"
log_outbound_request(
forwarder="anthropic_ccr_continuation",
method="POST",
path=url,
body_bytes_count=len(ccr_outbound_bytes),
body_mutated=True,
mutation_reasons=["ccr_continuation"],
request_id=request_id,
source=ccr_outbound_source,
)
try:
cont_response = await self.http_client.post(
async def _post_continuation(
send_headers: dict[str, str], send_body: dict[str, Any]
) -> httpx.Response:
assert self.http_client is not None
ccr_outbound_bytes, ccr_outbound_source = (
prepare_outbound_body_bytes(
body=send_body,
original_body_bytes=None,
body_mutated=True,
)
)
log_outbound_request(
forwarder="anthropic_ccr_continuation",
method="POST",
path=url,
body_bytes_count=len(ccr_outbound_bytes),
body_mutated=True,
mutation_reasons=["ccr_continuation"],
request_id=request_id,
source=ccr_outbound_source,
)
return await self.http_client.post(
url,
content=ccr_outbound_bytes,
headers=ccr_outbound_headers,
headers=send_headers,
timeout=self._anthropic_buffered_request_timeout(),
)
cont_response: httpx.Response | None = None
try:
cont_response = await self._send_buffered_as_stream(
_post_continuation,
ccr_outbound_headers,
continuation_body,
url=url,
request_id=request_id,
)
logger.info(
f"CCR: Got response status={cont_response.status_code}, "
f"[{request_id}] CCR: Got response "
f"status={cont_response.status_code}, "
f"content-encoding={cont_response.headers.get('content-encoding')}"
)
if not 200 <= cont_response.status_code < 300:
@@ -4564,16 +4716,23 @@ class AnthropicHandlerMixin:
f"{cont_response.status_code}"
)
result: dict[str, Any] = cont_response.json()
logger.info("CCR: Parsed JSON successfully")
logger.info(f"[{request_id}] CCR: Parsed JSON successfully")
return result
except Exception as e:
resp_headers: str | dict[str, str] = "N/A"
try:
resp_headers = dict(cont_response.headers)
except Exception:
pass
logger.error(
f"CCR: API call failed: {e}, response headers: {resp_headers}"
# Status and the upstream request id only:
# the other response headers are not ours
# to copy into a log.
upstream_request_id = (
cont_response.headers.get("request-id")
if cont_response is not None
else None
)
log_request_failure(
request_id,
"CCR continuation",
e,
status=getattr(cont_response, "status_code", None),
upstream_request_id=upstream_request_id,
)
raise
@@ -4758,12 +4917,17 @@ class AnthropicHandlerMixin:
if tools:
continuation_body["tools"] = tools
cont_response = await self._retry_request(
"POST",
url,
cont_response = await self._send_buffered_as_stream(
partial(
self._retry_request,
"POST",
url,
timeout=self._anthropic_buffered_request_timeout(),
),
headers,
continuation_body,
timeout=self._anthropic_buffered_request_timeout(),
url=url,
request_id=request_id,
)
# Update response with continuation
@@ -4800,12 +4964,17 @@ class AnthropicHandlerMixin:
hook_messages: list[dict[str, Any]],
) -> dict[str, Any]:
continuation_body = {**body, "messages": hook_messages}
continuation_response = await self._retry_request(
"POST",
url,
continuation_response = await self._send_buffered_as_stream(
partial(
self._retry_request,
"POST",
url,
timeout=self._anthropic_buffered_request_timeout(),
),
headers,
continuation_body,
timeout=self._anthropic_buffered_request_timeout(),
url=url,
request_id=request_id,
)
continuation_json = continuation_response.json()
_hook_usage.record(continuation_json)
@@ -5401,8 +5570,11 @@ class AnthropicHandlerMixin:
raise
except Exception as e:
await self.metrics.record_failed(provider=provider_name)
# Log full error details internally for debugging
logger.error(f"[{request_id}] Request failed: {type(e).__name__}: {e}")
# Error names the failure; text and traceback go to debug.
# `model` is unbound when the failure precedes body parsing.
log_request_failure(
request_id, "Request", e, provider=provider_name, model=locals().get("model")
)
# An untrusted TLS-inspection root is the one failure worth
# spelling out: it is environmental, never transient, and the
@@ -5666,7 +5838,7 @@ class AnthropicHandlerMixin:
pipeline_timing: dict[str, float] = {}
# O1 (2026-09-27 perf audit): the per-request snapshot aliases unless
# hooks or extensions are configured (see the main handler).
# hooks, extensions or turn hooks are configured (see the main handler).
from headroom.proxy.helpers import snapshot_original_messages
from headroom.transforms.cold_prefix import anthropic_cache_ttl_seconds
@@ -5914,7 +6086,7 @@ class AnthropicHandlerMixin:
except Exception as e:
await self.metrics.record_failed(provider="anthropic")
logger.error(f"[{request_id}] Batch request failed: {type(e).__name__}: {e}")
log_request_failure(request_id, "Anthropic batch request", e)
return JSONResponse(
status_code=502,
content={
+7 -3
View File
@@ -15,6 +15,7 @@ if TYPE_CHECKING:
from fastapi.responses import Response
from headroom.proxy.auth_mode import classify_client
from headroom.proxy.handlers._failure_logging import log_request_failure
from headroom.proxy.helpers import (
COMPRESSION_TIMEOUT_SECONDS,
_headroom_bypass_enabled,
@@ -374,6 +375,7 @@ class BatchHandlerMixin:
await self._store_google_batch_context(
batch_name,
requests_list,
compressed_requests,
model,
api_key,
)
@@ -392,7 +394,7 @@ class BatchHandlerMixin:
)
except Exception as e:
logger.error(f"[{request_id}] Google batch request failed: {e}")
log_request_failure(request_id, "Google batch request", e, model=model)
return JSONResponse(
status_code=500,
content={
@@ -619,6 +621,7 @@ class BatchHandlerMixin:
self,
batch_name: str,
requests_list: list[dict[str, Any]],
forwarded_requests: list[dict[str, Any]],
model: str,
api_key: str | None,
) -> None:
@@ -627,6 +630,7 @@ class BatchHandlerMixin:
Args:
batch_name: The batch name from the API response.
requests_list: The original batch requests.
forwarded_requests: Effective requests with any injected native tools.
model: The model used for the batch.
api_key: The API key for continuation calls.
"""
@@ -640,7 +644,7 @@ class BatchHandlerMixin:
api_base_url=self.GEMINI_API_URL,
)
for batch_req in requests_list:
for batch_req, forwarded_req in zip(requests_list, forwarded_requests, strict=True):
metadata = batch_req.get("metadata", {})
custom_id = metadata.get("key", "")
req_content = batch_req.get("request", {})
@@ -661,7 +665,7 @@ class BatchHandlerMixin:
BatchRequestContext(
custom_id=custom_id,
messages=messages,
tools=req_content.get("tools"),
tools=forwarded_req.get("request", {}).get("tools"),
model=model,
system_instruction=sys_text,
)
+7 -2
View File
@@ -22,6 +22,7 @@ from headroom.agent_savings import proxy_pipeline_kwargs
from headroom.copilot_auth import build_copilot_upstream_url
from headroom.proxy.auth_mode import classify_client
from headroom.proxy.compression_decision import CompressionDecision
from headroom.proxy.handlers._failure_logging import log_request_failure
from headroom.proxy.helpers import (
COMPRESSION_TIMEOUT_SECONDS,
extract_tags,
@@ -1111,7 +1112,9 @@ class GeminiHandlerMixin:
return Response(content=e.content, status_code=e.status_code, headers=response_headers)
except Exception as e:
await self.metrics.record_failed(provider=provider_name)
logger.error(f"[{request_id}] Gemini request failed: {type(e).__name__}: {e}")
log_request_failure(
request_id, "Gemini request", e, provider=provider_name, model=model
)
return JSONResponse(
status_code=502,
content={
@@ -1581,7 +1584,9 @@ class GeminiHandlerMixin:
)
except Exception as e:
await self.metrics.record_failed(provider=provider_name)
logger.error(f"[{request_id}] Gemini countTokens failed: {type(e).__name__}: {e}")
log_request_failure(
request_id, "Gemini countTokens", e, provider=provider_name, model=model
)
return JSONResponse(
status_code=502,
content={
+248 -44
View File
@@ -25,7 +25,9 @@ from datetime import datetime
from typing import TYPE_CHECKING, Any
from urllib.parse import quote, unquote, urlparse
from headroom.log_safety import describe_exception
from headroom.proxy.conversation_savings import savings_conversation_key
from headroom.proxy.handlers._failure_logging import log_hook_failure, log_request_failure
from headroom.proxy.helpers import (
COMPRESSION_TIMEOUT_SECONDS,
_headroom_bypass_enabled,
@@ -43,9 +45,13 @@ from headroom.proxy.provider_usage import (
usage_int,
)
from headroom.proxy.rate_limit_identity import rate_limit_identity
from headroom.proxy.savings import ItemMeasure, get_item_ledger, prefix_key, responses_items
from headroom.proxy.semantic_cache_key_policy import compute_request_cache_partition
from headroom.proxy.stage_timer import StageTimer, emit_stage_timings_log
from headroom.proxy.tool_schema_savings_policy import without_deferral_flags
from headroom.proxy.tool_schema_savings_policy import (
net_hook_tool_saving,
without_deferral_flags,
)
from headroom.proxy.upstream_guard import is_safe_upstream_url
from headroom.proxy.ws_headers import WS_HOP_BY_HOP_HEADERS
from headroom.proxy.ws_session_registry import (
@@ -69,6 +75,7 @@ from headroom.config import is_tool_excluded, unwrap_tool_call_name
from headroom.copilot_auth import (
apply_copilot_api_auth,
build_copilot_upstream_url,
copilot_nes_base_url,
is_copilot_api_url,
)
from headroom.pipeline import PipelineStage, summarize_routing_markers
@@ -345,13 +352,22 @@ class TurnHookUsage:
the safe direction for a bill.
"""
__slots__ = ("_seen", "input_tokens", "output_tokens", "cache_read_tokens", "extra_calls")
__slots__ = (
"_seen",
"input_tokens",
"output_tokens",
"cache_read_tokens",
"cache_write_tokens",
"extra_calls",
)
def __init__(self) -> None:
self._seen: list[tuple[int, Any, int, int, int]] = []
self._seen: list[tuple[int, Any, int, int, int, int]] = []
self.input_tokens = 0
self.output_tokens = 0
self.cache_read_tokens = 0
#: Reported (Responses ``cache_write_tokens``) writes only; 0 otherwise.
self.cache_write_tokens = 0
self.extra_calls = 0
def record(
@@ -375,17 +391,19 @@ class TurnHookUsage:
usage_int(usage.get(input_key)),
usage_int(usage.get(output_key)),
cached,
_reported_cache_write(details) or 0,
)
else:
entry = (id(payload), payload, 0, 0, 0)
entry = (id(payload), payload, 0, 0, 0, 0)
self._seen.append(entry)
def settle(self, final: Any) -> None:
"""Total everything except ``final``, which the usage block will read."""
self.input_tokens = self.output_tokens = self.cache_read_tokens = 0
self.cache_write_tokens = 0
self.extra_calls = 0
dropped = False
for _ident, payload, tin, tout, cached in self._seen:
for _ident, payload, tin, tout, cached, written in self._seen:
if not dropped and payload is final:
dropped = True
continue
@@ -393,6 +411,7 @@ class TurnHookUsage:
self.input_tokens += tin
self.output_tokens += tout
self.cache_read_tokens += cached
self.cache_write_tokens += written
def _sanitize_forwarded_response_headers(
@@ -608,7 +627,13 @@ def _passthrough_usage_from_json(payload: Any, provider: str | None = None) -> d
"input_tokens": billed_input_from_usage(usage, provider) or usage_int(input_tokens),
"output_tokens": usage_int(output_tokens),
"cache_read_input_tokens": usage_int(usage.get("cache_read_input_tokens", cache_read)),
"cache_creation_input_tokens": usage_int(usage.get("cache_creation_input_tokens")),
# Responses spells a billed write ``input_tokens_details.cache_write_tokens``.
"cache_creation_input_tokens": usage_int(
usage.get(
"cache_creation_input_tokens",
details.get("cache_write_tokens") if isinstance(details, dict) else None,
)
),
}
return {}
@@ -1644,6 +1669,48 @@ def _infer_openai_cache_write_tokens(input_tokens: int, cache_read_tokens: int)
return max(input_tokens - cache_read_tokens, 0)
def _reported_cache_write(details: Any) -> int | None:
"""``input_tokens_details.cache_write_tokens``, or ``None`` when not reported."""
if not isinstance(details, dict) or details.get("cache_write_tokens") is None:
return None
return usage_int(details.get("cache_write_tokens"))
def _hook_reported_write(final_write: int | None, hook_usage: Any) -> int | None:
"""The final response's reported write plus any turn-hook re-drives' writes.
A final response without the field still carries the re-drives' reported
writes: treating its own write as 0 prices the same as inferring it, since
an inferred write is dropped from pricing anyway.
"""
hook_writes = hook_usage.cache_write_tokens if hook_usage.extra_calls else 0
if final_write is None:
return hook_writes or None
return final_write + hook_writes
def _openai_responses_cache_split(
input_tokens: int, cached: int, reported_write: int | None
) -> tuple[int, int, int, bool]:
"""Split a Responses ``input_tokens`` total into ``(read, write, uncached, inferred)``.
Responses usage now reports cache writes itself as
``input_tokens_details.cache_write_tokens``, billed at the write rate
(above list input on current models). When present it is the truth and the
three buckets are disjoint. Older responses omit it; the write is then
inferred from the uncached slice and flagged, so pricing drops it rather
than billing the same tokens twice.
"""
if reported_write is not None:
return cached, reported_write, max(input_tokens - cached - reported_write, 0), False
return (
cached,
_infer_openai_cache_write_tokens(input_tokens, cached),
max(input_tokens - cached, 0),
True,
)
def _deferrable_savings_delta(input_delta: int, saved_delta: int) -> int:
"""Gate a WS Responses turn's compression-savings delta on input accounting.
@@ -1664,32 +1731,36 @@ def _deferrable_savings_delta(input_delta: int, saved_delta: int) -> int:
return saved_delta
def _extract_responses_usage(event: dict[str, Any]) -> tuple[int, int, int, int, int]:
def _extract_responses_usage(event: dict[str, Any]) -> tuple[int, int, int, int, int, bool]:
"""Return input/output/cache usage from a Responses event.
Codex WebSocket streams include usage on ``response.completed`` events.
The shape mirrors HTTP Responses usage:
``response.usage.input_tokens`` plus
``response.usage.input_tokens_details.cached_tokens``.
``response.usage.input_tokens_details.cached_tokens`` / ``cache_write_tokens``.
The last element says whether the write was inferred (see
:func:`_openai_responses_cache_split`).
"""
if event.get("type") != "response.completed":
return 0, 0, 0, 0, 0
return 0, 0, 0, 0, 0, True
response = event.get("response")
if not isinstance(response, dict):
response = {}
usage = response.get("usage") or event.get("usage")
if not isinstance(usage, dict):
return 0, 0, 0, 0, 0
return 0, 0, 0, 0, 0, True
input_tokens = usage_int(usage.get("input_tokens"))
output_tokens = usage_int(usage.get("output_tokens"))
details = usage.get("input_tokens_details")
cached_tokens = usage_int(details.get("cached_tokens")) if isinstance(details, dict) else 0
cache_write_tokens = _infer_openai_cache_write_tokens(input_tokens, cached_tokens)
uncached_tokens = max(input_tokens - cached_tokens, 0)
return input_tokens, output_tokens, cached_tokens, cache_write_tokens, uncached_tokens
cached, write, uncached, inferred = _openai_responses_cache_split(
input_tokens,
usage_int(details.get("cached_tokens")) if isinstance(details, dict) else 0,
_reported_cache_write(details),
)
return input_tokens, output_tokens, cached, write, uncached, inferred
def _prefers_http1_passthrough(base_url: str) -> bool:
@@ -2698,8 +2769,12 @@ class OpenAIHandlerMixin:
- tokenizer.count_text(_json_debug_dumps(working.get("tools"))),
)
_add_timing("compression_tool_schema_token_count", tool_token_started)
except Exception:
pass
except Exception as e:
logger.debug(
"[%s] tool schema compaction token count failed; savings not counted: %s",
request_id,
describe_exception(e),
)
# Layer 2: Tool description truncation (opt-in via
# HEADROOM_TOOL_DESC_MAX_CHARS).
@@ -2727,10 +2802,17 @@ class OpenAIHandlerMixin:
tokenizer.count_text(_json_debug_dumps(payload.get("tools")))
- tokenizer.count_text(_json_debug_dumps(working.get("tools"))),
)
except Exception:
pass
except Exception:
pass
except Exception as e:
logger.debug(
"[%s] tool desc compaction token count failed; savings not counted: %s",
request_id,
describe_exception(e),
)
except Exception as e:
# Tool schemas are client content: log the failure, never its message.
logger.warning(
"[%s] tool desc compaction step failed: %s", request_id, describe_exception(e)
)
# Server-side Tool Search deferral (OpenAI Responses, gpt-5.4+): mark
# non-core function/MCP tools defer_loading + inject {"type": "tool_search"}
@@ -2852,8 +2934,12 @@ class OpenAIHandlerMixin:
)
if _mt_after < _mt_before:
tokens_saved += _mt_before - _mt_after
except Exception:
pass
except Exception as e:
logger.debug(
"[%s] turn-hook message fold token count failed; savings not counted: %s",
request_id,
describe_exception(e),
)
modified = True
transforms.append("openai:responses:turn_hook")
@@ -2902,8 +2988,12 @@ class OpenAIHandlerMixin:
"compression_tool_schema_attempted_token_count",
attempted_token_started,
)
except Exception:
pass
except Exception as e:
logger.debug(
"[%s] tool schema attempted-token count failed: %s",
request_id,
describe_exception(e),
)
dedupe_started = time.perf_counter()
deduped: list[str] = []
@@ -3134,8 +3224,8 @@ class OpenAIHandlerMixin:
model = body.get("model", "unknown")
messages = body.get("messages", [])
# O1 (2026-09-27 perf audit): the snapshot of the original
# conversation aliases the live list unless hooks or pipeline
# extensions are configured; those can mutate `messages` in place
# conversation aliases the live list unless hooks, pipeline extensions
# or turn hooks are configured; those can mutate `messages` in place
# (pre_compress receives the live list), so then it is an
# independently owned copy (see snapshot_original_messages).
from headroom.proxy.helpers import snapshot_original_messages
@@ -3145,6 +3235,16 @@ class OpenAIHandlerMixin:
)
custom_upstream_base_url = _resolve_openai_upstream_base(request.headers)
upstream_base_url = self._resolve_openai_upstream(request)
# Ghost text and next edits: CAPI does not serve these models. A
# caller-chosen x-headroom-base-url is left alone, as in
# select_passthrough_base_url.
nes_base_url = (
copilot_nes_base_url(model, upstream_base_url)
if custom_upstream_base_url is None
else None
)
if nes_base_url:
upstream_base_url = nes_base_url
handler_path_suffix = _resolve_openai_chat_handler_path(
upstream_base_url,
model,
@@ -3525,12 +3625,15 @@ class OpenAIHandlerMixin:
from headroom.hooks import CompressContext, collect_protected
_hook_ctx = CompressContext(model=model, provider="openai")
_hook_stage = "pre_compress"
try:
messages = self.config.hooks.pre_compress(messages, _hook_ctx)
_hook_stage = "compute_biases"
_hook_biases = self.config.hooks.compute_biases(messages, _hook_ctx)
_hook_stage = "protect_messages"
_hook_protect = collect_protected(self.config.hooks, messages, _hook_ctx)
except Exception as e:
logger.debug(f"[{request_id}] Hook error: {e}")
log_hook_failure(request_id, _hook_stage, self.config.hooks, e)
# x-headroom-keep-last-turns: N — trim history before optimization.
# Consumed here (after bypass check, after _strip_internal_headers)
@@ -3935,7 +4038,7 @@ class OpenAIHandlerMixin:
)
)
except Exception as e:
logger.debug(f"[{request_id}] post_compress hook error: {e}")
log_hook_failure(request_id, "post_compress", self.config.hooks, e)
# CCR Tool Injection: Inject retrieval tool if compression occurred
# OR if this session has previously done CCR (PR-B7 sticky-on).
@@ -4335,6 +4438,7 @@ class OpenAIHandlerMixin:
)
_th_ctx: TurnContext | None = None
_th_raw_saved = None
if registered_turn_hooks():
_th_tools_before = body.get("tools")
_th_tok_before = (
@@ -4382,7 +4486,17 @@ class OpenAIHandlerMixin:
optimized_tokens = _th_msg_after
if 0 < tool_tokens_after_compaction < tool_tokens_before_compaction:
optimized_tokens += tool_tokens_after_compaction
tokens_saved = max(0, original_tokens - optimized_tokens)
# A tool the hook added is sent too: it reduces the saving.
_th_tools_after_count = (
tokenizer.count_text(
json.dumps(without_deferral_flags(_th_ctx.tools), default=str)
)
if _th_ctx.tools
else 0
)
optimized_tokens += max(0, _th_tools_after_count - _th_tok_before)
_th_raw_saved: int | None = original_tokens - optimized_tokens
tokens_saved = max(0, _th_raw_saved)
# Attribute to the hook ONLY when the hook itself reduced tokens.
if _th_msg_before is not None and _th_msg_after < _th_msg_before:
transforms_applied.append("turn_hook")
@@ -4399,6 +4513,10 @@ class OpenAIHandlerMixin:
int(tags.get("turn_hook_tools_saved_tokens", 0) or 0) + _th_saved
)
transforms_applied.append(f"turn_hook:tools:{_th_saved}tok")
# Signed, then clamped once: message text a hook added offsets the
# tool definitions it removed.
if _th_raw_saved is not None:
tokens_saved = net_hook_tool_saving(_th_raw_saved, tags, _th_saved)
# Compatibility shim: GPT-5 / o-series chat models REJECT the legacy
# `max_tokens` ("Unsupported parameter … Use 'max_completion_tokens'
@@ -4752,8 +4870,12 @@ class OpenAIHandlerMixin:
current_forwarded_messages=optimized_messages,
),
)
except Exception:
pass
except Exception as e:
logger.debug(
"[%s] cache observation (openai chat, backend) failed: %s",
request_id,
describe_exception(e),
)
openai_prefix_tracker.update_from_response(
cache_read_tokens=cache_read_tokens,
@@ -5252,8 +5374,12 @@ class OpenAIHandlerMixin:
current_forwarded_messages=optimized_messages,
),
)
except Exception:
pass
except Exception as e:
logger.debug(
"[%s] cache observation (openai chat, direct) failed: %s",
request_id,
describe_exception(e),
)
openai_prefix_tracker.update_from_response(
cache_read_tokens=cache_read_tokens,
@@ -5446,8 +5572,14 @@ class OpenAIHandlerMixin:
)
except Exception as e:
await self.metrics.record_failed(provider=openai_chat_outcome_provider)
# Log full error details internally for debugging
logger.error(f"[{request_id}] OpenAI request failed: {type(e).__name__}: {e}")
# Error names the failure; text and traceback go to debug.
log_request_failure(
request_id,
"OpenAI request",
e,
provider=openai_chat_outcome_provider,
model=model,
)
# Return sanitized error message to client (don't expose internal details)
return JSONResponse(
status_code=502,
@@ -6260,6 +6392,36 @@ class OpenAIHandlerMixin:
"upstream request for server-side retrieval handling"
)
# Per-item original/sent counts against this conversation's previous
# request, in Headroom's tokenizer (headroom.proxy.savings). ORIGINAL
# is the client's bytes, before memory, compression or shaping; SENT is
# the body forwarded below. All of it runs off the event loop: it
# decodes, serializes and tokenizes the whole transcript. Skipped for
# incremental bodies (previous_response_id / conversation): the
# provider bills context they do not carry. It covers the first
# upstream call only; continuations and re-drives are the wiring's to
# mark as estimated. The outcome funnel settles it (ItemLedger.settle).
savings_measure = None
if not (body.get("previous_response_id") or body.get("conversation")):
def _measure_items() -> ItemMeasure:
original = responses_items(json.loads(original_body_bytes))
return get_item_ledger().measure(
prefix_key(_pre_compression_conversation_key, model, original),
original,
responses_items(body),
tokenizer.count_text,
)
try:
savings_measure = await asyncio.to_thread(_measure_items)
except Exception as exc: # noqa: BLE001 - telemetry must never break a request
logger.warning(
"[%s] savings item measurement skipped: %s",
request_id,
describe_exception(exc),
)
try:
if stream and not buffered_stream_ccr:
# Streaming for Responses API uses semantic events
@@ -6284,6 +6446,7 @@ class OpenAIHandlerMixin:
waste_signals=waste_signals_dict,
conversation_key=responses_conversation_key,
conversation_tokens_saved=tokens_saved,
savings_measure=savings_measure,
)
else:
@@ -6471,6 +6634,7 @@ class OpenAIHandlerMixin:
total_input_tokens = original_tokens # fallback
output_tokens = 0
cache_read_tokens = 0
details: Any = None
resp_json = None
try:
resp_json = response.json()
@@ -6690,11 +6854,17 @@ class OpenAIHandlerMixin:
# Cost is recorded once by the outcome funnel below; here we only
# compute the cache-write / uncached split the funnel needs.
# (Recording here too double-counted spend + budget on this path.)
cache_write_tokens = _infer_openai_cache_write_tokens(
# Reads include the hook's re-drives added above.
(
cache_read_tokens,
cache_write_tokens,
uncached_input_tokens,
cache_inferred,
) = _openai_responses_cache_split(
total_input_tokens,
cache_read_tokens,
_hook_reported_write(_reported_cache_write(details), _resp_hook_usage),
)
uncached_input_tokens = max(0, total_input_tokens - cache_read_tokens)
# Was: optimized := provider count, then original := max(original,
# optimized + saved) to stop `attempted` exceeding `original`.
@@ -6736,7 +6906,7 @@ class OpenAIHandlerMixin:
cache_read_tokens=cache_read_tokens,
cache_write_tokens=cache_write_tokens,
uncached_input_tokens=uncached_input_tokens,
cache_inferred=True,
cache_inferred=cache_inferred,
total_latency_ms=total_latency,
overhead_ms=optimization_latency,
transforms_applied=tuple(transforms_applied),
@@ -6745,6 +6915,7 @@ class OpenAIHandlerMixin:
tags=_resp_log_tags,
conversation_key=responses_conversation_key,
conversation_tokens_saved=tokens_saved,
savings_measure=savings_measure,
turn_id=compute_turn_id(model, body.get("instructions"), messages),
request_messages=messages
if getattr(self.config, "log_full_messages", False)
@@ -6878,7 +7049,7 @@ class OpenAIHandlerMixin:
return await _buffered_ccr_operation()
except Exception as e:
await self.metrics.record_failed(provider="openai")
logger.error(f"[{request_id}] OpenAI responses request failed: {type(e).__name__}: {e}")
log_request_failure(request_id, "OpenAI responses request", e, model=model)
return JSONResponse(
status_code=502,
content={
@@ -7497,6 +7668,11 @@ class OpenAIHandlerMixin:
ws_cache_read_tokens_total = 0
ws_cache_write_tokens_total = 0
ws_uncached_input_tokens_total = 0
# Whether the latest usage frame's write was inferred rather than
# reported (see _openai_responses_cache_split). One flag for the
# summed deltas: a session that mixed reported and unreported
# frames would misprice one kind, which Codex does not do.
ws_cache_inferred = True
ws_recorded_input_tokens_total = 0
ws_recorded_output_tokens_total = 0
ws_recorded_cache_read_tokens_total = 0
@@ -8823,7 +8999,7 @@ class OpenAIHandlerMixin:
nonlocal ws_memory_response_pending
nonlocal ws_input_tokens_total, ws_output_tokens_total
nonlocal ws_cache_read_tokens_total, ws_cache_write_tokens_total
nonlocal ws_uncached_input_tokens_total
nonlocal ws_uncached_input_tokens_total, ws_cache_inferred
nonlocal ws_recorded_input_tokens_total
nonlocal ws_recorded_output_tokens_total
nonlocal ws_recorded_cache_read_tokens_total
@@ -8953,6 +9129,7 @@ class OpenAIHandlerMixin:
cache_read_tokens=max(0, cache_read_delta),
cache_write_tokens=max(0, cache_write_delta),
uncached_input_tokens=max(0, uncached_delta),
cache_inferred=ws_cache_inferred,
total_latency_ms=latency_ms,
overhead_ms=overhead_delta_ms,
ttfb_ms=ttfb_for_record_ms,
@@ -9097,8 +9274,10 @@ class OpenAIHandlerMixin:
usage_cache_read_tokens,
usage_cache_write_tokens,
usage_uncached_tokens,
usage_cache_inferred,
) = _extract_responses_usage(event)
if usage_input_tokens or usage_output_tokens:
ws_cache_inferred = usage_cache_inferred
ws_input_tokens_total += usage_input_tokens
ws_output_tokens_total += usage_output_tokens
ws_cache_read_tokens_total += usage_cache_read_tokens
@@ -9492,6 +9671,7 @@ class OpenAIHandlerMixin:
fb_cache_read_tokens,
fb_cache_write_tokens,
fb_uncached_tokens,
ws_cache_inferred,
) = await self._ws_http_fallback(
websocket, body, first_msg_raw, upstream_headers, request_id
)
@@ -9623,6 +9803,7 @@ class OpenAIHandlerMixin:
cache_read_tokens=residual_cache_read_tokens,
cache_write_tokens=residual_cache_write_tokens,
uncached_input_tokens=residual_uncached_input_tokens,
cache_inferred=ws_cache_inferred,
total_latency_ms=ws_session_duration_ms,
overhead_ms=final_overhead_delta_ms,
ttfb_ms=final_ttfb_ms,
@@ -9769,7 +9950,7 @@ class OpenAIHandlerMixin:
first_msg_raw: str,
upstream_headers: dict[str, str],
request_id: str,
) -> tuple[int, int, int, int, int]:
) -> tuple[int, int, int, int, int, bool]:
"""Fall back to HTTP POST streaming when upstream WS fails.
Converts the WS ``response.create`` message to an HTTP POST to
@@ -9783,7 +9964,9 @@ class OpenAIHandlerMixin:
authoritative wire-token count; otherwise a fallback recorded
``input_tokens=0`` and savings percentages blew past 100 (#2957).
"""
fallback_usage = [0, 0, 0, 0, 0]
# Five summed counters, then whether the latest frame's write was
# inferred (see _openai_responses_cache_split).
fallback_usage: list[int] = [0, 0, 0, 0, 0, True]
def _accumulate_usage(data_str: str) -> None:
try:
@@ -9791,8 +9974,10 @@ class OpenAIHandlerMixin:
except (json.JSONDecodeError, TypeError):
return
if isinstance(event, dict) and event.get("type") == "response.completed":
for i, value in enumerate(_extract_responses_usage(event)):
usage = _extract_responses_usage(event)
for i, value in enumerate(usage[:5]):
fallback_usage[i] += value
fallback_usage[5] = usage[5]
# Route to correct endpoint based on auth mode
is_chatgpt_fallback = has_chatgpt_account_header(upstream_headers)
@@ -10451,6 +10636,11 @@ class OpenAIHandlerMixin:
if _turn is not None:
_turn.prepare(model_name=model_name, tags=tags, config=self.config)
# Whether the returned ``tokens_after`` was counted over the FINAL,
# post-hook messages (so it already includes any text a hook added).
# Set by whichever closure runs; read after the executor.
_after_counts_hook = [False]
def _run_stateless():
result = pipeline.apply(messages=messages, model=model, **pipeline_kwargs)
final = result.messages
@@ -10459,6 +10649,7 @@ class OpenAIHandlerMixin:
final = _turn.transform(final)
if _turn.folded_messages:
tokens_after = _turn.count_messages(final, tokens_after)
_after_counts_hook[0] = True
return (
result,
final,
@@ -10548,6 +10739,7 @@ class OpenAIHandlerMixin:
_tok = get_tokenizer(model_name)
raw_tokens_before = _tok.count_messages(messages)
final_tokens_after = _tok.count_messages(final)
_after_counts_hook[0] = True
except Exception as e:
# Fail-open, but LOUD: this fallback reverts to the
# pipeline's counts of the cache-swapped input, which
@@ -10598,7 +10790,19 @@ class OpenAIHandlerMixin:
ccr_hashes = _response_ccr_hashes(final_messages, result.markers_inserted)
tokens_saved = max(0, tokens_before - tokens_after)
# Tools and message text a turn hook added are sent too: they reduce
# the saving, and offset tools the hook removed (signed, clamped once).
_hook_tool_saved = 0
if _turn is not None:
tokens_after += max(0, int(getattr(_turn, "tool_growth_tokens", 0) or 0))
# Only a count of pre-hook messages lacks the text a hook added;
# a recount of the final messages (stateless fold, session) has it.
if not _after_counts_hook[0]:
tokens_after += max(0, int(getattr(_turn, "message_growth_tokens", 0) or 0))
_hook_tool_saved = int(getattr(_turn, "hook_tool_saved_tokens", 0) or 0)
tokens_saved = net_hook_tool_saving(
tokens_before - tokens_after, tags, _hook_tool_saved
)
latency_ms = (time.time() - start_time) * 1000
_transforms_applied = list(result.transforms_applied or ())
# The claimed turn adds its labels and response fields BEFORE the
+21 -2
View File
@@ -32,6 +32,8 @@ from headroom.proxy.token_counting import gemini_output_tokens
if TYPE_CHECKING:
from fastapi.responses import Response, StreamingResponse
from headroom.proxy.savings import ItemMeasure
import httpx
@@ -421,6 +423,13 @@ class StreamingMixin:
usage_found["cache_read_input_tokens"] = usage_int(
details.get("cached_tokens")
)
# Responses reports billed cache writes itself; the
# Anthropic-shape key routes them down the real-write
# branch instead of inferring them from uncached.
if details.get("cache_write_tokens") is not None:
usage_found["cache_creation_input_tokens"] = usage_int(
details.get("cache_write_tokens")
)
elif provider == "gemini":
usage_meta = _sse_dict(data.get("usageMetadata"))
@@ -808,6 +817,7 @@ class StreamingMixin:
# See ``conversation_savings``.
conversation_key: str | None = None,
conversation_tokens_saved: int | None = None,
savings_measure: ItemMeasure | None = None,
) -> None:
from headroom.proxy.outcome import RequestOutcome
@@ -1033,6 +1043,7 @@ class StreamingMixin:
waste_signals=waste_signals,
conversation_key=conversation_key,
conversation_tokens_saved=conversation_tokens_saved,
savings_measure=savings_measure,
)
await self._record_request_outcome(outcome)
@@ -1064,6 +1075,7 @@ class StreamingMixin:
session_key: str | None = None,
conversation_key: str | None = None,
conversation_tokens_saved: int | None = None,
savings_measure: ItemMeasure | None = None,
server_memory_tool_names: frozenset[str] | None = None,
client_beta: str | None = None,
) -> Response | StreamingResponse:
@@ -1111,6 +1123,7 @@ class StreamingMixin:
session_key=session_key,
conversation_key=conversation_key,
conversation_tokens_saved=conversation_tokens_saved,
savings_measure=savings_measure,
server_memory_tool_names=server_memory_tool_names,
client_beta=client_beta,
)
@@ -1145,6 +1158,7 @@ class StreamingMixin:
session_key: str,
conversation_key: str | None = None,
conversation_tokens_saved: int | None = None,
savings_measure: ItemMeasure | None = None,
server_memory_tool_names: frozenset[str] | None = None,
client_beta: str | None = None,
) -> Response | StreamingResponse:
@@ -1579,6 +1593,7 @@ class StreamingMixin:
status_code=upstream_response.status_code,
conversation_key=conversation_key,
conversation_tokens_saved=conversation_tokens_saved,
savings_measure=savings_measure,
)
self._cleanup_mid_turn_stream(session_key)
return Response(
@@ -1974,6 +1989,7 @@ class StreamingMixin:
),
conversation_key=conversation_key,
conversation_tokens_saved=conversation_tokens_saved,
savings_measure=savings_measure,
)
if supports_mid_turn_coalescing(client) and pending_messages:
pending_event = json.dumps(
@@ -2425,12 +2441,15 @@ class StreamingMixin:
# Bedrock/Anthropic shape when present. Fall back to
# inferring write count from total - read for OpenAI
# shape (which has no separate write counter).
cache_creation_input_tokens = stream_state.get("cache_creation_input_tokens") or 0
# None means "not reported"; an explicit 0 is a reported zero
# and must not fall through to the inferred branch.
reported_write = stream_state.get("cache_creation_input_tokens")
cache_creation_input_tokens = reported_write or 0
if upstream_input is None:
cache_write_tokens = 0
uncached_input_tokens = 0
cache_inferred = False
elif cache_creation_input_tokens > 0:
elif reported_write is not None:
cache_write_tokens = cache_creation_input_tokens
uncached_input_tokens = max(
upstream_input - cache_read_tokens - cache_write_tokens, 0
+74 -8
View File
@@ -112,6 +112,7 @@ from headroom.proxy.tool_injection_logging import (
)
from headroom.proxy.tool_injection_tracker import SessionToolTracker as _SessionToolTracker
from headroom.proxy.tool_name_policy import extract_tool_name
from headroom.proxy.turn_hooks import registered_turn_hooks
if TYPE_CHECKING:
import httpx
@@ -1095,6 +1096,7 @@ def relocate_system_messages_to_top_level(
family in model_id
for family in (
"claude-fable-5",
"claude-haiku-5",
"claude-mythos-5",
"claude-opus-4-8",
"claude-opus-5",
@@ -1880,6 +1882,54 @@ def _warn_once_if_owner_only_unsupported(log_path: Path) -> None:
)
def _headroom_log_level() -> int:
"""Level for the ``headroom`` logger and the proxy.log handler.
``HEADROOM_LOG_LEVEL=debug`` (or ``trace``) turns on Headroom's own debug
lines as well as uvicorn's; anything else keeps the INFO default, so the
default (``warning``, which only quiets uvicorn) never hides Headroom's
INFO events.
"""
raw = os.environ.get("HEADROOM_LOG_LEVEL", "").strip().lower()
return logging.DEBUG if raw in ("debug", "trace") else logging.INFO
class _HeadroomDebugStaysInProxyLog(logging.Filter):
"""Drop ``headroom.*`` DEBUG records on every handler except proxy.log.
Headroom's debug lines can carry request-derived data (error messages that
quote a request; with HEADROOM_DEBUG_DUMP=full, the tool output the router
compresses). proxy.log is owner-only; stdout, container logs
and wrap's stdio capture are not, so debug stays out of them, exactly as
when debug was unreachable.
"""
def filter(self, record: logging.LogRecord) -> bool:
if record.levelno >= logging.INFO:
return True
return record.name != "headroom" and not record.name.startswith("headroom.")
def _keep_headroom_debug_out_of_other_handlers() -> None:
"""Filter every handler that can see ``headroom.*`` records except proxy.log.
That is the root handlers, plus any handler already attached to ``headroom``
or a child logger (e.g. an extension's). Records stop at proxy.log only.
"""
loggers: list[logging.Logger] = [logging.getLogger(), logging.getLogger("headroom")]
loggers += [
candidate
for name, candidate in logging.Logger.manager.loggerDict.items()
if name.startswith("headroom.") and isinstance(candidate, logging.Logger)
]
for each in loggers:
for handler in each.handlers:
if handler.get_name() == _PROXY_LOG_HANDLER_NAME:
continue
if not any(isinstance(f, _HeadroomDebugStaysInProxyLog) for f in handler.filters):
handler.addFilter(_HeadroomDebugStaysInProxyLog())
def _setup_file_logging(
port: int | None = None,
*,
@@ -1926,7 +1976,8 @@ def _setup_file_logging(
# Keep root propagation enabled for container stdout/stderr while
# this handler writes the separate port/worker-specific proxy log.
headroom_logger = logging.getLogger("headroom")
headroom_logger.setLevel(logging.INFO)
level = _headroom_log_level()
headroom_logger.setLevel(level)
# Decide BEFORE constructing the handler: constructing a
# RotatingFileHandler opens (creates) the file, so building one only to
# discard it would leave an empty stray worker log and leak
@@ -1938,7 +1989,12 @@ def _setup_file_logging(
for h in headroom_logger.handlers
if isinstance(h, RotatingFileHandler) and h.name == _PROXY_LOG_HANDLER_NAME
]
if any(Path(h.baseFilename) == log_path for h in existing):
if level == logging.DEBUG:
_keep_headroom_debug_out_of_other_handlers()
reused = [h for h in existing if Path(h.baseFilename) == log_path]
if reused:
for h in reused:
h.setLevel(level)
return
handler = handler_cls(
log_path,
@@ -1947,7 +2003,7 @@ def _setup_file_logging(
encoding="utf-8",
)
handler.set_name(_PROXY_LOG_HANDLER_NAME)
handler.setLevel(logging.INFO)
handler.setLevel(level)
handler.setFormatter(
logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
)
@@ -1955,6 +2011,15 @@ def _setup_file_logging(
headroom_logger.removeHandler(stale)
stale.close()
headroom_logger.addHandler(handler)
if level == logging.DEBUG:
logger.warning(
"Headroom debug logging is on (HEADROOM_LOG_LEVEL). %s now records "
"request-derived data such as error messages that can quote requests; the "
"file is owner-only and debug lines stay out of stdout. Full tool-output "
"dumps also need HEADROOM_DEBUG_DUMP=full. Unset HEADROOM_LOG_LEVEL when "
"you finish diagnosing.",
log_path,
)
except OSError as exc:
# Non-fatal: can't write logs (read-only fs, permissions, etc.). Say so,
# or the missing proxy.log is the only clue. The OSError names the path.
@@ -4792,11 +4857,12 @@ def snapshot_original_messages(
Aliasing the live list is safe only while nothing between ingress and the
pipeline's own deepcopy can mutate it in place. A configured
``config.hooks`` (``pre_compress`` and friends receive the live list) or an
enabled pipeline extension can, so in that case the snapshot is an
independently owned deep copy; with neither configured the alias is kept
and costs nothing.
``config.hooks`` (``pre_compress`` and friends receive the live list), an
enabled pipeline extension or a registered turn hook (skill search folds
message text in place) can, so in that case the snapshot is an
independently owned deep copy; with none of them the alias is kept and
costs nothing.
"""
if hooks is not None or bool(getattr(extensions, "enabled", False)):
if hooks is not None or bool(getattr(extensions, "enabled", False)) or registered_turn_hooks():
return copy.deepcopy(messages)
return messages
+14
View File
@@ -36,3 +36,17 @@ def is_token_mode(mode: str | None) -> bool:
def is_cache_mode(mode: str | None) -> bool:
"""Return True when mode resolves to cache mode."""
return normalize_proxy_mode(mode) == PROXY_MODE_CACHE
def read_maturation_inert_reason(
mode: str | None, *, quiesce_turns: int, max_hold_turns: int
) -> str | None:
"""Why read maturation can never fire under ``mode``, else None.
Cache mode freezes every turn but the latest, and maturation skips frozen
messages. A Read in the latest turn has had no quiet turns yet, so it is
held unless a threshold is 0; by the time it could quiesce it is frozen.
"""
if is_cache_mode(mode) and quiesce_turns > 0 and max_hold_turns > 0:
return "cache mode freezes a Read before it can quiesce"
return None
+55 -38
View File
@@ -33,6 +33,7 @@ from typing import Any
from headroom.log_safety import describe_exception
from headroom.proxy.conversation_savings import get_conversation_savings
from headroom.proxy.savings import ItemMeasure, get_item_ledger
from headroom.proxy.tool_schema_savings_policy import (
headline_tokens_saved,
tool_schema_saved_from_tags,
@@ -204,6 +205,11 @@ class RequestOutcome:
# path, where the outcome carries a per-turn delta.
conversation_key: str | None = None
conversation_tokens_saved: int | None = None
# savings_measure: the request's per-item original/sent counts against the
# conversation's previous request (``headroom.proxy.savings``), from
# which the per-request savings record is priced. None on paths that
# do not measure items yet.
savings_measure: ItemMeasure | None = None
transforms_applied: tuple[str, ...] = ()
waste_signals: dict[str, int] | None = None
num_messages: int = 0
@@ -339,6 +345,7 @@ class RequestOutcome:
conversation_key: str | None = None,
conversation_tokens_saved: int | None = None,
provider_input_tokens: int = 0,
savings_measure: ItemMeasure | None = None,
) -> RequestOutcome:
"""Construct an outcome from the locals available at streaming
finalize. Three streaming finalizers
@@ -414,6 +421,7 @@ class RequestOutcome:
tokens_saved=tokens_saved,
conversation_key=conversation_key,
conversation_tokens_saved=conversation_tokens_saved,
savings_measure=savings_measure,
attempted_input_tokens=optimized_tokens + tokens_saved,
status_code=status_code,
cache_read_tokens=cache_read_tokens,
@@ -539,6 +547,10 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
# beacon must never add latency to, or take down, the request path.
record_outcome(outcome)
if outcome.savings_measure is not None:
# Only a request the provider served becomes the next one's baseline.
get_item_ledger().settle(outcome.savings_measure, succeeded=outcome.status_code < 400)
# A rejected turn must not feed the savings/cost/log success stats; that
# would let a request the provider never billed inflate the save-rate.
# Record it under the counter that names what happened, and stop.
@@ -571,44 +583,6 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
await handler.metrics.record_failed(provider=outcome.provider)
return
# Outcome stage: hand the meter's reading to any pipeline extension that
# adapts to it — a ceiling that was hit, an effort setting that did or did
# not pay off. The snapshot is frozen, so an extension can learn from the
# measurement without being able to rewrite it: extensions declare what
# they did, the core records what happened, and attribution is the core's
# arithmetic over both.
#
# Best-effort and last in line: a handler without a pipeline manager, or an
# extension that raises, must not affect the response or the stats below.
_pipeline = getattr(handler, "pipeline_extensions", None)
if _pipeline is not None and getattr(_pipeline, "enabled", False):
try:
from headroom.pipeline import OutcomeSnapshot, PipelineStage
_pipeline.emit(
PipelineStage.OUTCOME_OBSERVED,
operation="proxy.outcome",
request_id=outcome.request_id,
provider=outcome.provider,
model=outcome.model,
outcome=OutcomeSnapshot(
request_id=outcome.request_id,
provider=outcome.provider,
model=outcome.model,
output_tokens=outcome.output_tokens,
thinking_tokens=outcome.thinking_tokens,
thinking_inferred=outcome.thinking_inferred,
stop_reason=outcome.stop_reason,
input_tokens=outcome.provider_input_tokens or outcome.optimized_tokens,
cache_read_tokens=outcome.cache_read_tokens,
cache_write_tokens=outcome.cache_write_tokens,
turn_index=outcome.turn_index,
transforms_applied=tuple(str(t) for t in (outcome.transforms_applied or ())),
),
)
except Exception: # noqa: BLE001 - telemetry must never break a response
logger.debug("OUTCOME_OBSERVED emit failed", exc_info=True)
# Output-shaping savings ledger (counterfactual estimator). The shaper
# tags each request's (arm, stratum) onto ``transforms_applied``; feed the
# observed output tokens to the recorder so it can produce an honest
@@ -653,6 +627,49 @@ async def emit_request_outcome(handler: Any, outcome: RequestOutcome) -> None:
if novel_tokens_saved is None:
novel_tokens_saved = outcome.tokens_saved
# Outcome stage: hand the meter's reading to any pipeline extension that
# adapts to it — a ceiling that was hit, an effort setting that did or did
# not pay off. The snapshot is frozen, so an extension can learn from the
# measurement without being able to rewrite it: extensions declare what
# they did, the core records what happened, and attribution is the core's
# arithmetic over both.
#
# Emitted after the novel share is known, so an extension reads the same
# per-request savings the running totals book instead of parsing PERF lines.
#
# Best-effort: a handler without a pipeline manager, or an extension that
# raises, must not affect the response or the stats below.
_pipeline = getattr(handler, "pipeline_extensions", None)
if _pipeline is not None and getattr(_pipeline, "enabled", False):
try:
from headroom.pipeline import OutcomeSnapshot, PipelineStage
_pipeline.emit(
PipelineStage.OUTCOME_OBSERVED,
operation="proxy.outcome",
request_id=outcome.request_id,
provider=outcome.provider,
model=outcome.model,
outcome=OutcomeSnapshot(
request_id=outcome.request_id,
provider=outcome.provider,
model=outcome.model,
output_tokens=outcome.output_tokens,
thinking_tokens=outcome.thinking_tokens,
thinking_inferred=outcome.thinking_inferred,
stop_reason=outcome.stop_reason,
input_tokens=outcome.provider_input_tokens or outcome.optimized_tokens,
cache_read_tokens=outcome.cache_read_tokens,
cache_write_tokens=outcome.cache_write_tokens,
turn_index=outcome.turn_index,
transforms_applied=tuple(str(t) for t in (outcome.transforms_applied or ())),
tokens_saved=outcome.tokens_saved,
novel_tokens_saved=novel_tokens_saved,
),
)
except Exception: # noqa: BLE001 - telemetry must never break a response
logger.debug("OUTCOME_OBSERVED emit failed", exc_info=True)
# Tool-schema savings (deferral + turn-hook tool shrink) live in per-request
# tags and never move tok_before/after; aggregate them into Metrics so the
# session summary / cost summary / all-layers total can surface the layer.
+6
View File
@@ -84,6 +84,12 @@ RUNTIME_ENV_KNOBS: tuple[Knob, ...] = (
"int",
"Max on-disk file size (bytes) the disk-verify fallback will read.",
),
Knob(
"HEADROOM_BUFFERED_UPSTREAM_STREAM",
"bool",
"Send buffered CCR requests upstream as stream:true and fold the reply "
"(default on; 0 sends stream:false).",
),
)
_KNOBS_BY_ENV: dict[str, Knob] = {k.env: k for k in RUNTIME_ENV_KNOBS}
+707
View File
@@ -0,0 +1,707 @@
"""One per-request savings record: counterfactual cost minus actual cost.
Every savings surface (/stats, the durable ledger, persistent savings, the
dashboard, the PERF line) is meant to derive from the :class:`SavingsRecord`
this module computes, so no surface prices savings its own way.
Two rulers meet here and are only ever combined through RATIOS:
* Headroom's tokenizer gives per-item counts of the request as the client sent
it (ORIGINAL) and as Headroom forwarded it (SENT). Both are counted with the
same tokenizer, so a tokenizer bias cancels in their difference.
* The provider's usage block gives exact billed totals (uncached, cache read,
cache write) but no per-item detail.
``k = billed / sent`` converts Headroom units into provider units, calibrated
on this request's own content. The counterfactual cache behaviour mirrors the
actual request's: removed tokens in items the previous request already carried
would have been cache reads to the extent the actual request hit its cache
(``warm``); removed tokens in new items would have been misses, written to
cache in the proportion the actual request wrote (``w``). Old items whose sent
copy Headroom changed since the previous request (``bust``) are misses that
Headroom caused, charged back against the saving.
Output tokens are identical in the counterfactual by construction; output
shaping is measured separately against its holdout and stays out of this
number.
``headroom.pricing`` is imported inside functions, as elsewhere on the proxy
path: its package ``__init__`` pulls in litellm (~4s), which must not land on
proxy startup.
"""
from __future__ import annotations
import hashlib
import json
import logging
import threading
from collections import OrderedDict
from collections.abc import Callable, Sequence
from dataclasses import dataclass, field, replace
from typing import TYPE_CHECKING, Any
from headroom.log_safety import describe_exception, safe_id
if TYPE_CHECKING:
from headroom.pricing.counterfactual import CacheMix, CacheRates
logger = logging.getLogger(__name__)
#: OpenAI caches prompts of at least 1024 tokens, in 128-token blocks.
OPENAI_MIN_CACHEABLE_TOKENS = 1024
OPENAI_CACHE_BLOCK_TOKENS = 128
#: Used when the catalog has no ``prompt_cache_min_tokens`` for a model.
DEFAULT_MIN_CACHEABLE_TOKENS = 1024
@dataclass(frozen=True, slots=True)
class ItemCounts:
"""One request item (tools block, system, or one input/message item).
Hashes identify the item's content; counts are in Headroom tokens. Lists of
items are aligned by position between ORIGINAL and SENT, so an item
Headroom dropped entirely keeps its slot with ``sent_hash=""`` and
``sent_tokens=0``. Tool-schema deferral is removal inside the tools item.
"""
original_hash: str
original_tokens: int
sent_hash: str
sent_tokens: int
@dataclass(frozen=True)
class ItemMeasure:
"""The Headroom-unit quantities the savings formula needs."""
#: ``S``: tokens of the whole sent body.
sent_tokens: int
#: ``R_old``: removed tokens (signed: an item Headroom grew counts against
#: it) in items within the longest prefix of the ORIGINAL body identical to
#: the previous ORIGINAL body.
removed_old: int
#: ``R_new``: removed tokens in every other item, signed likewise.
removed_new: int
#: ``P_S``: tokens of the longest prefix of the SENT body identical to the
#: previous SENT body.
sent_shared_prefix: int
#: Sent tokens of old items that fell outside the sent shared prefix: cache
#: misses caused only by Headroom changing what it had sent before.
bust: int
#: False when the old/new split is approximate (the totals stay exact):
#: Headroom changed the item count and the original/sent pairing had to be
#: approximated, or the baseline was lost (``baseline_lost``).
aligned: bool = True
#: True when the ledger lost what this conversation last sent (its
#: baseline or an in-flight request was evicted under the budget, or its
#: baseline may be truncated), so ``removed_new`` may hold old items. Such
#: a measure is also ``aligned=False``. Its record prices the new removal
#: at the cache-read rate, the lowest any input token costs, so the lost
#: knowledge can only understate the saving. A conversation's first
#: request is not lost: nothing was sent before, so everything is new.
baseline_lost: bool = False
#: Tokens Headroom added to new items (the negative part of
#: ``removed_new``), so the read-rate floor covers only what it removed.
grown_new: int = 0
#: Which measured request this is, for :meth:`ItemLedger.settle`.
ticket: int = field(default=0, compare=False)
@property
def removed(self) -> int:
return self.removed_old + self.removed_new
@dataclass(frozen=True)
class SavingsRecord:
"""What one request saved, in dollars and in both token rulers."""
saved_usd: float
actual_input_cost_usd: float
counterfactual_input_cost_usd: float
#: Removed tokens in Headroom units (``R``).
removed_tokens: int
#: The same removal in provider units (``k * R``).
saved_tokens: float
k: float
warm: float
write_share: float
#: True when usage was missing (aborted stream) or summed over server-side
#: iterations, so the cache split could not be read from this request.
estimated: bool = False
#: False when the catalog has no price for the model.
priced: bool = True
def _common_prefix_len(a: Sequence[str], b: Sequence[str]) -> int:
n = 0
for x, y in zip(a, b):
if x != y:
break
n += 1
return n
def measure_items(
items: Sequence[ItemCounts],
previous: Sequence[ItemCounts] | None,
) -> ItemMeasure:
"""Split one request's removal into old/new items against the previous request.
``previous`` is the same conversation's previous request, or ``None`` on its
first request, where everything is new and nothing is shared.
"""
n_old = _common_prefix_len(
[i.original_hash for i in items], [i.original_hash for i in previous or ()]
)
n_sent_shared = _common_prefix_len(
[i.sent_hash for i in items], [i.sent_hash for i in previous or ()]
)
removed = [i.original_tokens - i.sent_tokens for i in items]
sent = [max(0, i.sent_tokens) for i in items]
return ItemMeasure(
sent_tokens=sum(sent),
removed_old=sum(removed[:n_old]),
removed_new=sum(removed[n_old:]),
sent_shared_prefix=sum(sent[:n_sent_shared]),
bust=sum(sent[n_sent_shared:n_old]),
grown_new=-sum(r for r in removed[n_old:] if r < 0),
)
def _dump(value: Any) -> str:
return json.dumps(value, ensure_ascii=False, separators=(",", ":"), default=str)
#: One request item as (identity text, billable text): the identity is hashed
#: to tell items apart, the billable text is what gets tokenized.
Item = tuple[str, str]
def _item(value: Any) -> Item:
identity = _dump(value)
if (
isinstance(value, dict)
and value.get("type") == "reasoning"
and "encrypted_content" in value
):
# The provider bills the reasoning it decrypts, not the ciphertext,
# which would otherwise be most of a long Codex transcript's count.
billable = _dump({k: v for k, v in value.items() if k != "encrypted_content"})
return identity, billable
return identity, identity
def responses_items(body: dict[str, Any]) -> list[Item]:
"""A ``/v1/responses`` body as items in prompt order.
Tools, then instructions, then each ``input`` item: the order the provider
caches the prompt in, which is what the shared-prefix comparison needs.
Codex's ``additional_tools`` input items stay where the client put them.
"""
items = [_item(body.get("tools") or []), _item(body.get("instructions") or "")]
# OpenAI-compatible upstreams accept ``messages`` in place of ``input``.
raw = body.get("input") if body.get("input") is not None else body.get("messages")
if isinstance(raw, list):
items.extend(_item(item) for item in raw)
elif raw:
items.append(_item(raw))
return items
def _digest(text: str) -> str:
return hashlib.blake2b(text.encode("utf-8", errors="replace"), digest_size=8).hexdigest()
#: Items kept across all conversations' baselines and requests awaiting their
#: outcome, combined. A long Codex session carries 1000+ items; bounding items,
#: not conversations, bounds memory: up to twice this while one conversation's
#: baseline and its in-flight request exceed it (see :class:`ItemLedger`).
MAX_STORED_ITEMS = 100_000
#: Conversations remembered as having lost their baseline, a memory bound
#: (one short key each). Past it the ledger can no longer tell a first request
#: from a lost one and treats every request without a baseline as lost: priced
#: at the cache-read floor, which can understate a saving but never overstate it.
MAX_LOST_KEYS = 100_000
def _align(
original: list[tuple[str, int]],
sent: list[tuple[str, int]],
previous: Sequence[ItemCounts] | None,
) -> tuple[list[ItemCounts], bool]:
"""Pair original and sent items, and say whether the pairing is exact.
Same item count: by position (compression rewrites items in place). A
different count (a hook folded or dropped items, or Headroom inserted
some): identical items at either end pair up; the unmatched originals in
between are removed, and the unmatched sent items in between are folded
into the first of their slots. The totals stay exact either way; only
which items count as old is approximate, hence ``aligned=False``. An item
compressed in place still pairs at the head when the previous request
paired the same original with the same sent copy at that position.
Equal counts pair by position even if a fold and an insert cancel out.
"""
if len(original) == len(sent):
return [ItemCounts(oh, ot, sh, st) for (oh, ot), (sh, st) in zip(original, sent)], True
limit = min(len(original), len(sent))
prev = previous or ()
def same_as_before(i: int) -> bool:
return (
i < len(prev)
and original[i][0] == prev[i].original_hash
and sent[i][0] == prev[i].sent_hash
)
head = 0
while head < limit and (original[head][0] == sent[head][0] or same_as_before(head)):
head += 1
tail = 0
while (
tail < limit - head
and original[len(original) - 1 - tail][0] == sent[len(sent) - 1 - tail][0]
):
tail += 1
mid_original = original[head : len(original) - tail]
mid_sent = sent[head : len(sent) - tail]
if len(mid_sent) == 1:
folded_hash = mid_sent[0][0]
else:
folded_hash = _digest("\x00".join(h for h, _ in mid_sent)) if mid_sent else ""
folded_tokens = sum(t for _, t in mid_sent)
middle = [ItemCounts(oh, ot, "", 0) for oh, ot in mid_original] or [ItemCounts("", 0, "", 0)]
middle[0] = ItemCounts(
middle[0].original_hash, middle[0].original_tokens, folded_hash, folded_tokens
)
pairs = [ItemCounts(oh, ot, sh, st) for (oh, ot), (sh, st) in zip(original[:head], sent[:head])]
pairs += middle
pairs += [ItemCounts(h, t, h, t) for h, t in original[len(original) - tail :]]
return pairs, False
class ItemLedger:
"""The previous request of each conversation, for the old/new item split.
One instance per process. A request is measured against the conversation's
last SUCCESSFUL request and becomes the baseline only once its own outcome
succeeds (:meth:`settle`): a failed call never reached the provider's cache.
Each measure carries a ticket, issued in measure order, so a slow earlier
turn settling late cannot replace a newer turn's baseline. Items re-sent
from the baseline reuse its token counts, so a long transcript is
tokenized once rather than every turn.
Baselines and requests awaiting their outcome share one budget,
:data:`MAX_STORED_ITEMS`. Past it, whichever is least recent goes first,
by ticket: a pending request by its own ticket (its slot is reserved when
the ticket is issued, so a slow measure keeps its place), a baseline by
the last ticket that used it. Settling counts as a use. A request being
admitted never evicts its own conversation's baseline: that baseline is
replaced only when a newer request for the conversation succeeds. When
only that baseline and one pending request are left, both are kept, even
past the budget, so a conversation larger than half the budget still
advances; memory then peaks at twice :data:`MAX_STORED_ITEMS` items.
A request is kept only up to its first :data:`MAX_STORED_ITEMS` items: the
comparison is a prefix, so the next request still gets the shared-prefix
credit for them.
Whatever is evicted, its conversation is remembered as lost, so its next
request is marked ``baseline_lost`` (and ``aligned=False``): its record
prices the new removal at the cache-read floor instead of as new, at the
miss rate. So is a request measured against a baseline of exactly
:data:`MAX_STORED_ITEMS` items, which may be truncated. A conversation's
first request is new, not lost. The memory of losses is bounded by
:data:`MAX_LOST_KEYS`; past it, every request without a baseline is
treated as lost, and a forgotten loss's stale baseline is dropped with it.
"""
def __init__(self) -> None:
self._lock = threading.Lock()
# key -> (settled ticket, items, last ticket that used it), oldest use first.
self._previous: OrderedDict[str, tuple[int, list[ItemCounts], int]] = OrderedDict()
# ticket -> (key, items), in ticket order.
self._pending: OrderedDict[int, tuple[str, list[ItemCounts]]] = OrderedDict()
# key -> newest ticket whose items were evicted, oldest loss first.
self._lost: OrderedDict[str, int] = OrderedDict()
# True once a loss was forgotten: a missing baseline may then be a lost one.
self._lost_overflowed = False
self._stored = 0
self._pending_items = 0
self._seq = 0
def measure(
self,
key: str,
original: Sequence[Item],
sent: Sequence[Item],
count: Callable[[str], int],
) -> ItemMeasure:
"""Measure one request against ``key``'s baseline; settle it later."""
with self._lock:
self._seq += 1
seq = self._seq
entry = self._previous.get(key)
if entry is not None:
self._previous[key] = (entry[0], entry[1], seq)
self._previous.move_to_end(key)
lost = key in self._lost or (entry is None and self._lost_overflowed)
self._pending[seq] = (key, [])
previous = entry[1] if entry else None
known: dict[str, int] = {}
for item in previous or ():
known[item.original_hash] = item.original_tokens
known[item.sent_hash] = item.sent_tokens
def counted(items: Sequence[Item]) -> list[tuple[str, int]]:
out = []
for identity, billable in items:
digest = _digest(identity)
tokens = known.get(digest)
if tokens is None:
tokens = known[digest] = int(count(billable))
out.append((digest, tokens))
return out
try:
items, aligned = _align(counted(original), counted(sent), previous)
except BaseException:
# The caller logs and never settles: release the reserved slot.
with self._lock:
self._pending.pop(seq, None)
raise
if previous is not None and len(previous) == MAX_STORED_ITEMS:
# Possibly a truncated baseline: items past it may be old.
lost = True
with self._lock:
if seq in self._pending: # not already evicted while counting
kept = items[:MAX_STORED_ITEMS]
self._pending[seq] = (key, kept)
self._pending_items += len(kept)
self._evict(key)
return replace(
measure_items(items, previous),
aligned=aligned and not lost,
baseline_lost=lost,
ticket=seq,
)
def settle(self, measure: ItemMeasure, *, succeeded: bool) -> None:
"""Make a measured request its conversation's baseline if it succeeded."""
seq = measure.ticket
with self._lock:
pending = self._pending.pop(seq, None)
if pending is None:
return
key, items = pending
self._pending_items -= len(items)
if not succeeded:
return
current = self._previous.get(key)
if current is not None and current[0] > seq:
return
# Moving items from pending to stored never grows the total.
self._stored -= len(current[1]) if current else 0
self._previous[key] = (seq, items, self._seq)
self._previous.move_to_end(key)
self._stored += len(items)
if self._lost.get(key, seq) < seq:
# Newer than everything evicted: the baseline is whole again.
del self._lost[key]
def _evict(self, admitting: str) -> None:
"""Forget the least recent entries until the combined budget holds.
Called with the lock held, right after admitting a request for
``admitting``, whose baseline is never a candidate. Each pass removes
one entry until only that baseline and one pending request are left:
each holds at most :data:`MAX_STORED_ITEMS` items, so they stay.
"""
while self._stored + self._pending_items > MAX_STORED_ITEMS:
oldest_ticket = next(iter(self._pending), None)
oldest_key = next((k for k in self._previous if k != admitting), None)
if oldest_key is None and len(self._pending) <= 1:
return
# On a tie the baseline goes: the request that used it is newer.
if oldest_key is not None and (
oldest_ticket is None or self._previous[oldest_key][2] <= oldest_ticket
):
settled, evicted, _ = self._previous.pop(oldest_key)
self._stored -= len(evicted)
self._mark_lost(oldest_key, settled)
else:
ticket, (key, dropped) = self._pending.popitem(last=False)
self._pending_items -= len(dropped)
self._mark_lost(key, ticket)
def _mark_lost(self, key: str, ticket: int) -> None:
"""Remember that ``key``'s items up to ``ticket`` were evicted (lock held)."""
self._lost[key] = max(ticket, self._lost.get(key, 0))
self._lost.move_to_end(key)
while len(self._lost) > MAX_LOST_KEYS:
forgotten, _ = self._lost.popitem(last=False)
if not self._lost_overflowed:
self._lost_overflowed = True
logger.info(
"savings: lost-baseline memory full (MAX_LOST_KEYS=%d); requests "
"without a baseline now price at the cache-read floor",
MAX_LOST_KEYS,
)
# Unmarked, a stale baseline would price old items as new: drop it,
# so the conversation counts as lost under the overflow rule.
stale = self._previous.pop(forgotten, None)
if stale is not None:
self._stored -= len(stale[1])
_ledger = ItemLedger()
def get_item_ledger() -> ItemLedger:
"""Process-wide ledger: one conversation spans many requests and handlers."""
return _ledger
def prefix_key(conversation: str | None, model: str, original: Sequence[Item]) -> str:
"""Which previous request a request is compared against.
The conversation's explicit identity (``savings_conversation_key``) plus
the tools and instructions: a side request in the same session (compaction,
review) carries a different prefix and must not replace the conversation's
previous request. Without an identity, the model plus the first input item
stand in. Requests that collide on the key overwrite each other's previous
request, shortening the shared prefix: more of the removal is then priced
as new, at the miss rate, which overstates the saving.
"""
head = "\x00".join(identity for identity, _ in original[:2])
if conversation:
# The model too: the provider's cache is per model, and so are counts.
return _digest("\x00".join([conversation, model, head]))
return _digest("\x00".join([model, *(identity for identity, _ in original[:3])]))
def _input_cost(
rates: CacheRates, *, uncached: float, read: float, write_5m: float, write_1h: float
) -> float:
return (
uncached * rates.uncached
+ read * rates.read
+ write_5m * rates.write_5m
+ write_1h * rates.write_1h
)
def _min_cacheable_tokens(model: str, provider: str | None) -> int:
if provider == "openai":
return OPENAI_MIN_CACHEABLE_TOKENS
from headroom.pricing.counterfactual import catalog_min_cacheable_tokens
return catalog_min_cacheable_tokens(model) or DEFAULT_MIN_CACHEABLE_TOKENS
def _unpriced(measure: ItemMeasure, *, k: float, estimated: bool) -> SavingsRecord:
return SavingsRecord(
saved_usd=0.0,
actual_input_cost_usd=0.0,
counterfactual_input_cost_usd=0.0,
removed_tokens=measure.removed,
saved_tokens=k * measure.removed,
k=k,
warm=0.0,
write_share=0.0,
estimated=estimated,
priced=False,
)
def compute_savings_record(
measure: ItemMeasure,
usage: CacheMix | None,
*,
model: str,
provider: str | None = None,
estimated: bool = False,
) -> SavingsRecord:
"""Price one request's removal as ``counterfactual_cost - actual_cost``.
``usage`` is the provider's billed input as a :class:`CacheMix` (normalized
here, so an inferred OpenAI write counts as the uncached slice it is).
``None`` or an empty mix means the provider reported nothing (an aborted
stream); the record then prices at list with ``k = 1`` and is marked
``estimated``.
For a request the provider ran as several server-side iterations, pass the
FIRST iteration's usage when it is available (``estimated=False``); the
later iterations are a cost the caller books separately. Pass the summed
usage with ``estimated=True`` only when per-iteration usage is not
available: the sum describes more prompts than the one sent body, so
``k`` is not calibrated from it (``k = 1``) and only its cache ratios are
used. ``provider`` must be given for OpenAI's 128-token cache blocks to
apply.
Never raises: a savings figure must not be able to fail a request.
"""
try:
record = _compute(measure, usage, model=model, provider=provider, estimated=estimated)
# An approximate item pairing leaves the totals exact but not the
# old/new split the price depends on.
return record if measure.aligned else replace(record, estimated=True)
except Exception as exc: # noqa: BLE001 - pricing must never fail a request
logger.debug(
"savings: record failed for model=%s: %s", safe_id(model), describe_exception(exc)
)
return _unpriced(measure, k=1.0, estimated=True)
def _compute(
measure: ItemMeasure,
usage: CacheMix | None,
*,
model: str,
provider: str | None,
estimated: bool,
) -> SavingsRecord:
from headroom.pricing.counterfactual import LONG_CONTEXT_THRESHOLD_TOKENS, resolve_rates
def rates_for(billed: float, *, for_billing: bool = False) -> CacheRates | None:
return resolve_rates(
model,
long_context=billed > LONG_CONTEXT_THRESHOLD_TOKENS,
provider=provider,
for_billing=for_billing,
)
removed = measure.removed
# With the baseline lost, the new items may be old ones the provider had
# cached. Their removal prices at the read rate, the floor of any input
# token: the cache ratio and minimum below describe a prefix the ledger no
# longer knows. Tokens Headroom added to new items stay at the miss rate.
floor = measure.removed_new + measure.grown_new if measure.baseline_lost else 0
mix = usage.normalized() if usage is not None else None
if mix is None or mix.billed <= 0:
actual_rates = rates_for(measure.sent_tokens)
cf_rates = rates_for(measure.sent_tokens + removed)
if actual_rates is None or cf_rates is None:
return _unpriced(measure, k=1.0, estimated=True)
actual = measure.sent_tokens * actual_rates.uncached
counterfactual = (
measure.sent_tokens + removed - floor
) * cf_rates.uncached + floor * cf_rates.read
return SavingsRecord(
saved_usd=counterfactual - actual,
actual_input_cost_usd=actual,
counterfactual_input_cost_usd=counterfactual,
removed_tokens=removed,
saved_tokens=float(removed),
k=1.0,
warm=0.0,
write_share=0.0,
estimated=True,
)
billed = mix.billed
writes = mix.write_5m + mix.write_1h
k = billed / measure.sent_tokens if measure.sent_tokens > 0 and not estimated else 1.0
hit = mix.read / billed
sigma = measure.sent_shared_prefix / measure.sent_tokens if measure.sent_tokens > 0 else 0.0
warm = min(1.0, hit / sigma) if sigma > 0 else 0.0
misses = mix.uncached + writes
w = writes / misses if misses > 0 else 0.0
# The counterfactual must obey its own cache minimum. The catalog's
# minimum is used unless this request was demonstrably cached or written
# below it; then the catalog is wrong and no minimum is applied, the
# direction that cannot inflate the saving.
min_cacheable = _min_cacheable_tokens(model, provider)
proven = mix.read if mix.read > 0 else (billed if writes > 0 else min_cacheable)
threshold = min_cacheable if proven >= min_cacheable else 0
# Removed or busted old tokens could only have been reads if the
# counterfactual's old prefix was itself cacheable.
raw_warm = warm
if k * (measure.sent_shared_prefix + measure.removed_old) < threshold:
warm = 0.0
# The counterfactual's buckets are built whole, not as deltas clamped onto
# the actual ones: a counterfactual smaller than the request (an old item
# Headroom grew) must not inherit reads or writes it was too small to make.
# Its reads are the actual reads plus the removed/busted old tokens that
# would have hit, minus the reads a grown old item contributed (those go
# whatever the prefix size), never more than its whole billed input, and
# none below its cache minimum. ``cf_billed`` is ``k * original`` when k is
# calibrated; the clamp matters only for summed (estimated) usage.
cf_billed = max(0.0, billed + k * removed)
gained = k * (max(0, measure.removed_old) + measure.bust) * warm
lost = k * min(0, measure.removed_old) * raw_warm
cf_read = min(max(0.0, mix.read + gained + lost), cf_billed)
if cf_read < threshold:
# Never fires when nothing changed: the actual reads are 0 or proven
# at least the threshold.
cf_read = 0.0
if provider == "openai" and cf_read != mix.read:
# Hits come in whole 128-token blocks: round down, but a counterfactual
# that adds reads keeps at least the actual ones. The ``!=`` keeps an
# unchanged request exactly at the actual reads.
blocks = (cf_read // OPENAI_CACHE_BLOCK_TOKENS) * OPENAI_CACHE_BLOCK_TOKENS
cf_read = max(blocks, mix.read) if cf_read > mix.read else blocks
if floor > 0:
cf_read = min(cf_read + k * floor, cf_billed)
# Everything else missed, written in the proportion the request wrote,
# unless the counterfactual is smaller than anything shown cacheable: a
# write it could not make would inflate the saving.
cf_miss = cf_billed - cf_read
cf_write = cf_miss * w if cf_billed >= min(min_cacheable, proven) else 0.0
w5_share = mix.write_5m / writes if writes > 0 else 1.0
cf_buckets = {
"uncached": cf_miss - cf_write,
"read": cf_read,
"write_5m": cf_write * w5_share,
"write_1h": cf_write * (1.0 - w5_share),
}
actual_buckets = {
"uncached": float(mix.uncached),
"read": float(mix.read),
"write_5m": float(mix.write_5m),
"write_1h": float(mix.write_1h),
}
# Tokens the request was billed for price at billing rates on both sides
# (the counterfactual's at its own context tier); only the tokens a
# counterfactual bucket holds beyond the actual one price at the
# savings-estimate rates. Every priced quantity is nonnegative.
actual_rates = rates_for(billed, for_billing=True)
cf_billing_rates = rates_for(cf_billed, for_billing=True)
cf_rates = rates_for(cf_billed)
if actual_rates is None or cf_billing_rates is None or cf_rates is None:
return _unpriced(measure, k=k, estimated=estimated)
actual = _input_cost(actual_rates, **actual_buckets)
counterfactual = _input_cost(
cf_billing_rates, **{b: min(n, actual_buckets[b]) for b, n in cf_buckets.items()}
) + _input_cost(cf_rates, **{b: max(0.0, n - actual_buckets[b]) for b, n in cf_buckets.items()})
return SavingsRecord(
saved_usd=counterfactual - actual,
actual_input_cost_usd=actual,
counterfactual_input_cost_usd=counterfactual,
removed_tokens=removed,
saved_tokens=k * removed,
k=k,
warm=warm,
write_share=w,
estimated=estimated,
)
__all__ = [
"Item",
"ItemCounts",
"ItemLedger",
"ItemMeasure",
"SavingsRecord",
"compute_savings_record",
"get_item_ledger",
"measure_items",
"prefix_key",
"responses_items",
]
+69 -5
View File
@@ -164,6 +164,7 @@ from headroom.proxy.modes import (
PROXY_MODE_TOKEN,
is_token_mode,
normalize_proxy_mode,
read_maturation_inert_reason,
)
from headroom.proxy.orphan_watchdog import (
orphan_grace_seconds,
@@ -202,7 +203,7 @@ from headroom.subscription.tracker import (
get_subscription_tracker,
)
from headroom.telemetry import get_telemetry_collector
from headroom.telemetry.beacon import is_beacon_enabled, is_telemetry_enabled
from headroom.telemetry.beacon import beacon_off_reason, is_beacon_enabled, is_telemetry_enabled
from headroom.telemetry.toin import get_toin
from headroom.transforms import (
CacheAligner,
@@ -2038,7 +2039,11 @@ class HeadroomProxy(
backend,
)
threading.Thread(target=_warm, name="kompress-warmup", daemon=True).start()
from headroom.transforms.kompress_compressor import start_kompress_warmup_thread
# Registered as the model's loader, so a request during the warm-up
# doesn't start a second load thread.
start_kompress_warmup_thread(compressor.config.model_id, _warm)
return True
async def startup(self):
@@ -2093,6 +2098,25 @@ class HeadroomProxy(
if self.config.mode == PROXY_MODE_CACHE:
logger.info(" Prefix freeze: strict (all prior turns immutable)")
logger.info(" Mutations: latest turn only")
if self.config.read_maturation:
_inert = read_maturation_inert_reason(
self.config.mode,
quiesce_turns=self.config.read_maturation_quiesce_turns,
max_hold_turns=self.config.read_maturation_max_hold_turns,
)
if _inert:
logger.warning(
"Read maturation: INERT (%s); use --mode token or disable read_maturation",
_inert,
)
else:
logger.info(
"Read maturation: ENABLED (quiesce_turns=%d max_hold_turns=%d "
"min_size_bytes=%d)",
self.config.read_maturation_quiesce_turns,
self.config.read_maturation_max_hold_turns,
self.config.read_maturation_min_size_bytes,
)
# Effective compression posture, resolved (not merely requested). The
# savings profile reaches the router through two paths — the config
# object and the seeded process env — and `setdefault` semantics mean a
@@ -2197,15 +2221,31 @@ class HeadroomProxy(
self._kompress_status = eager_status["kompress"]
if eager_status.get("code_aware") == "enabled":
self._code_aware_status = "enabled"
kompress_enabled = any(
transform.config.enable_kompress
for pipeline in (self.anthropic_pipeline, self.openai_pipeline)
for transform in pipeline.transforms
if isinstance(transform, ContentRouter)
)
# Log component status
if self._kompress_status == "enabled":
logger.info("Kompress: ENABLED (ModernBERT token compressor)")
if eager_status.get("kompress_backend") == "remote":
logger.info("Kompress: ENABLED (remote endpoint; no local model)")
else:
logger.info("Kompress: ENABLED (ModernBERT token compressor)")
elif self._kompress_status == "deferred":
if self._start_kompress_background_warmup():
logger.info("Kompress: DEFERRED (warming in the background after startup)")
else:
logger.info("Kompress: DEFERRED (model loads on first request)")
elif not kompress_enabled and (
self.config.optimize
or self.config.disable_kompress
or self.config.disable_kompress_anthropic is True
or self.config.disable_kompress_openai is True
):
logger.info("Kompress: DISABLED")
elif self.config.optimize:
logger.info("Kompress: not installed (pip install headroom-ai[ml] for ML compression)")
@@ -2337,10 +2377,11 @@ class HeadroomProxy(
if is_beacon_enabled():
logger.info(
"Anonymous upload beacon: ENABLED (default — session summaries are sent to "
"Headroom Labs). Opt out: HEADROOM_BEACON=off or DO_NOT_TRACK=1"
"Headroom Labs). Opt out: HEADROOM_BEACON=off, HEADROOM_TELEMETRY=off or "
"DO_NOT_TRACK=1"
)
else:
logger.info("Anonymous upload beacon: DISABLED")
logger.info("Anonymous upload beacon: DISABLED (%s)", beacon_off_reason())
self.pipeline_extensions.emit(
PipelineStage.POST_START,
@@ -3773,6 +3814,10 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
"cloudcode_api_url": config.cloudcode_api_url,
"vertex_api_url": config.vertex_api_url,
"savings_profile": config.savings_profile,
# Enabled extension names only (no plugin state): `headroom
# wrap` carries them over when it has to start a dedicated
# proxy beside this one, so an enterprise sink is not lost.
"proxy_extensions": sorted(config.proxy_extensions or []),
"target_ratio": effective_target_ratio,
"target_savings_percent": (
round(max(0.0, min(1.0, 1.0 - float(effective_target_ratio))) * 100, 1)
@@ -5374,6 +5419,25 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
# Effective state from the running process. This is the supported
# black-box provenance surface for benchmark/qualification tools.
"rollout": proxy.config.rollout.to_dict() if proxy.config.rollout else None,
"read_maturation": _read_maturation_status(proxy.config),
}
def _read_maturation_status(cfg: ProxyConfig) -> dict[str, Any]:
# The rollout snapshot says whether the feature is enabled, not whether
# it can act; cache mode leaves it enabled but unable to fire.
inert = (
read_maturation_inert_reason(
cfg.mode,
quiesce_turns=cfg.read_maturation_quiesce_turns,
max_hold_turns=cfg.read_maturation_max_hold_turns,
)
if cfg.read_maturation
else None
)
return {
"enabled": cfg.read_maturation,
"effective": cfg.read_maturation and inert is None,
"inert_reason": inert,
}
def _dashboard_config_payload() -> dict[str, Any]:
@@ -183,6 +183,26 @@ def tool_schema_saved_from_tags(tags: object) -> int:
return total
def net_hook_tool_saving(raw_saved: int, tags: object, hook_tool_saved: int) -> int:
"""Net a request's message-side saving against the tool saving its turn
hooks booked on ``turn_hook_tools_saved_tokens``; return it clamped at 0.
The headline is ``tokens_saved`` (clamped) plus that tag. A hook that adds
message text while removing tools leaves ``raw_saved`` negative, and the
clamp alone would drop the growth while the tag kept the full removal. The
deficit is debited from the tag first (at most what the hooks booked on
this request), so headline == messages + tools, signed, clamped once.
"""
raw = int(raw_saved)
booked = max(0, int(hook_tool_saved or 0))
if raw < 0 and booked > 0 and isinstance(tags, dict):
offset = min(-raw, booked)
current = int(tags.get("turn_hook_tools_saved_tokens", 0) or 0)
tags["turn_hook_tools_saved_tokens"] = max(0, current - offset)
raw += offset
return max(0, raw)
def headline_tokens_saved(tokens_saved: object, tags: object) -> int:
"""Return the single "Tokens saved" figure for one request.
+42 -10
View File
@@ -207,6 +207,11 @@ def run_request_hooks(ctx: TurnContext, *, stream_safe_only: bool = False) -> No
# Deferral booked before or by a hook; reconciled once every hook has run,
# since a later hook may un-defer booked tools (tool search's hot tools).
booking = deferred_booking(ctx.tags, ctx.tools)
# Positive nets wait until every hook has run: a later hook that grows the
# request (adds a tool) offsets earlier savings, so the ledger never credits
# more than the whole sequence actually removed.
gains: list[tuple[str, int, dict[str, int]]] = []
sequence_net = 0
for hook in registered_turn_hooks():
if stream_safe_only and not getattr(hook, "stream_safe", False):
continue
@@ -221,24 +226,28 @@ def run_request_hooks(ctx: TurnContext, *, stream_safe_only: bool = False) -> No
if ctx.count_tools is not None:
before_tools = ctx.count_tools(without_deferral_flags(ctx.tools))
fn(ctx)
# Signed deltas, netted: a hook that folds messages but ADDS a tool
# (skill search's ``search_skills``) saved the difference, not the
# fold alone. Booked only when the net is a saving.
message_saved = (
max(0, before_messages - ctx.count_messages(ctx.messages))
before_messages - ctx.count_messages(ctx.messages)
if before_messages is not None and ctx.count_messages is not None
else 0
)
tool_saved = (
max(0, before_tools - ctx.count_tools(without_deferral_flags(ctx.tools)))
before_tools - ctx.count_tools(without_deferral_flags(ctx.tools))
if before_tools is not None and ctx.count_tools is not None
else 0
)
if message_saved or tool_saved:
ctx.record_savings(
getattr(hook, "savings_source", getattr(hook, "name", type(hook).__name__)),
tokens=message_saved + tool_saved,
details={
"message_tokens_saved": message_saved,
"tool_tokens_saved": tool_saved,
},
net_saved = message_saved + tool_saved
sequence_net += net_saved
if net_saved > 0:
gains.append(
(
getattr(hook, "savings_source", getattr(hook, "name", type(hook).__name__)),
net_saved,
{"message_tokens_saved": message_saved, "tool_tokens_saved": tool_saved},
)
)
except Exception: # a hook must never break the proxy
log.exception("turn hook %r on_request failed", getattr(hook, "name", hook))
@@ -246,6 +255,29 @@ def run_request_hooks(ctx: TurnContext, *, stream_safe_only: bool = False) -> No
# This hook booked (or re-booked) the deferral: it is the new baseline.
booking = deferred_booking(ctx.tags, ctx.tools)
reconcile_deferred_tokens(ctx.tags, booking, ctx.tools, ctx.count_tools)
# Book gains in run order up to the sequence's net saving; a loss that
# exceeds them all books nothing (never a negative entry).
budget = max(0, sequence_net)
for source, net_saved, details in gains:
tokens = min(net_saved, budget)
if tokens <= 0:
break
budget -= tokens
if tokens < net_saved:
# Later hooks' cost comes off this credit; share it across the
# message and tool parts so the breakdown still sums to ``tokens``.
# The uncapped deltas stay for diagnosis.
message_part = round(details["message_tokens_saved"] * tokens / net_saved)
details = {
"message_tokens_saved": message_part,
"tool_tokens_saved": tokens - message_part,
"uncapped_message_tokens_saved": details["message_tokens_saved"],
"uncapped_tool_tokens_saved": details["tool_tokens_saved"],
}
try:
ctx.record_savings(source, tokens=tokens, details=details)
except Exception:
log.exception("turn hook savings for %r not recorded", source)
async def run_response_hooks(
+16 -14
View File
@@ -256,19 +256,21 @@ def destination_listed(
return (scheme, host.lower(), port) in origins
# RFC 6052 / RFC 8215: these IPv6 prefixes embed an IPv4 address in their low
# 32 bits, and `ipaddress` reports the well-known one as globally routable. On a
# NAT64 network `64:ff9b::7f00:1` reaches 127.0.0.1, so the embedded address is
# what has to be judged. 6to4, Teredo and IPv4-mapped forms are already caught
# by the `is_global` test below.
_NAT64_PREFIXES = (
ipaddress.IPv6Network("64:ff9b::/96"),
ipaddress.IPv6Network("64:ff9b:1::/48"),
)
# RFC 6052 well-known prefix. A DNS64 resolver answers a host that has only an
# A record with `64:ff9b::<its IPv4>`, and the NAT64 translator delivers that to
# the IPv4 address in the low 32 bits, so the embedded address is what has to
# be judged: `64:ff9b::7f00:1` reaches 127.0.0.1. It has to be judged *before*
# the category checks, because `ipaddress` calls the whole prefix reserved (it
# sits in ::/8) -- judging the IPv6 form rejected every IPv4-only upstream on a
# DNS64 network. The local-use prefix (RFC 8215, 64:ff9b:1::/48) is not
# unwrapped: where its IPv4 bits sit depends on the operator's prefix length,
# so it stays rejected as non-global. 6to4, Teredo and IPv4-mapped forms are
# already caught by the `is_global` test below.
_NAT64_WELL_KNOWN_PREFIX = ipaddress.IPv6Network("64:ff9b::/96")
def _nat64_embedded_ipv4(addr: ipaddress.IPv6Address) -> ipaddress.IPv4Address | None:
if not any(addr in prefix for prefix in _NAT64_PREFIXES):
if addr not in _NAT64_WELL_KNOWN_PREFIX:
return None
try:
return ipaddress.IPv4Address(int(addr) & 0xFFFFFFFF)
@@ -281,6 +283,10 @@ def _is_internal_address(ip: str) -> bool:
addr = ipaddress.ip_address(ip)
except ValueError:
return True # unparseable (e.g. scoped link-local) -> treat as unsafe
if isinstance(addr, ipaddress.IPv6Address):
embedded = _nat64_embedded_ipv4(addr)
if embedded is not None:
return _is_internal_address(str(embedded))
if (
addr.is_private
or addr.is_loopback
@@ -298,10 +304,6 @@ def _is_internal_address(ip: str) -> bool:
# learns about.
if not addr.is_global:
return True
if isinstance(addr, ipaddress.IPv6Address):
embedded = _nat64_embedded_ipv4(addr)
if embedded is not None and _is_internal_address(str(embedded)):
return True
return False
+9 -3
View File
@@ -111,21 +111,27 @@ class WarmupRegistry:
``error`` statuses must be set explicitly by the caller.
"""
def _apply(slot: WarmupSlot, value: str | None) -> None:
def _apply(slot: WarmupSlot, value: str | None, **info: Any) -> None:
if value is None:
return
v = value.strip().lower()
if v in {"enabled", "ready"} or v.startswith("loaded"):
# Preserve whatever handle/info was set already.
if slot.status != "loaded":
slot.mark_loaded(handle=slot.handle, source_status=value)
slot.mark_loaded(handle=slot.handle, source_status=value, **info)
else:
slot.info.setdefault("source_status", value)
else:
if slot.status != "loaded":
slot.info["source_status"] = value
_apply(self.kompress, status.get("kompress"))
# A remote endpoint is ready at startup; /readyz reports its backend.
kompress_backend = status.get("kompress_backend")
_apply(
self.kompress,
status.get("kompress"),
**({"backend": kompress_backend} if kompress_backend == "remote" else {}),
)
_apply(self.magika, status.get("magika"))
_apply(self.code_aware, status.get("code_aware"))
_apply(self.tree_sitter, status.get("tree_sitter"))
+3 -3
View File
@@ -11,7 +11,7 @@ Available scorers:
- Combines BM25 + embeddings for best accuracy
- Adaptive alpha: more BM25 for UUIDs, more semantic for natural language
- Falls back gracefully to BM25 if sentence-transformers not installed
- Install for full support: pip install headroom[relevance]
- Install for full support: pip install "headroom-ai[relevance]"
2. BM25Scorer (zero dependencies)
- Fast keyword matching
@@ -21,7 +21,7 @@ Available scorers:
3. EmbeddingScorer (requires sentence-transformers)
- Pure semantic similarity
- Best for natural language queries
- Install: pip install headroom[relevance]
- Install: pip install "headroom-ai[relevance]"
WHY HYBRID IS DEFAULT:
- Missing important items during compression is catastrophic
@@ -112,7 +112,7 @@ def create_scorer(
if not EmbeddingScorer.is_available():
raise RuntimeError(
"EmbeddingScorer requires sentence-transformers. "
"Install with: pip install headroom[relevance]"
'Install with: pip install "headroom-ai[relevance]"'
)
return EmbeddingScorer(**kwargs)
+5 -4
View File
@@ -13,7 +13,7 @@ Key features:
- ~2-3x faster than sentence-transformers' all-MiniLM-L6-v2
- Outranks all-MiniLM-L6-v2 by ~6 MTEB points
Install with: pip install headroom[relevance]
Install with: pip install "headroom-ai[relevance]"
History: this module previously wrapped `sentence-transformers`
(PyTorch). Switched to fastembed in Stage 3c.1 of the Rust port to:
@@ -49,7 +49,7 @@ def _get_numpy():
except ImportError as e:
raise ImportError(
"numpy is required for EmbeddingScorer. "
"Install with: pip install headroom[relevance]"
'Install with: pip install "headroom-ai[relevance]"'
) from e
return _numpy
@@ -172,7 +172,7 @@ class EmbeddingScorer(RelevanceScorer):
# score.score > 0.5 (semantic match between "failed"/"error" and "errors")
Note:
Requires fastembed: pip install headroom[relevance]
Requires fastembed: pip install "headroom-ai[relevance]"
"""
def __init__(
@@ -218,7 +218,8 @@ class EmbeddingScorer(RelevanceScorer):
"""
if not self.is_available():
raise RuntimeError(
"EmbeddingScorer requires fastembed. Install with: pip install headroom[relevance]"
"EmbeddingScorer requires fastembed. "
'Install with: pip install "headroom-ai[relevance]"'
)
if self._model is None:
+2 -1
View File
@@ -23,7 +23,8 @@ def _get_jinja2_template(template_str: str):
return Template(template_str, autoescape=True)
except ImportError as e:
raise ImportError(
"jinja2 is required for report generation. Install with: pip install headroom[reports]"
"jinja2 is required for report generation. "
'Install with: pip install "headroom-ai[reports]"'
) from e
+44 -6
View File
@@ -41,6 +41,7 @@ blending two meanings.
from __future__ import annotations
import json
import logging
import os
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
@@ -48,6 +49,7 @@ from pathlib import Path
from typing import Any
from headroom import paths as _paths
from headroom.log_safety import WarnOnce, describe_exception, safe_id
# Reuse the proxy tracker's pricing + normalization so MCP and proxy events
# bucket models identically and price them through one implementation.
@@ -68,6 +70,26 @@ try:
except ImportError:
_HAS_FCNTL = False
logger = logging.getLogger(__name__)
# The first failed append to each ledger path is a WARNING so an unwritable
# ledger is visible; repeats drop to DEBUG so a persistent failure cannot flood
# logs. A successful append re-arms the path.
_append_warnings = WarnOnce(64, "unwritable savings ledgers")
def _warn_append_failure(target: Path, exc: BaseException) -> None:
if _append_warnings.first(str(target), logger):
logger.warning(
"savings ledger: append to %s failed: %s; savings will not be recorded. "
"Make the directory writable or set HEADROOM_SAVINGS_EVENTS_PATH.",
target,
describe_exception(exc),
)
else:
logger.debug("savings ledger: append to %s failed: %s", target, describe_exception(exc))
SCHEMA_VERSION = 2
UNKNOWN = "unknown"
@@ -201,7 +223,8 @@ def _price_event(
"""
try:
from headroom.pricing.counterfactual import CacheMix, Region, price_savings
except Exception: # pragma: no cover - defensive
except Exception as exc: # pragma: no cover - defensive
logger.debug("savings ledger: pricing module failed to import: %s", describe_exception(exc))
return None
cache = event.get("cache") or {}
@@ -244,7 +267,12 @@ def _price_event(
total += priced.usd
total_list += priced.usd_list
bases.append(priced.basis)
except Exception: # pragma: no cover - defensive
except Exception as exc: # pragma: no cover - defensive
logger.debug(
"savings ledger: pricing failed for model=%s: %s",
safe_id(model),
describe_exception(exc),
)
return None
if not bases:
@@ -412,9 +440,11 @@ def record_savings_event(
finally:
if _HAS_FCNTL and fcntl is not None:
fcntl.flock(handle, fcntl.LOCK_UN)
except Exception:
except Exception as exc:
_warn_append_failure(target, exc)
return False
_append_warnings.forget(str(target))
_maybe_compact(target)
return True
@@ -454,7 +484,13 @@ def _read_events(
finally:
if _HAS_FCNTL and fcntl is not None:
fcntl.flock(handle, fcntl.LOCK_UN)
except Exception:
except Exception as exc:
logger.warning(
"savings ledger: could not read %s: %s. Check that it is a readable file, "
"or set HEADROOM_SAVINGS_EVENTS_PATH.",
target,
describe_exception(exc),
)
return []
return events
@@ -553,7 +589,8 @@ def _weakest(existing: str | None, incoming: str | None) -> str | None:
from headroom.pricing.counterfactual import weakest_basis
return weakest_basis(existing, incoming)
except Exception: # pragma: no cover - defensive
except Exception as exc: # pragma: no cover - defensive
logger.debug("savings ledger: could not compare pricing bases: %s", describe_exception(exc))
return existing
@@ -758,7 +795,8 @@ def _maybe_compact(target: Path) -> None:
finally:
if _HAS_FCNTL and fcntl is not None:
fcntl.flock(handle, fcntl.LOCK_UN)
except Exception:
except Exception as exc:
logger.debug("savings ledger: compaction of %s failed: %s", target, describe_exception(exc))
return
+23 -2
View File
@@ -1,7 +1,10 @@
"""Storage modules for Headroom SDK."""
import logging
import os
from headroom.log_safety import describe_exception, safe_id
from .base import Storage
from .jsonl import JSONLStorage
from .sqlite import SQLiteStorage
@@ -12,6 +15,8 @@ __all__ = [
"JSONLStorage",
]
logger = logging.getLogger(__name__)
def _builtin_storage_path(store_url: str, scheme: str) -> str:
"""Return the filesystem portion of a built-in storage URL."""
@@ -64,7 +69,23 @@ def create_storage(store_url: str) -> Storage:
create_fn = ep.load()
result: Storage = create_fn(store_url)
return result
except Exception:
pass
logger.warning(
"No headroom.storage_backend entry point for scheme %r; "
"falling back to SQLite storage",
scheme,
)
except Exception as e:
# The plugin's exception can echo the store URL, credentials included,
# so no level logs its message; DEBUG gets describe_exception (types and frames).
logger.warning(
"Failed to load storage backend for scheme %r (%s); "
"falling back to SQLite storage",
scheme,
safe_id(e),
)
if logger.isEnabledFor(logging.DEBUG):
logger.debug(
"Storage backend %r load failure: %s", scheme, describe_exception(e)
)
# Default to SQLite (legacy behavior)
return SQLiteStorage(store_url)
+2 -2
View File
@@ -23,6 +23,7 @@ import httpx
from headroom.offline import OfflineEgressBlocked, guard_egress, note_refusal
from headroom.subscription.models import SubscriptionSnapshot
from headroom.subscription.session_tracking import _claude_config_dir
logger = logging.getLogger(__name__)
@@ -32,8 +33,7 @@ _TOKEN_EXPIRY_BUFFER_S = 60
def _credentials_path() -> Path:
base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~/.claude")
return Path(base) / ".credentials.json"
return _claude_config_dir() / ".credentials.json"
def _load_credentials_file() -> dict[str, Any] | None:
+41 -25
View File
@@ -8,7 +8,8 @@ Never leaves the machine.
``HEADROOM_BEACON`` — **on by default, opt-out.** Uploads an anonymous,
content-free session summary to Headroom Labs. Disable with
``HEADROOM_BEACON=off``, ``DO_NOT_TRACK=1``, or offline mode. See
``HEADROOM_BEACON=off``, ``HEADROOM_TELEMETRY=off``, ``DO_NOT_TRACK=1``, or
offline mode. See
:mod:`headroom.telemetry.session` for the exact payload and
``deploy/beacon/worker.js`` for what the receiver does with it.
@@ -17,7 +18,9 @@ collector via ``HEADROOM_OTEL_METRICS_*`` — a destination you control, that
Headroom Labs never sees.
Keeping these separate matters: an operator who turned on local stats has not
thereby agreed to upload anything, and must not start doing so on upgrade.
thereby agreed to upload anything, and must not start doing so on upgrade. The
one crossing is deliberate and only ever turns the upload off: an explicit
``HEADROOM_TELEMETRY=off`` reads as "send nothing", so the beacon honours it.
"""
from __future__ import annotations
@@ -56,40 +59,53 @@ def is_telemetry_enabled() -> bool:
BEACON_DEFAULT_ON = True
def is_beacon_enabled() -> bool:
"""Check if the anonymous upload beacon is enabled.
def beacon_off_reason() -> str | None:
"""Name the setting that turns the anonymous upload beacon off, or ``None`` when on.
Default is :data:`BEACON_DEFAULT_ON`. Three things switch it off regardless,
in this order:
Default is :data:`BEACON_DEFAULT_ON`. Checked in this order, first match wins:
* offline mode — no network is no network;
* ``DO_NOT_TRACK`` — the cross-tool convention, honoured because a user who
has already stated this preference should not have to state it again;
* ``HEADROOM_BEACON=off`` (or false/0/no/disable/disabled).
* ``HEADROOM_BEACON`` — the beacon's own switch; an explicit on-value keeps
the beacon on even when local stats are off;
* ``HEADROOM_TELEMETRY=off`` (or false/0/no/disable/disabled) — people set
the telemetry switch to mean "send nothing", so an explicit off stops the
upload too.
Deliberately a *separate* switch from ``HEADROOM_TELEMETRY``. That flag
means "aggregate stats locally so ``/stats`` has something to show" — data
that never leaves the machine. Overloading it to also authorise upload
would mean every operator who had turned on local stats begins transmitting
the moment they upgrade, having answered a different question.
Only an explicit *off* on ``HEADROOM_TELEMETRY`` reaches the beacon. Its
*on* still means only "aggregate stats locally": turning on local stats must
never be read as agreeing to upload.
The result is what ``headroom telemetry`` prints, so it is the variable and
value as the operator wrote them (lowercased), e.g. ``HEADROOM_TELEMETRY=off``.
"""
from headroom.offline import OFFLINE_ENV, is_offline
if is_offline():
return f"{OFFLINE_ENV} (offline mode)"
dnt = os.environ.get("DO_NOT_TRACK", "").lower().strip()
if dnt and dnt not in _OFF_VALUES:
return f"DO_NOT_TRACK={dnt}"
raw = os.environ.get("HEADROOM_BEACON", "").lower().strip()
if raw in _OFF_VALUES:
return f"HEADROOM_BEACON={raw}"
if raw in _ON_VALUES:
return None
local = os.environ.get("HEADROOM_TELEMETRY", "").lower().strip()
if local in _OFF_VALUES:
return f"HEADROOM_TELEMETRY={local}"
return None if BEACON_DEFAULT_ON else "default (opt-in)"
def is_beacon_enabled() -> bool:
"""Check if the anonymous upload beacon is enabled; see :func:`beacon_off_reason`.
Note the asymmetry with :func:`is_telemetry_enabled`, which is fail-closed:
this one is fail-open by construction while ``BEACON_DEFAULT_ON`` is True,
so an unrecognised value uploads rather than staying silent.
"""
from headroom.offline import is_offline
if is_offline():
return False
dnt = os.environ.get("DO_NOT_TRACK", "").lower().strip()
if dnt and dnt not in _OFF_VALUES:
return False
raw = os.environ.get("HEADROOM_BEACON", "").lower().strip()
if raw in _OFF_VALUES:
return False
if raw in _ON_VALUES:
return True
return BEACON_DEFAULT_ON
return beacon_off_reason() is None
def is_telemetry_warn_enabled() -> bool:
+14
View File
@@ -1768,7 +1768,13 @@ def post_session_event(payload: dict[str, Any]) -> None:
ponytail: unbounded thread spawn is safe only because the close rate is
bounded by the idle timeout. Revisit if anything else starts emitting here.
"""
from headroom.telemetry.beacon import is_beacon_enabled
try:
# Re-checked at send time: a session buffered before an opt-out must
# not upload after it (heartbeats and idle closes send through here).
if not is_beacon_enabled():
return
threading.Thread(
target=_post_blocking,
args=(payload,),
@@ -1812,9 +1818,17 @@ def _flush_at_exit() -> None:
Still does not cover SIGKILL or a closed laptop. Heartbeats bound the loss
there to one flush interval.
"""
from headroom.telemetry.beacon import is_beacon_enabled
aggregator = _aggregator
if aggregator is None:
return
try:
if not is_beacon_enabled(): # opted out since the session was buffered
return
except Exception:
logger.debug("telemetry: beacon gate failed at exit", exc_info=True)
return
aggregator.flush_all(emit=lambda payload: _post_blocking(payload, timeout=_EXIT_POST_TIMEOUT_S))
+43
View File
@@ -2,12 +2,55 @@
from __future__ import annotations
import logging
from abc import ABC, abstractmethod
from typing import Any
from ..config import TransformResult
from ..log_safety import describe_exception, safe_id
from ..tokenizer import Tokenizer
logger = logging.getLogger(__name__)
def persist_rust_ccr_entry(original: str, compressed: str, cache_key: str, *, source: str) -> None:
"""Store a Rust-emitted CCR entry in the production ``CompressionStore``.
The Rust search/diff/log compressors emit a retrieval marker but keep the
original only in their in-memory test store. This writes it through to the
long-lived Python store so the marker resolves. Failures are logged at
warning level with ``source`` (the compressor name): a store hiccup must not
break the response, just degrade retrieval.
"""
try:
from ..cache.compression_store import get_compression_store
except ImportError as e:
logger.warning(
"CCR store import failed (%s); cache_key %s won't persist: %s",
source,
cache_key,
safe_id(e),
)
logger.debug("CCR store import failure detail: %s", describe_exception(e))
return
try:
store: Any = get_compression_store()
# The Rust-emitted marker embeds MD5(original)[:24], but store() has
# defaulted to SHA-256(original)[:24] since PR #395. Pass the marker's
# key explicitly so retrieving the marker hash finds the entry (#816).
store.store(original, compressed, explicit_hash=cache_key)
except Exception as e:
# Store backends can echo the payload in errors. The WARNING names only
# the exception type; the DEBUG record has types and code locations, or
# the full traceback (payload included) once HEADROOM_DEBUG_DUMP=full.
logger.warning(
"CCR store write failed (%s, %s); cache_key %s remains in-marker only",
source,
safe_id(e),
cache_key,
)
logger.debug("CCR store write failure detail: %s", describe_exception(e))
class Transform(ABC):
"""Abstract base class for message transforms."""

Some files were not shown because too many files have changed in this diff Show More