chore: merge main while preserving output savings confidence gates

This commit is contained in:
JerrettDavis
2026-10-08 05:44:35 -05:00
177 changed files with 19709 additions and 1815 deletions
+4 -4
View File
@@ -3,10 +3,10 @@
# Path matters: cargo-audit reads `.cargo/audit.toml`, not a root-level
# `audit.toml`. A file at the repo root is silently ignored.
#
# The `audit` job in .github/workflows/rust.yml is a BLOCKING gate. It runs on
# every PR touching Rust and nightly on the schedule (the `rust-changes` job
# reports `rust=true` for `schedule`/`workflow_dispatch`, so a newly-disclosed
# advisory surfaces without anyone touching Rust code).
# The `cargo-audit` job in .github/workflows/security.yml is a BLOCKING gate.
# It runs on every PR and push to main whatever paths changed, and weekly on
# that workflow's schedule, so a newly-disclosed advisory surfaces without
# anyone touching Rust code.
#
# It was `continue-on-error: true` until the change that added this file, which meant it reported findings
# nobody saw: RUSTSEC-2026-0258 (h2, unbounded empty DATA frames) sat in a green
+7
View File
@@ -18,6 +18,13 @@ __pycache__
dist/
build/
# Rust artifacts. The Dockerfile runs its own `cargo build` inside the
# builder stage, so the host's target/ is never needed — and after a
# local `cargo build` it is 100GB+, which the daemon dutifully copies
# on every `docker build`. CI never noticed because a fresh checkout
# has no target/; it only ever bites local builds.
target/
# Dev/test tooling
.pytest_cache
.coverage
+96
View File
@@ -0,0 +1,96 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 240" width="880" height="240" role="img"
aria-label="Headroom Enterprise for teams: 3 months free with a 12-month plan. Adds tool search, model routing, attack removal and org-wide savings. Claim the perk.">
<title>Headroom Enterprise — 3 months free with a 12-month plan</title>
<defs>
<!-- Brand palette as in hero.svg: Mint #00F0B5, Obsidian #070A0F,
Midnight #0C1118, Cyan #65D8FF, White, Slate #98A4B3.
Dark in both GitHub themes, matching the hero. -->
<pattern id="pgrid" width="44" height="44" patternUnits="userSpaceOnUse">
<path d="M44 0H0V44" fill="none" stroke="#00F0B5" stroke-opacity="0.05" stroke-width="1"/>
</pattern>
<radialGradient id="pglow" cx="12%" cy="0%" r="80%">
<stop offset="0%" stop-color="#00F0B5" stop-opacity="0.16"/>
<stop offset="100%" stop-color="#00F0B5" stop-opacity="0"/>
</radialGradient>
<linearGradient id="pedge" x1="0" y1="0" x2="1" y2="0">
<stop offset="0%" stop-color="#00F0B5" stop-opacity="0.65"/>
<stop offset="55%" stop-color="#65D8FF" stop-opacity="0.35"/>
<stop offset="100%" stop-color="#65D8FF" stop-opacity="0.10"/>
</linearGradient>
<linearGradient id="pbtn" x1="0" y1="0" x2="1" y2="1">
<stop offset="0%" stop-color="#00F0B5"/>
<stop offset="100%" stop-color="#0FD9AE"/>
</linearGradient>
<linearGradient id="pshine" gradientUnits="userSpaceOnUse" x1="0" y1="0" x2="70" y2="0">
<stop offset="0%" stop-color="#FFFFFF" stop-opacity="0"/>
<stop offset="50%" stop-color="#FFFFFF" stop-opacity="0.45"/>
<stop offset="100%" stop-color="#FFFFFF" stop-opacity="0"/>
</linearGradient>
<clipPath id="pbtnclip"><rect x="646" y="94" width="208" height="58" rx="29"/></clipPath>
<style>
.s { font-family: "Segoe UI", Inter, -apple-system, BlinkMacSystemFont, Helvetica, Arial, sans-serif; }
/* One light pass over the button per cycle draws the eye to the action. */
.shine { animation: shine 5s ease-in-out infinite; }
@keyframes shine { 0%, 55% { transform: translateX(-80px) } 85%, 100% { transform: translateX(240px) } }
.dot { animation: beat 2.4s ease-in-out infinite; }
@keyframes beat { 0%, 100% { opacity: 1 } 50% { opacity: .3 } }
@media (prefers-reduced-motion: reduce) {
.shine, .dot { animation: none; }
.shine { opacity: 0; }
}
</style>
</defs>
<!-- Card. One font family, three sizes: 52 headline, 20 lead and button, 16 everything else. -->
<rect x="1" y="1" width="878" height="238" rx="18" fill="#070A0F"/>
<rect x="1" y="1" width="878" height="238" rx="18" fill="url(#pgrid)"/>
<rect x="1" y="1" width="878" height="238" rx="18" fill="url(#pglow)"/>
<rect x="1" y="1" width="878" height="238" rx="18" fill="none" stroke="url(#pedge)" stroke-width="1.5"/>
<g class="s">
<!-- Eyebrow -->
<circle class="dot" cx="46" cy="47" r="5" fill="#00F0B5"/>
<text x="60" y="53" font-size="16" font-weight="600" letter-spacing="1.5" fill="#00F0B5">HEADROOM ENTERPRISE · FOR TEAMS</text>
<!-- Headline -->
<text x="40" y="116" font-size="52" font-weight="700" fill="#FFFFFF">3 months free</text>
<text x="40" y="152" font-size="20" fill="#98A4B3">with a 12-month plan · one perk per company</text>
<!-- What Enterprise adds -->
<g font-size="16" fill="#E6EDF3">
<rect x="40" y="178" width="118" height="36" rx="18" fill="#0C1118" stroke="#00F0B5" stroke-opacity="0.30"/>
<text x="99" y="202" text-anchor="middle">Tool search</text>
<rect x="168" y="178" width="134" height="36" rx="18" fill="#0C1118" stroke="#00F0B5" stroke-opacity="0.30"/>
<text x="235" y="202" text-anchor="middle">Model routing</text>
<rect x="312" y="178" width="140" height="36" rx="18" fill="#0C1118" stroke="#00F0B5" stroke-opacity="0.30"/>
<text x="382" y="202" text-anchor="middle">Attack removal</text>
<rect x="462" y="178" width="156" height="36" rx="18" fill="#0C1118" stroke="#65D8FF" stroke-opacity="0.30"/>
<text x="540" y="202" text-anchor="middle">Org-wide savings</text>
</g>
<!-- Divider -->
<line x1="634" y1="36" x2="634" y2="204" stroke="#98A4B3" stroke-opacity="0.18"/>
<!-- Call to action -->
<text x="750" y="72" font-size="16" text-anchor="middle" fill="#98A4B3">SSO · VPC or managed</text>
<g clip-path="url(#pbtnclip)">
<rect x="646" y="94" width="208" height="58" rx="29" fill="url(#pbtn)"/>
<rect class="shine" x="646" y="94" width="70" height="58" fill="url(#pshine)"/>
</g>
<text x="750" y="130" font-size="20" font-weight="700" text-anchor="middle" fill="#070A0F">Claim the perk →</text>
<text x="750" y="190" font-size="16" text-anchor="middle" fill="#98A4B3">headroom-perks.vercel.app</text>
</g>
</svg>

After

Width:  |  Height:  |  Size: 4.8 KiB

+6 -6
View File
@@ -44,15 +44,15 @@ jobs:
- run: npm run build
- run: npm test
# The wheel ships a committed self-contained bundle at
# headroom/providers/opencode/_dist/entry.opencode.js so pip installs
# get the transport plugin too. Rebuild it and fail if the committed
# artifact has drifted from the source.
# headroom/providers/opencode/_dist/index.js so pip installs get the
# transport plugin too. Rebuild it and fail if the committed artifact
# has drifted from the source.
- run: npm run build:standalone
- name: verify committed wheel bundle matches source
run: |
cmp dist-standalone/entry.opencode.js \
../../headroom/providers/opencode/_dist/entry.opencode.js \
|| { echo "::error::headroom/providers/opencode/_dist/entry.opencode.js is stale - run 'npm run build:standalone' in plugins/opencode and commit the result"; exit 1; }
cmp dist-standalone/index.js \
../../headroom/providers/opencode/_dist/index.js \
|| { echo "::error::headroom/providers/opencode/_dist/index.js is stale - run 'npm run build:standalone' in plugins/opencode and commit the result"; exit 1; }
cmp dist-standalone/hook-shim/handler.js \
../../headroom/providers/opencode/hook-shim/handler.js \
|| { echo "::error::headroom/providers/opencode/hook-shim/handler.js is stale - run 'npm run build:standalone' in plugins/opencode and commit the result"; exit 1; }
+24 -1
View File
@@ -789,7 +789,10 @@ jobs:
# recommended pattern for release workflows that may run
# multiple times against the same version.
skip-existing: true
attestations: false
# PEP 740 attestations from this job's trusted-publishing identity
# (needs only `id-token: write`, granted above). Off since #2405 with
# no recorded root cause; if a release fails on them, revert this line.
attestations: true
publish-npm:
needs: [detect-version, build]
@@ -1062,6 +1065,26 @@ jobs:
gh release create "$TAG" --title "$TITLE" --notes-file .changelog.md
fi
# Appends once: a re-run finds this step's own marker and leaves the notes
# alone. Keyed on the marker, not the link, so a changelog entry that
# happens to mention the perks page does not suppress the footer.
# Release notes stay the changelog; this is one line under it.
- name: Add Headroom for Teams footer to release notes
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
TAG="v${{ needs.detect-version.outputs.version }}"
MARKER='<!-- headroom-teams-footer -->'
gh release view "$TAG" --json body --jq .body > release-notes.md
if ! grep -qF "$MARKER" release-notes.md; then
{
printf '\n%s\n\n---\n\n' "$MARKER"
printf '**Headroom for Teams:** 3 months of Headroom Enterprise free with a 12-month plan. '
printf '[Claim the perk →](https://headroom-perks.vercel.app/?source=github&utm_source=github&utm_medium=release-notes&utm_content=%s)\n' "$TAG"
} >> release-notes.md
gh release edit "$TAG" --notes-file release-notes.md
fi
- name: Publish ${{ env.PYPI_PACKAGE }} Python distributions to GitHub Release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+4 -26
View File
@@ -208,32 +208,10 @@ jobs:
name: wheels-${{ matrix.target }}
path: dist/*.whl
audit:
name: audit
needs: rust-changes
if: needs.rust-changes.outputs.rust == 'true'
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v7
- uses: dtolnay/rust-toolchain@stable
with:
toolchain: 1.95.0
- uses: Swatinem/rust-cache@v2
- name: Install cargo-audit + cargo-deny
uses: taiki-e/install-action@v2
with:
tool: cargo-audit,cargo-deny
# Blocking. Soft-failing this made it useless: RUSTSEC-2026-0258 (h2,
# unbounded empty DATA frames -> unbounded memory or a panic) was
# reported by this job for as long as it existed and never turned a run
# red, so nobody acted on it. Accepted advisories go in audit.toml with
# a written reason rather than being swallowed wholesale here.
- name: cargo audit
run: cargo audit
- name: cargo deny check licenses
continue-on-error: true
run: cargo deny check licenses
# The Rust dependency advisory scan (`cargo audit`) moved to security.yml,
# where it runs on every PR and push regardless of which paths changed. Here
# it sat behind the `rust-changes` filter and this workflow's schedule, and
# that combination let three weeks pass with no scan at all.
# Blocking on every PR that touches Rust. Safe to harden now because the
# harness fails only on a Diff — `parity-run` sets `any_diffs` inside the
+43
View File
@@ -0,0 +1,43 @@
name: SDK (TypeScript)
# The TypeScript SDK (sdk/typescript, published to npm as `headroom-ai`) has a
# vitest suite, a typecheck and a build, yet nothing in CI ever ran them. Two
# individually green PRs could leave `npm test` red on main (#3424 + #3370,
# repaired in #3796), and a dependabot bump of `ai` could break three adapter
# tests without anyone noticing (#3910). This gate runs the SDK's own
# test + typecheck + build whenever it (or this workflow) changes, mirroring
# the OpenCode plugin gate in opencode-plugin.yml.
on:
pull_request:
branches: [main]
paths:
- "sdk/typescript/**"
- ".github/workflows/sdk-typescript.yml"
push:
branches: [main]
paths:
- "sdk/typescript/**"
- ".github/workflows/sdk-typescript.yml"
permissions:
contents: read
jobs:
test:
name: test + typecheck + build
runs-on: ubuntu-latest
timeout-minutes: 15
defaults:
run:
working-directory: sdk/typescript
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: ">=24.16.0 <25"
cache: npm
cache-dependency-path: sdk/typescript/package-lock.json
- run: npm ci
- run: npm test
- run: npm run typecheck
- run: npm run build
+29
View File
@@ -55,6 +55,35 @@ jobs:
with:
inputs: requirements-prod.txt
# ---- SCA: Rust dependency advisories -----------------------------------
# `cargo audit` reads Cargo.lock only (no build, about a minute), so it runs
# unconditionally: every PR, every push to main, and the weekly schedule
# above. It used to live in rust.yml behind the `rust-changes` path filter;
# pushes that touched no Rust path reported it `skipped`, and rust.yml's own
# schedule stopped firing after 2026-09-08, so no advisory scan ran for three
# weeks. Blocking: an accepted advisory goes in .cargo/audit.toml with a
# written reason.
cargo-audit:
name: Rust advisories (cargo audit)
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v7
- name: Install cargo-audit + cargo-deny
uses: taiki-e/install-action@v2
with:
tool: cargo-audit,cargo-deny
- name: cargo audit (blocking; exceptions in .cargo/audit.toml)
run: cargo audit
# Licence allow-list from deny.toml. Advisory decisions stay with
# cargo-audit above, so there is one place that decides what is accepted.
- name: cargo deny check licenses
continue-on-error: true
run: cargo deny check licenses
# Audit every maintained npm lock, including development dependencies.
# Lockfile audits do not install packages or execute their lifecycle scripts.
npm-audit:
Generated
+1
View File
@@ -2009,6 +2009,7 @@ dependencies = [
"aws-sigv4",
"aws-smithy-runtime-api",
"axum",
"base64 0.22.1",
"bytes",
"bytesize",
"clap",
+22 -13
View File
@@ -16,6 +16,7 @@
<p>
<b><a href="https://docs.headroomlabs.ai/docs/quickstart">Quickstart</a></b> ·
<b><a href="#headroom-for-teams">Headroom for Teams</a></b> ·
<a href="#get-started-60-seconds">Install</a> ·
<a href="#proof">Proof</a> ·
<a href="#agent-compatibility">Agents</a> ·
@@ -37,6 +38,10 @@ chunks, files, and conversation history — before it reaches the LLM. Same
answers, fraction of the tokens. Compression runs on your machine; no prompt or
file content is sent anywhere to be compressed.
<p align="center">
<a href="https://headroom-perks.vercel.app/?source=github&utm_source=github&utm_medium=readme&utm_content=banner"><img src=".github/assets/enterprise-perk.svg" alt="Headroom Enterprise for teams: 3 months free with a 12-month plan. Claim the perk." width="880"></a>
</p>
<div align="center">
<img src="HeadroomDemo-Fast.gif" alt="Headroom compressing a 10,144 token log dump to 1,260 tokens while preserving the FATAL line" width="820">
<br><sub>10,144 → 1,260 tokens. The same <code>FATAL</code> found.</sub>
@@ -615,26 +620,30 @@ regresses a compression ratio across real workloads rather than only our own tes
corpus.
Turn it off with `HEADROOM_BEACON=off`, the `DO_NOT_TRACK=1` convention, or
`--offline`. The full field list is in
`HEADROOM_OFFLINE=1`. The full field list is in
[the proxy docs](https://docs.headroomlabs.ai/docs/proxy).
## Headroom for teams
Headroom OSS is built for individual developers: run `headroom proxy` or
`headroom wrap` on your laptop and start cutting tokens in minutes, free and
local-first.
Headroom OSS is built for one developer on one laptop. Headroom Enterprise is built
for the whole team.
Running it across an engineering org is a different job — a shared always-on
deployment, centralised config and version rollout, org-wide savings dashboards,
SSO and access control, air-gapped and VPC installs, and someone to call. We help
companies with that, self-hosted with support or fully managed.
| | Open source | Enterprise |
|---|---|---|
| Savings | Compression, plus tool search on Anthropic requests (on by default) | Also: tool search for every model, harness tuning, extra compressors |
| Model routing | Rule-based and opt-in: turn it on with `HEADROOM_MODEL_ROUTER_ENABLED=1` and write the rules in `HEADROOM_MODEL_ROUTES` | Automatic: a cheaper model per request when quality allows, with a shadow mode that shows the savings before you turn it on |
| Security | — | Detect and strip prompt injection and risky tool calls |
| Rollout | Per laptop | Managed or in your VPC, SSO, central config, org-wide savings |
| Support | GitHub, Discord | Dedicated engineers, onboarding, priority response |
If your team is spending real money on LLM tokens — Claude Code, Codex, Cursor,
or agents running in CI — email **[hello@headroomlabs.ai](mailto:hello@headroomlabs.ai)**
with your stack and rough monthly LLM spend.
**3 months of Enterprise free.** Companies that sign a 12-month Enterprise plan get
their first 3 months free. One perk per company.
Everything in this repo stays open source under Apache 2.0. The managed offering
is for teams that would rather have it deployed, supported and scaled for them.
**[Claim 3 months free →](https://headroom-perks.vercel.app/?source=github&utm_source=github&utm_medium=readme&utm_content=teams)**
· or email [hello@headroomlabs.ai](mailto:hello@headroomlabs.ai) with your stack and
monthly LLM spend.
Everything in this repo stays open source under Apache 2.0.
## Documentation
+74
View File
@@ -92,6 +92,80 @@ curl -si http://127.0.0.1:8787/v1/models
| `--log-level` | | `info` | `RUST_LOG`-style filter |
| `--rewrite-host` / `--no-rewrite-host` | | rewrite | rewrite Host to upstream (default) |
| `--graceful-shutdown-timeout` | | `30s` | wait for in-flight on SIGTERM/SIGINT |
| `--stats` | `HEADROOM_PROXY_STATS` | `true` | native savings stats + `/dashboard` (below) |
| `--stats-path` | `HEADROOM_PROXY_STATS_PATH` | `~/.headroom/native_stats.json` | ledger persistence (honours `HEADROOM_WORKSPACE_DIR`) |
### Savings stats & dashboard (native)
The Rust proxy records per-request savings/cost telemetry on every
lane it forwards — Anthropic `/v1/messages`, OpenAI Chat/Responses,
all four native Bedrock routes, and Vertex `rawPredict` /
`streamRawPredict` — and serves it locally (never tunnelled
upstream):
```bash
curl -s http://127.0.0.1:8787/stats | jq '.session' # since-boot totals
curl -s http://127.0.0.1:8787/stats | jq '.lifetime_by_model'
curl -s "http://127.0.0.1:8787/stats/timeseries?bucket=day" | jq '.points[-7:]'
curl -s "http://127.0.0.1:8787/stats/events?limit=5" # recent-request feed
open http://127.0.0.1:8787/dashboard # embedded UI, zero deps
```
Recording is deferred until the response is fully observed, so
streaming output/cache token counts come from the real SSE /
EventStream usage frames. USD figures come from the vendored LiteLLM
price table (`data/model_prices_and_context_window.json`); a model
missing from it records $0 and logs one WARN — refresh via
`scripts/refresh_model_limits.sh`. Input and output are priced
separately (`input_cost_usd` / `output_cost_usd`) because they bill
at different rates — output is typically 4-5x input, so a spend
figure that counted input alone would understate a short-prompt,
long-answer turn by most of its cost. `total_cost_usd` is the sum
and is what `/dashboard` shows as "Spend". Cache savings are NET: the
cache-read discount minus the cache-write premium (writes bill
above list price), floored at $0 per request — a warm-up turn that
only writes is not counted as negative savings, and gross-read
figures that overstate the benefit are never shown. Failed upstreams count as
failures and accrue no savings — as do proxy-side rejections
(missing AWS credentials, SigV4/ADC failures, oversized bodies), so
an operator-side outage reads as a failure spike rather than as
zero traffic. Aggregates (lifetime, per-model, 48 h hourly +
~13 mo daily buckets) persist as one atomic snapshot written off
the hot path every 10 s and on shutdown.
> **What reads 0 today.** Spend, token counts, and prompt-cache
> savings are live. `tokens_saved` / `compression_savings_usd` are
> wired end-to-end but will report 0 on real traffic until the
> live-zone per-type compressors are implemented — the dispatcher
> currently returns `NoCompression` for every well-formed body
> (`live_zone_mode_with_valid_body_returns_no_compression_pr_b2`
> pins that invariant). Nothing needs changing here when they land;
> the numbers start flowing on their own.
> **No auth; exposure is split by tier.** These endpoints bind
> wherever `--listen` points (default `0.0.0.0:8787`) and carry no
> auth, so the payload is split the same way the Python proxy splits
> its own `/stats`:
>
> - **Aggregates** — spend, tokens, per-model/provider rollups,
> history — are served to anyone, like the Prometheus `/metrics`
> endpoint next door. Same data class, same stance.
> - **Per-request rows** — `recent_requests`, all of `/stats/events`
> — plus the ledger's filesystem path are served **only to local
> callers**: loopback peer *and* a loopback `Host` header (the
> second is the DNS-rebinding defence — a rebound request reaches
> the proxy *from* loopback, so the peer check alone doesn't hold).
> Remote callers get `recent_requests: null` and a 404 from
> `/stats/events`; the dashboard says so rather than erroring.
>
> A request id + model + timestamp is a different sensitivity tier
> from a counter, and `/metrics` never exposes it — so "same as
> /metrics" isn't a licence to hand it to the open internet. Opening
> the local-only tier to a trusted reverse proxy is tracked in
> [#1959](https://github.com/headroomlabs-ai/headroom/issues/1959),
> which is settling that policy for the Python dashboard first; this
> surface should adopt it rather than grow a second scheme.
> `--stats=false` removes the routes entirely.
### Picking the next port: invocation telemetry
@@ -0,0 +1,85 @@
# Claude Code tool search: native vs Headroom
A live A/B benchmark. Each run is a fresh, isolated Claude Code session with its own
throwaway `HOME`, a new copy of `fixture/`, and six fake enterprise MCP servers
(`mcp_server.py`: GitHub, Jira, Slack, Datadog, PagerDuty and Confluence, 63 tools).
Every session does the same task:
1. Read Jira BENCH-42.
2. Fix the pricing bug.
3. Run the tests.
4. Search the Datadog logs.
5. Comment on the ticket.
6. Post to Slack.
Usage is read from Claude Code's own transcript, which records what the API billed,
subagents included.
```bash
python3 benchmarks/tool_search_vs_native/run.py --arms native,hr_client,hr_server,hr_hot --reps 3 --warmup
python3 benchmarks/tool_search_vs_native/run.py ... --context-kb 200 # lookups deep in a long session
```
The script needs `ANTHROPIC_API_KEY` (or `~/env.txt`) and the repo's `.venv`. A full run
of four arms with three reps and a warmup costs about $1 short and $5 long, on Sonnet 5.5.
| Arm | Setup |
|---|---|
| `native` | Claude Code straight to api.anthropic.com, with its own ToolSearch (on by default). |
| `eager` | Claude Code straight to Anthropic with `ENABLE_TOOL_SEARCH=false`, so nothing is deferred. |
| `hr_client` | Claude Code through Headroom with `ENABLE_TOOL_SEARCH=true` (what `headroom wrap` sets today). |
| `hr_server` | Claude Code through Headroom with `ENABLE_TOOL_SEARCH=false`. Headroom defers tools on Anthropic's side. |
| `hr_hot` | As `hr_server`, but the MCP tools a developer uses routinely stay loaded (`HEADROOM_TOOL_SEARCH_CORE_TOOLS`). |
## Results (2026-10-06, Claude Code 2.1.290, Sonnet 5.5, n=3 after warmup, median)
Run on macOS 26.6 (arm64) with Python 3.12.13 (the repo's `.venv`) and real Anthropic API
calls. Commands:
```bash
python3 benchmarks/tool_search_vs_native/run.py --arms native,hr_hot,hr_client --reps 3 --warmup
python3 benchmarks/tool_search_vs_native/run.py --arms native,hr_hot,hr_client --reps 3 --warmup --context-kb 200
```
A run passes only if Claude Code exits 0, the fixture tests pass, and the session called
Jira `get_issue`, Datadog `search_logs`, Jira `add_comment` and Slack `post_message`.
All 73 recorded runs pass under that rule.
| | native | hr_client | hr_server | hr_hot |
|---|---|---|---|---|
| short task, before fixes | $0.059 | $0.062 | $0.081 | $0.049 |
| long task, before fixes | $0.283 | $0.323 | $0.350 | $0.426 |
| long task, **after fixes** | $0.284 | **$0.284** | — | **$0.255 (−10%)** |
| short task, **after fixes** | $0.061 | $0.062 | — | **$0.046 (−25%)** |
The "after" rows held in every run: on the long task `hr_hot` cost $0.254–0.256 and
`native` $0.282–0.284.
### What the runs showed
- **A tool lookup costs a re-read of the whole conversation.** That holds for Claude
Code's ToolSearch, which takes an extra turn, and for Anthropic's server-side search,
which takes an extra sampling pass inside the same call (usage sums the iterations). A
schema that stays loaded costs about 0.1× its size per turn. So keeping a routinely
used tool loaded is far cheaper than looking it up.
- **Server-side search without names searches blindly.** Claude Code tells the model the
deferred tool names, so it loads everything it needs in one `select:`. Headroom's
server-side deferral gives no names, and the model ran 2–5 regex searches. Each search
pulled in about 4.7K tokens of schemas, uncached.
- **Bug: cache mode broke when Claude Code re-serialized its last reply.** Headroom
records the model's raw reply as the end of the previous turn. Claude Code sends that
reply back edited: it strips a leading `cd <cwd> &&` from Bash commands and drops
`caller`. The history then read as diverged, Headroom forwarded the raw originals over
its earlier compressed messages, and the whole conversation was re-written to cache:
66.8K tokens on every long `hr_hot` run. Fixed in `headroom/cache/prefix_tracker.py`
(`_client_rewrote_reply_delta`). Set `HEADROOM_DEBUG_PREFIX_MISMATCH=<dir>` to log and
dump where a history diverges.
- **Bug: compressing small MCP results cost turns.** The Jira ticket (a few hundred
tokens) was compressed and lost its description, so the model called
`headroom_retrieve` and then re-fetched the ticket: two extra turns, about +15% on the
long task. MCP results under `HEADROOM_MCP_RESULT_MIN_CHARS` (default 4000) are now
forwarded verbatim, in both Anthropic `tool_result` blocks and OpenAI `role: "tool"`
messages.
The fake MCP schemas are terse compared with real servers such as GitHub's official one,
so absolute savings here understate a real catalog.
@@ -0,0 +1,16 @@
"""Checkout pricing."""
from __future__ import annotations
def apply_discount(price: float, percent: float) -> float:
"""Return ``price`` after a ``percent`` discount, rounded to cents."""
discounted = price * (1 - percent / 100)
discounted = discounted * (1 - percent / 100)
return round(discounted, 2)
def order_total(items: list[tuple[float, int]], coupon_percent: float = 0) -> float:
"""Sum ``(unit_price, quantity)`` lines and apply an optional coupon."""
subtotal = sum(price * qty for price, qty in items)
return apply_discount(subtotal, coupon_percent) if coupon_percent else round(subtotal, 2)
@@ -0,0 +1,18 @@
import unittest
from shop.pricing import apply_discount, order_total
class PricingTest(unittest.TestCase):
def test_ten_percent(self):
self.assertEqual(apply_discount(100.0, 10), 90.0)
def test_zero(self):
self.assertEqual(apply_discount(59.99, 0), 59.99)
def test_order_total_with_coupon(self):
self.assertEqual(order_total([(20.0, 2), (10.0, 1)], coupon_percent=10), 45.0)
if __name__ == "__main__":
unittest.main()
@@ -0,0 +1,697 @@
#!/usr/bin/env python3
"""Deterministic stdio MCP server standing in for one enterprise service.
python3 mcp_server.py <service> <calls.jsonl>
Exposes realistic, full-size tool schemas (GitHub, Jira, Slack, Datadog, PagerDuty,
Confluence) so a coding agent sees a catalog the size real enterprise setups have.
Every tools/call is appended to calls.jsonl so the benchmark can check the task was done.
Standard library only; speaks newline-delimited JSON-RPC 2.0 (MCP stdio transport).
"""
from __future__ import annotations
import json
import sys
SERVICE = sys.argv[1]
CALL_LOG = sys.argv[2]
# (name, description, {param: (type, description)}, required)
CATALOG = {
"github": [
(
"search_repositories",
"Search GitHub repositories by keyword, language, topic, stars or owner. Returns repository metadata including default branch, visibility, open issue count and last push time.",
{
"query": (
"string",
"GitHub search syntax, e.g. 'billing language:python org:acme'",
),
"sort": ("string", "stars, forks, updated or best-match"),
"per_page": ("integer", "Results per page, 1-100"),
"page": ("integer", "Page number, starting at 1"),
},
["query"],
),
(
"get_repository",
"Get full metadata for one repository: description, topics, default branch, branch protection summary, languages, license and permissions of the caller.",
{
"owner": ("string", "Repository owner, user or organization"),
"repo": ("string", "Repository name"),
},
["owner", "repo"],
),
(
"list_pull_requests",
"List pull requests in a repository with filters for state, base branch, head branch and author. Includes review state, mergeability and CI status summary.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"state": ("string", "open, closed or all"),
"base": ("string", "Filter by base branch"),
"author": ("string", "Filter by author login"),
},
["owner", "repo"],
),
(
"get_pull_request",
"Get a pull request including body, commits, changed files with patch hunks, review comments, requested reviewers and status checks.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"number": ("integer", "Pull request number"),
},
["owner", "repo", "number"],
),
(
"create_pull_request",
"Open a pull request from a head branch into a base branch. Supports draft pull requests, maintainer edits and an initial set of reviewers and labels.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"title": ("string", "Pull request title"),
"head": ("string", "Branch with your changes"),
"base": ("string", "Branch to merge into"),
"body": ("string", "Markdown description"),
"draft": ("boolean", "Open as a draft"),
},
["owner", "repo", "title", "head", "base"],
),
(
"merge_pull_request",
"Merge a pull request using merge, squash or rebase. Fails if required checks or reviews are missing unless the caller can bypass branch protection.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"number": ("integer", "Pull request number"),
"method": ("string", "merge, squash or rebase"),
"commit_title": ("string", "Title for the merge commit"),
},
["owner", "repo", "number"],
),
(
"list_issues",
"List issues with filters for labels, assignee, milestone, state and creation date. Pull requests are excluded unless requested.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"labels": ("string", "Comma-separated label names"),
"assignee": ("string", "Assignee login, 'none' or '*'"),
"state": ("string", "open, closed or all"),
},
["owner", "repo"],
),
(
"create_issue",
"Create an issue with title, body, labels, assignees and milestone.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"title": ("string", "Issue title"),
"body": ("string", "Markdown body"),
"labels": ("array", "Label names"),
"assignees": ("array", "Assignee logins"),
},
["owner", "repo", "title"],
),
(
"add_issue_comment",
"Add a comment to an issue or pull request conversation.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"number": ("integer", "Issue or pull request number"),
"body": ("string", "Markdown comment"),
},
["owner", "repo", "number", "body"],
),
(
"get_file_contents",
"Read a file or list a directory at a ref. Returns decoded content for text files and metadata for binaries.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"path": ("string", "Path within the repository"),
"ref": ("string", "Branch, tag or commit SHA"),
},
["owner", "repo", "path"],
),
(
"list_commits",
"List commits on a branch or touching a path, newest first, with author, message and verification status.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"sha": ("string", "Branch or commit to start from"),
"path": ("string", "Only commits touching this path"),
"since": ("string", "ISO 8601 timestamp"),
},
["owner", "repo"],
),
(
"get_workflow_runs",
"List GitHub Actions workflow runs with status, conclusion, triggering event, branch and timing.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"workflow": ("string", "Workflow file name or ID"),
"branch": ("string", "Filter by branch"),
"status": ("string", "queued, in_progress, completed, failure, success"),
},
["owner", "repo"],
),
(
"get_job_logs",
"Download the log of one workflow job, optionally only the failing step.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"job_id": ("integer", "Workflow job ID"),
"failed_only": ("boolean", "Return only the failing step"),
},
["owner", "repo", "job_id"],
),
(
"create_branch",
"Create a branch from an existing ref.",
{
"owner": ("string", "Repository owner"),
"repo": ("string", "Repository name"),
"branch": ("string", "New branch name"),
"from_ref": ("string", "Branch, tag or SHA to branch from"),
},
["owner", "repo", "branch"],
),
(
"search_code",
"Search code across repositories with GitHub code search syntax. Returns file paths, repository and matching fragments.",
{"query": ("string", "Code search query"), "per_page": ("integer", "Results per page")},
["query"],
),
],
"jira": [
(
"search_issues",
"Search Jira issues with JQL. Returns key, summary, status, assignee, priority, labels and updated time for each match.",
{
"jql": ("string", "JQL query, e.g. 'project = BENCH AND status = Open'"),
"max_results": ("integer", "Maximum issues to return"),
"fields": ("array", "Fields to include"),
},
["jql"],
),
(
"get_issue",
"Get one Jira issue with description, comments, status history, linked issues, components, fix versions and custom fields.",
{
"issue_key": ("string", "Issue key, e.g. BENCH-42"),
"expand": ("string", "Extra sections such as changelog or renderedFields"),
},
["issue_key"],
),
(
"create_issue",
"Create a Jira issue in a project with type, summary, description, priority, labels and assignee.",
{
"project": ("string", "Project key"),
"issue_type": ("string", "Bug, Task, Story or Epic"),
"summary": ("string", "One-line summary"),
"description": ("string", "Description in Jira markdown"),
"priority": ("string", "Highest, High, Medium, Low"),
"labels": ("array", "Labels"),
},
["project", "issue_type", "summary"],
),
(
"update_issue",
"Update fields on an issue: summary, description, labels, priority, assignee or custom fields.",
{"issue_key": ("string", "Issue key"), "fields": ("object", "Field name to new value")},
["issue_key", "fields"],
),
(
"add_comment",
"Add a comment to a Jira issue. Supports Jira markdown and @mentions.",
{
"issue_key": ("string", "Issue key, e.g. BENCH-42"),
"body": ("string", "Comment text"),
},
["issue_key", "body"],
),
(
"transition_issue",
"Move an issue through its workflow, for example To Do -> In Progress -> Done, with an optional resolution and comment.",
{
"issue_key": ("string", "Issue key"),
"transition": ("string", "Transition name or ID"),
"resolution": ("string", "Resolution when closing"),
"comment": ("string", "Comment to add with the transition"),
},
["issue_key", "transition"],
),
(
"assign_issue",
"Assign an issue to a user, or unassign it.",
{
"issue_key": ("string", "Issue key"),
"assignee": ("string", "Account ID, or null to unassign"),
},
["issue_key"],
),
(
"list_sprints",
"List sprints on a board with state and dates.",
{
"board_id": ("integer", "Agile board ID"),
"state": ("string", "active, future or closed"),
},
["board_id"],
),
(
"get_sprint_issues",
"List issues in a sprint with status and story points.",
{"sprint_id": ("integer", "Sprint ID"), "jql": ("string", "Extra JQL filter")},
["sprint_id"],
),
(
"link_issues",
"Link two issues with a relationship such as blocks, relates to or duplicates.",
{
"inward_issue": ("string", "Inward issue key"),
"outward_issue": ("string", "Outward issue key"),
"link_type": ("string", "Link type name"),
},
["inward_issue", "outward_issue", "link_type"],
),
(
"add_worklog",
"Log time spent on an issue.",
{
"issue_key": ("string", "Issue key"),
"time_spent": ("string", "Duration such as 2h 30m"),
"comment": ("string", "Work description"),
},
["issue_key", "time_spent"],
),
(
"get_project",
"Get a project's issue types, components, versions and workflow scheme.",
{"project": ("string", "Project key")},
["project"],
),
],
"slack": [
(
"post_message",
"Post a message to a Slack channel or thread. Supports mrkdwn formatting, blocks and unfurl settings.",
{
"channel": ("string", "Channel name like #eng-alerts or channel ID"),
"text": ("string", "Message text in mrkdwn"),
"thread_ts": ("string", "Reply in this thread"),
},
["channel", "text"],
),
(
"list_channels",
"List public and private channels the bot can see, with member counts and topics.",
{
"types": ("string", "public_channel, private_channel, mpim, im"),
"limit": ("integer", "Maximum channels"),
},
[],
),
(
"get_channel_history",
"Read recent messages from a channel, newest first.",
{
"channel": ("string", "Channel name or ID"),
"limit": ("integer", "Maximum messages"),
"oldest": ("string", "Only messages after this timestamp"),
},
["channel"],
),
(
"get_thread_replies",
"Read every reply in a message thread.",
{
"channel": ("string", "Channel ID"),
"thread_ts": ("string", "Parent message timestamp"),
},
["channel", "thread_ts"],
),
(
"search_messages",
"Search messages across the workspace with Slack search modifiers such as in:, from: and before:.",
{"query": ("string", "Search query"), "count": ("integer", "Results to return")},
["query"],
),
(
"add_reaction",
"Add an emoji reaction to a message.",
{
"channel": ("string", "Channel ID"),
"timestamp": ("string", "Message timestamp"),
"name": ("string", "Emoji name without colons"),
},
["channel", "timestamp", "name"],
),
(
"get_user_profile",
"Get a user's profile, title, time zone and status.",
{"user": ("string", "User ID or email")},
["user"],
),
(
"set_channel_topic",
"Set a channel's topic.",
{"channel": ("string", "Channel ID"), "topic": ("string", "New topic")},
["channel", "topic"],
),
(
"upload_file",
"Upload a file or snippet to one or more channels.",
{
"channels": ("array", "Channel IDs"),
"content": ("string", "File content"),
"filename": ("string", "File name"),
"title": ("string", "Title"),
},
["channels", "content"],
),
(
"schedule_message",
"Schedule a message for later delivery.",
{
"channel": ("string", "Channel ID"),
"text": ("string", "Message text"),
"post_at": ("integer", "Unix timestamp"),
},
["channel", "text", "post_at"],
),
],
"datadog": [
(
"query_metrics",
"Query a metric time series with Datadog query syntax over a time range. Returns points, unit and aggregation.",
{
"query": ("string", "e.g. avg:billing.api.latency{env:prod} by {endpoint}"),
"from_ts": ("integer", "Start, Unix seconds"),
"to_ts": ("integer", "End, Unix seconds"),
},
["query", "from_ts", "to_ts"],
),
(
"search_logs",
"Search logs with Datadog log query syntax, newest first, including attributes and tags.",
{
"query": ("string", "Log query, e.g. service:billing status:error"),
"from_time": ("string", "Relative or absolute start, e.g. now-1h"),
"limit": ("integer", "Maximum log events"),
},
["query"],
),
(
"list_monitors",
"List monitors with state, query, thresholds, tags and notification targets.",
{
"name": ("string", "Filter by name"),
"tags": ("string", "Comma-separated tags"),
"group_states": ("string", "alert, warn, no data, ok"),
},
[],
),
(
"get_monitor",
"Get one monitor's definition, current state per group and recent state changes.",
{"monitor_id": ("integer", "Monitor ID")},
["monitor_id"],
),
(
"mute_monitor",
"Mute a monitor, optionally for one scope and until a time.",
{
"monitor_id": ("integer", "Monitor ID"),
"scope": ("string", "Scope to mute"),
"end": ("integer", "Unix time to unmute"),
},
["monitor_id"],
),
(
"list_dashboards",
"List dashboards with title, author and URL.",
{"filter": ("string", "Title filter")},
[],
),
(
"get_apm_traces",
"Search APM traces by service, resource and duration, with span breakdown.",
{
"service": ("string", "Service name"),
"resource": ("string", "Resource name"),
"min_duration_ms": ("integer", "Minimum duration"),
},
["service"],
),
(
"list_incidents",
"List incidents with severity, state, commander and timeline summary.",
{
"state": ("string", "active, stable or resolved"),
"severity": ("string", "SEV-1 to SEV-5"),
},
[],
),
(
"create_event",
"Post an event to the event stream, for example a deploy marker.",
{
"title": ("string", "Event title"),
"text": ("string", "Event body"),
"tags": ("array", "Tags"),
},
["title", "text"],
),
(
"get_service_dependencies",
"Get upstream and downstream dependencies of a service from APM.",
{"service": ("string", "Service name"), "env": ("string", "Environment")},
["service"],
),
],
"pagerduty": [
(
"list_incidents",
"List PagerDuty incidents with urgency, status, service and assignments.",
{
"statuses": ("array", "triggered, acknowledged, resolved"),
"service_ids": ("array", "Service IDs"),
"since": ("string", "ISO 8601 start"),
},
[],
),
(
"get_incident",
"Get one incident with timeline, alerts, notes and responders.",
{"incident_id": ("string", "Incident ID")},
["incident_id"],
),
(
"acknowledge_incident",
"Acknowledge an incident on behalf of the caller.",
{"incident_id": ("string", "Incident ID")},
["incident_id"],
),
(
"resolve_incident",
"Resolve an incident with an optional resolution note.",
{"incident_id": ("string", "Incident ID"), "note": ("string", "Resolution note")},
["incident_id"],
),
(
"list_oncalls",
"List who is on call for schedules and escalation policies.",
{
"schedule_ids": ("array", "Schedule IDs"),
"since": ("string", "Start time"),
"until": ("string", "End time"),
},
[],
),
(
"add_incident_note",
"Add a note to an incident timeline.",
{"incident_id": ("string", "Incident ID"), "content": ("string", "Note text")},
["incident_id", "content"],
),
(
"list_services",
"List services with escalation policy and integrations.",
{"query": ("string", "Name filter")},
[],
),
(
"create_incident",
"Trigger a new incident on a service.",
{
"service_id": ("string", "Service ID"),
"title": ("string", "Incident title"),
"urgency": ("string", "high or low"),
"body": ("string", "Details"),
},
["service_id", "title"],
),
],
"confluence": [
(
"search_pages",
"Search Confluence pages with CQL, returning title, space, excerpt and last editor.",
{
"cql": ("string", "CQL query, e.g. space = ENG and text ~ 'discount'"),
"limit": ("integer", "Maximum results"),
},
["cql"],
),
(
"get_page",
"Get a page body in storage format with version, ancestors and labels.",
{
"page_id": ("string", "Page ID"),
"expand": ("string", "body.storage, version, ancestors"),
},
["page_id"],
),
(
"create_page",
"Create a page in a space, optionally under a parent page.",
{
"space": ("string", "Space key"),
"title": ("string", "Page title"),
"body": ("string", "Body in storage format"),
"parent_id": ("string", "Parent page ID"),
},
["space", "title", "body"],
),
(
"update_page",
"Update a page body; requires the next version number.",
{
"page_id": ("string", "Page ID"),
"title": ("string", "Title"),
"body": ("string", "New body"),
"version": ("integer", "Next version number"),
},
["page_id", "body", "version"],
),
(
"add_page_comment",
"Add a footer comment to a page.",
{"page_id": ("string", "Page ID"), "body": ("string", "Comment body")},
["page_id", "body"],
),
(
"list_spaces",
"List spaces with key, name, type and homepage.",
{"type": ("string", "global or personal"), "limit": ("integer", "Maximum spaces")},
[],
),
(
"get_page_children",
"List child pages of a page.",
{"page_id": ("string", "Page ID")},
["page_id"],
),
(
"add_label",
"Add labels to a page.",
{"page_id": ("string", "Page ID"), "labels": ("array", "Labels")},
["page_id", "labels"],
),
],
}
ISSUE = {
"key": "BENCH-42",
"summary": "Discount applied twice at checkout",
"status": "Open",
"priority": "High",
"description": (
"Customers with a 10% coupon are charged 81% of the price instead of 90%. "
"The bug is in shop/pricing.py, function apply_discount. "
"tests/test_pricing.py reproduces it. When fixed, comment on this issue with a one-line "
"summary of the fix and post a short note to the #eng-alerts Slack channel."
),
"comments": [],
}
def schema(params: dict, required: list) -> dict:
props = {}
for name, (typ, desc) in params.items():
p = {"type": typ, "description": desc}
if typ == "array":
p["items"] = {"type": "string"}
props[name] = p
return {"type": "object", "properties": props, "required": required}
TOOLS = [
{"name": n, "description": d, "inputSchema": schema(p, r)} for n, d, p, r in CATALOG[SERVICE]
]
def call(name: str, args: dict) -> str:
with open(CALL_LOG, "a") as fh:
fh.write(json.dumps({"service": SERVICE, "tool": name, "args": args}) + "\n")
if SERVICE == "jira" and name == "get_issue":
return json.dumps(ISSUE if args.get("issue_key") == "BENCH-42" else {"error": "not found"})
if SERVICE == "jira" and name == "search_issues":
return json.dumps(
{"issues": [{k: ISSUE[k] for k in ("key", "summary", "status", "priority")}]}
)
return json.dumps({"ok": True, "service": SERVICE, "tool": name})
def main() -> None:
for line in sys.stdin:
try:
msg = json.loads(line)
except ValueError:
continue
mid, method = msg.get("id"), msg.get("method")
if mid is None: # notification
continue
if method == "initialize":
result = {
"protocolVersion": msg.get("params", {}).get("protocolVersion", "2025-06-18"),
"capabilities": {"tools": {}},
"serverInfo": {"name": SERVICE, "version": "1.0.0"},
}
elif method == "tools/list":
result = {"tools": TOOLS}
elif method == "tools/call":
p = msg.get("params", {})
result = {
"content": [{"type": "text", "text": call(p.get("name"), p.get("arguments") or {})}]
}
elif method == "ping":
result = {}
else:
sys.stdout.write(
json.dumps(
{
"jsonrpc": "2.0",
"id": mid,
"error": {"code": -32601, "message": f"unknown method {method}"},
}
)
+ "\n"
)
sys.stdout.flush()
continue
sys.stdout.write(json.dumps({"jsonrpc": "2.0", "id": mid, "result": result}) + "\n")
sys.stdout.flush()
if __name__ == "__main__":
main()
+402
View File
@@ -0,0 +1,402 @@
#!/usr/bin/env python3
"""Claude Code native tool search vs Headroom server-side tool search.
python3 run.py --arms native,hr_server --reps 3 --model claude-sonnet-5-5
Every run is a fresh, isolated Claude Code (throwaway HOME, fresh copy of the fixture
repo, six fake enterprise MCP servers) doing the same task: read a Jira ticket, fix the
bug, run the tests, comment on the ticket, post to Slack. Usage is read from Claude
Code's own transcript (what the API billed), so the numbers include subagents.
Arms:
native Claude Code straight to api.anthropic.com, its own ToolSearch (default on)
eager Claude Code straight to Anthropic with ENABLE_TOOL_SEARCH=false (no deferral)
hr_client Claude Code -> Headroom, ENABLE_TOOL_SEARCH=true (today's `headroom wrap`)
hr_server Claude Code -> Headroom, ENABLE_TOOL_SEARCH=false; Headroom defers server-side
hr_hot as hr_server, but the MCP tools this developer used before stay loaded
(HEADROOM_TOOL_SEARCH_CORE_TOOLS): no lookup at all for routine tools
hr_ext as hr_server, plus the proxy env given with --proxy-env KEY=VALUE
(repeatable), e.g. to measure a proxy extension
Needs ANTHROPIC_API_KEY (or ~/env.txt). Results go to results/<timestamp>/.
"""
from __future__ import annotations
import argparse
import glob
import json
import os
import shutil
import socket
import statistics
import subprocess
import sys
import time
from pathlib import Path
HERE = Path(__file__).resolve().parent
REPO = HERE.parents[1]
SERVERS = ["github", "jira", "slack", "datadog", "pagerduty", "confluence"]
TASK = (
"Jira ticket BENCH-42 reports a pricing bug in this repository. Look the ticket up in Jira, "
"fix the bug, and run the tests with `python3 -m unittest`. Then search Datadog logs for "
"errors from service billing in the last hour, add a comment on BENCH-42 with a one-line "
"summary of the fix and the Datadog result, and post a short note about the fix to the "
"#eng-alerts Slack channel. Do not ask questions; just do it."
)
# Headroom's default resident set (headroom/proxy/helpers.py _TOOL_SEARCH_CORE_TOOLS) plus the
# MCP tools a developer doing this kind of work has used before: a learned working set.
CORE = [
"bash",
"bash_background",
"bash_background_output",
"bash_background_wait",
"bash_background_kill",
"read",
"write",
"edit",
"multiedit",
"apply_patch",
"glob",
"grep",
"task",
"todowrite",
"todoread",
"webfetch",
"question",
"skill",
"toolsearch",
]
HOT = [
"mcp__jira__get_issue",
"mcp__jira__add_comment",
"mcp__slack__post_message",
"mcp__datadog__search_logs",
]
PROXY_ENV = {
"hr_client": {},
"hr_server": {},
"hr_hot": {"HEADROOM_TOOL_SEARCH_CORE_TOOLS": ",".join(CORE + HOT)},
# As hr_server plus whatever --proxy-env adds, e.g. a proxy extension under test.
"hr_ext": {},
}
ALLOWED = ["Bash", "Read", "Edit", "Write", "Glob", "Grep", "ToolSearch"] + [
f"mcp__{s}" for s in SERVERS
]
# Billed input-equivalent weights (Anthropic): cache write 5m 1.25x, 1h 2x, read 0.1x.
W_5M, W_1H, W_READ = 1.25, 2.0, 0.1
def api_key() -> str:
if os.environ.get("ANTHROPIC_API_KEY"):
return os.environ["ANTHROPIC_API_KEY"]
for line in Path.home().joinpath("env.txt").read_text().splitlines():
line = line.strip().removeprefix("export ").strip()
if line.startswith("ANTHROPIC_API_KEY="):
return line.split("=", 1)[1].strip().strip("'\"")
sys.exit("ANTHROPIC_API_KEY not found")
def free_port() -> int:
with socket.socket() as s:
s.bind(("127.0.0.1", 0))
return s.getsockname()[1]
def start_proxy(out: Path, key: str, name: str, extra: dict) -> tuple[subprocess.Popen, int]:
port = free_port()
ws = out / f"headroom-workspace-{name}"
ws.mkdir(parents=True, exist_ok=True)
env = {
**os.environ,
"HEADROOM_WORKSPACE_DIR": str(ws),
"HEADROOM_TOOL_SEARCH": "1",
"HEADROOM_TELEMETRY": "off",
"ANTHROPIC_API_KEY": key,
**extra,
}
env.pop("ANTHROPIC_BASE_URL", None)
log = open(out / f"proxy-{name}.log", "w")
proc = subprocess.Popen(
[str(REPO / ".venv/bin/headroom"), "proxy", "--port", str(port)],
env=env,
stdout=log,
stderr=subprocess.STDOUT,
cwd=ws,
)
for _ in range(120):
try:
with socket.create_connection(("127.0.0.1", port), timeout=0.5):
return proc, port
except OSError:
time.sleep(0.5)
proc.kill()
sys.exit(f"proxy did not start; see {out / f'proxy-{name}.log'}")
def usage_from_transcripts(home: Path) -> dict:
seen, calls = set(), []
for f in glob.glob(str(home / ".claude/projects/*/**/*.jsonl"), recursive=True):
for line in open(f):
try:
r = json.loads(line)
except ValueError:
continue
m = r.get("message") or {}
if m.get("role") != "assistant" or not m.get("usage") or m.get("id") in seen:
continue
seen.add(m.get("id"))
u = m["usage"]
cc = u.get("cache_creation") or {}
w1h = cc.get("ephemeral_1h_input_tokens", 0)
w5m = cc.get("ephemeral_5m_input_tokens", u.get("cache_creation_input_tokens", 0) - w1h)
tool_names = [
b.get("name")
for b in m.get("content") or []
if isinstance(b, dict) and b.get("type") in ("tool_use", "server_tool_use")
]
calls.append(
{
"input": u.get("input_tokens", 0),
"w5m": w5m,
"w1h": w1h,
"read": u.get("cache_read_input_tokens", 0),
"output": u.get("output_tokens", 0),
"sidechain": bool(r.get("isSidechain")),
"tools": tool_names,
}
)
t = {k: sum(c[k] for c in calls) for k in ("input", "w5m", "w1h", "read", "output")}
t["api_calls"] = len(calls)
t["toolsearch_calls"] = sum(c["tools"].count("ToolSearch") for c in calls)
t["toolsearch_only_turns"] = sum(
1 for c in calls if c["tools"] and set(c["tools"]) == {"ToolSearch"}
)
t["server_searches"] = sum(
1 for c in calls for n in c["tools"] if n and n.startswith("tool_search_tool")
)
t["billed_input_equiv"] = round(
t["input"] + W_5M * t["w5m"] + W_1H * t["w1h"] + W_READ * t["read"]
)
return t
def check_task(work: Path, calls_log: Path) -> dict:
tests = subprocess.run(
[sys.executable, "-m", "unittest", "-q"], cwd=work, capture_output=True, text=True
)
calls = (
[json.loads(line) for line in calls_log.read_text().splitlines()]
if calls_log.exists()
else []
)
did = lambda svc, tool: any(c["service"] == svc and c["tool"] == tool for c in calls) # noqa: E731
return {
"tests_pass": tests.returncode == 0,
"read_ticket": did("jira", "get_issue"), # a search result has no description
"searched_logs": did("datadog", "search_logs"),
"commented": did("jira", "add_comment"),
"posted_slack": did("slack", "post_message"),
"mcp_calls": len(calls),
}
def run_one(
arm: str, rep: int, out: Path, key: str, model: str, port: int | None, context_kb: int
) -> dict:
d = out / f"{arm}-{rep}"
home, work = d / "home", d / "work"
home.mkdir(parents=True)
shutil.copytree(HERE / "fixture", work)
task = TASK
if context_kb: # put the MCP lookups deep in the session, where real ones happen
(work / "docs").mkdir()
(work / "docs/ARCHITECTURE.md").write_text(architecture_doc(context_kb))
task = "First read docs/ARCHITECTURE.md in full (all of it, in chunks if needed). " + TASK
subprocess.run(["git", "init", "-q"], cwd=work)
subprocess.run(["git", "add", "-A"], cwd=work)
subprocess.run(
["git", "-c", "user.email=b@b", "-c", "user.name=b", "commit", "-qm", "init"], cwd=work
)
calls_log = d / "mcp_calls.jsonl"
cfg = {
"mcpServers": {
s: {"command": sys.executable, "args": [str(HERE / "mcp_server.py"), s, str(calls_log)]}
for s in SERVERS
}
}
(d / "mcp.json").write_text(json.dumps(cfg))
env = {
k: v
for k, v in os.environ.items()
if not k.startswith(("ANTHROPIC_", "CLAUDE_", "ENABLE_TOOL_SEARCH", "HEADROOM_"))
}
env.update(
{
"HOME": str(home),
"ANTHROPIC_API_KEY": key,
"DISABLE_AUTOUPDATER": "1",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
"DISABLE_TELEMETRY": "1",
}
)
if arm == "eager":
env["ENABLE_TOOL_SEARCH"] = "false"
elif arm in PROXY_ENV:
env["ANTHROPIC_BASE_URL"] = f"http://127.0.0.1:{port}"
env["ENABLE_TOOL_SEARCH"] = "true" if arm == "hr_client" else "false"
cmd = [
"claude",
"-p",
task,
"--model",
model,
"--mcp-config",
str(d / "mcp.json"),
"--strict-mcp-config",
"--output-format",
"json",
"--allowedTools",
*ALLOWED,
]
t0 = time.time()
p = subprocess.run(cmd, cwd=work, env=env, capture_output=True, text=True, timeout=900)
wall = time.time() - t0
(d / "stdout.json").write_text(p.stdout)
(d / "stderr.txt").write_text(p.stderr)
try:
cc = json.loads(p.stdout)
except ValueError:
cc = {}
row = {
"arm": arm,
"rep": rep,
"wall_s": round(wall, 1),
"exit": p.returncode,
"cc_cost_usd": cc.get("total_cost_usd"),
"cc_turns": cc.get("num_turns"),
**usage_from_transcripts(home),
**check_task(work, calls_log),
}
# A session that errored out does not pass, even if it got the actions done.
row["task_ok"] = row["exit"] == 0 and all(
row[k] for k in ("tests_pass", "read_ticket", "searched_logs", "commented", "posted_slack")
)
return row
def architecture_doc(kb: int) -> str:
"""Deterministic, non-repetitive prose so compression cannot trivially erase it."""
import random
rng = random.Random(42)
words = (
"ledger invoice coupon tenant region shard replica queue retry idempotency webhook settlement "
"refund currency rounding audit partition latency throughput cache eviction migration rollout "
"flag canary checkout cart session token gateway schema index backfill reconciliation"
).split()
out, size, n = ["# Billing platform architecture\n"], 0, 0
while size < kb * 1024:
n += 1
para = f"\n## Section {n}\n" + " ".join(rng.choice(words) for _ in range(120)) + ".\n"
out.append(para)
size += len(para)
return "".join(out)
def summarize(rows: list[dict]) -> str:
keys = [
"task_ok",
"cc_cost_usd",
"billed_input_equiv",
"output",
"api_calls",
"toolsearch_only_turns",
"server_searches",
"read",
"w5m",
"w1h",
"input",
"wall_s",
]
lines = ["| arm | n | " + " | ".join(keys) + " |", "|" + "---|" * (len(keys) + 2)]
for arm in dict.fromkeys(r["arm"] for r in rows):
rs = [r for r in rows if r["arm"] == arm]
cells = []
for k in keys:
vals = [r[k] for r in rs if r.get(k) is not None]
if k == "task_ok":
cells.append(f"{sum(vals)}/{len(rs)}")
elif not vals:
cells.append("-")
else:
med = statistics.median(vals)
cells.append(
f"{med:.3f}"
if k == "cc_cost_usd"
else f"{med:,.0f}"
if k != "wall_s"
else f"{med:.0f}"
)
lines.append(f"| {arm} | {len(rs)} | " + " | ".join(cells) + " |")
return "\n".join(lines) + "\n\n(median per run)"
def main() -> None:
ap = argparse.ArgumentParser()
ap.add_argument("--arms", default="native,hr_server,hr_client,eager")
ap.add_argument("--reps", type=int, default=3)
ap.add_argument("--model", default="claude-sonnet-5-5")
ap.add_argument(
"--context-kb", type=int, default=0, help="add a doc of this size to read before the task"
)
ap.add_argument(
"--warmup",
action="store_true",
help="run each arm once first and discard it (warms caches)",
)
ap.add_argument(
"--proxy-env",
action="append",
default=[],
metavar="KEY=VALUE",
help="extra proxy environment for the hr_ext arm (repeatable)",
)
ap.add_argument("--out", default=str(HERE / "results" / time.strftime("%Y%m%d-%H%M%S")))
a = ap.parse_args()
out = Path(a.out)
out.mkdir(parents=True, exist_ok=True)
key = api_key()
arms = a.arms.split(",")
PROXY_ENV["hr_ext"] = dict(kv.split("=", 1) for kv in a.proxy_env)
proxies = {arm: start_proxy(out, key, arm, PROXY_ENV[arm]) for arm in arms if arm in PROXY_ENV}
rows = []
try:
if a.warmup:
for arm in arms:
run_one(arm, 0, out, key, a.model, proxies.get(arm, (None, None))[1], a.context_kb)
for rep in range(1, a.reps + 1): # interleave arms so drift hits every arm alike
for arm in arms:
row = run_one(
arm, rep, out, key, a.model, proxies.get(arm, (None, None))[1], a.context_kb
)
rows.append(row)
print(json.dumps(row), flush=True)
(out / "rows.jsonl").open("a").write(json.dumps(row) + "\n")
finally:
for proc, _ in proxies.values():
proc.terminate()
s = summarize(rows)
(out / "summary.md").write_text(s + "\n")
print(s)
if __name__ == "__main__":
main()
@@ -9,6 +9,7 @@
//! - **SearchResults**: grep / ripgrep output (`file:line:content`)
//! - **BuildOutput**: Compiler / test / lint logs
//! - **GitDiff**: Unified diff format → `DiffCompressor`
//! - **Tabular**: lossless route for tables and human-readable Git status
//! - **Html**: Web pages (needs extraction, not compression)
//! - **PlainText**: Generic fallback
//!
@@ -37,6 +38,7 @@ pub enum ContentType {
BuildOutput,
GitDiff,
Html,
Tabular,
PlainText,
}
@@ -50,13 +52,14 @@ impl ContentType {
/// extending this array is caught by the length annotation, and the
/// exhaustive `match` in [`ContentType::as_str`] forces the author
/// into this file in the first place.
pub const ALL: [ContentType; 7] = [
pub const ALL: [ContentType; 8] = [
ContentType::JsonArray,
ContentType::SourceCode,
ContentType::SearchResults,
ContentType::BuildOutput,
ContentType::GitDiff,
ContentType::Html,
ContentType::Tabular,
ContentType::PlainText,
];
@@ -69,6 +72,7 @@ impl ContentType {
ContentType::BuildOutput => "build",
ContentType::GitDiff => "diff",
ContentType::Html => "html",
ContentType::Tabular => "tabular",
ContentType::PlainText => "text",
}
}
@@ -86,6 +90,7 @@ impl ContentType {
ContentType::BuildOutput => "build_output",
ContentType::GitDiff => "git_diff",
ContentType::Html => "html",
ContentType::Tabular => "tabular",
ContentType::PlainText => "plain_text",
}
}
@@ -287,6 +292,93 @@ static HTML_STRUCTURAL_TAGS: LazyLock<Regex> = LazyLock::new(|| {
.unwrap()
});
#[derive(Clone, Copy, PartialEq, Eq)]
enum GitStatusSection {
Staged,
Unstaged,
Untracked,
Unmerged,
}
fn try_detect_git_status(content: &str) -> Option<DetectionResult> {
let mut lines = content.lines();
let first = lines.next()?;
if !first.starts_with("On branch ")
&& !first.starts_with("HEAD detached at ")
&& !first.starts_with("HEAD detached from ")
{
return None;
}
let mut has_heading = false;
let mut has_path = false;
let mut section = None;
for line in lines {
section = match line {
"Changes to be committed:" => {
has_heading = true;
Some(GitStatusSection::Staged)
}
"Changes not staged for commit:" => {
has_heading = true;
Some(GitStatusSection::Unstaged)
}
"Untracked files:" => {
has_heading = true;
Some(GitStatusSection::Untracked)
}
"Unmerged paths:" => {
has_heading = true;
Some(GitStatusSection::Unmerged)
}
_ => section,
};
if section == Some(GitStatusSection::Untracked)
&& line
.strip_prefix('\t')
.is_some_and(|path| !path.trim().is_empty())
{
has_path = true;
} else if matches!(
section,
Some(
GitStatusSection::Staged | GitStatusSection::Unstaged | GitStatusSection::Unmerged
)
) {
let Some((state, path)) = line.trim_start().split_once(": ") else {
continue;
};
if !path.trim().is_empty()
&& matches!(
state,
"new file"
| "modified"
| "deleted"
| "renamed"
| "copied"
| "typechange"
| "both modified"
| "both added"
| "both deleted"
| "added by us"
| "deleted by us"
| "added by them"
| "deleted by them"
)
{
has_path = true;
}
}
}
(has_heading && has_path).then(|| {
let mut metadata = Map::new();
metadata.insert("format".into(), Value::String("git_status".into()));
DetectionResult::new(ContentType::Tabular, 1.0, metadata)
})
}
// ─── Public entry point ────────────────────────────────────────────────
/// Detect the type of `content` for routing. Mirrors Python's
@@ -297,10 +389,11 @@ static HTML_STRUCTURAL_TAGS: LazyLock<Regex> = LazyLock::new(|| {
/// 2. JSON array (highest priority for `SmartCrusher`)
/// 3. Git diff (≥ 0.7 confidence required)
/// 4. HTML (≥ 0.7 confidence required)
/// 5. Search results (≥ 0.6 confidence required)
/// 6. Build / log output (≥ 0.5 confidence required)
/// 7. Source code (≥ 0.5 confidence required)
/// 8. Fallback to `PlainText` confidence 0.5
/// 5. Human-readable Git status → `Tabular` (lossless)
/// 6. Search results (≥ 0.6 confidence required)
/// 7. Build / log output (≥ 0.5 confidence required)
/// 8. Source code (≥ 0.5 confidence required)
/// 9. Fallback to `PlainText` confidence 0.5
pub fn detect_content_type(content: &str) -> DetectionResult {
if content.is_empty() || content.trim().is_empty() {
return DetectionResult::plain_text(0.0);
@@ -319,6 +412,10 @@ pub fn detect_content_type(content: &str) -> DetectionResult {
return r;
}
}
if let Some(r) = try_detect_git_status(content) {
return r;
}
if let Some(r) = try_detect_search(content) {
if r.confidence >= 0.6 {
return r;
@@ -680,6 +777,57 @@ mod tests {
assert!(r.confidence >= 0.6);
}
#[test]
fn git_status_with_staged_unstaged_and_untracked_paths_is_tabular() {
let content = "\
On branch feature/status
Changes to be committed:
(use \"git restore --staged <file>...\" to unstage)
\tnew file: staged file.txt
Changes not staged for commit:
(use \"git add <file>...\" to update what will be committed)
\tmodified: path with spaces.txt
Untracked files:
(use \"git add <file>...\" to include in what will be committed)
\tuntracked path.txt
";
let result = detect_content_type(content);
assert_eq!(result.content_type, ContentType::Tabular);
assert_eq!(
result.metadata.get("format").and_then(Value::as_str),
Some("git_status")
);
}
#[test]
fn untracked_only_git_status_is_tabular() {
let content = "\
On branch feature/status
Untracked files:
(use \"git add <file>...\" to include in what will be committed)
\tuntracked path with spaces.txt
\tuntracked α.rs
";
let result = detect_content_type(content);
assert_eq!(result.content_type, ContentType::Tabular);
assert_eq!(
result.metadata.get("format").and_then(Value::as_str),
Some("git_status")
);
}
#[test]
fn ordinary_bullet_list_is_not_git_status() {
let prose = "The branch has many changes:\n- modified: item one\n- modified: item two";
assert_eq!(
detect_content_type(prose).content_type,
ContentType::PlainText
);
}
#[test]
fn git_diff_detected() {
let content = "\
@@ -189,6 +189,9 @@ const THRESHOLD_SOURCE_CODE: usize = 2048;
/// gate fires before dispatch, so sub-threshold prose never reaches the
/// Kompress arm wired below.
const THRESHOLD_PLAIN_TEXT: usize = 5120;
/// Tabular text has no native compressor; keep it lossless.
const THRESHOLD_TABULAR: usize = 512;
/// HTML blocks have no compressor. 512 was PlainText's pre-PR-B4 value;
/// HTML deliberately keeps it rather than following PlainText to 5120,
/// because `REALIGNMENT/04` pins no HTML threshold — when an HTML
@@ -212,6 +215,7 @@ pub const fn threshold_for(content_type: ContentType) -> usize {
ContentType::SourceCode => THRESHOLD_SOURCE_CODE,
ContentType::PlainText => THRESHOLD_PLAIN_TEXT,
ContentType::Html => THRESHOLD_HTML,
ContentType::Tabular => THRESHOLD_TABULAR,
}
}
@@ -1732,6 +1736,12 @@ fn dispatch_compressor(text: &str, content_type: ContentType) -> DispatchResult
// when the model isn't cache-resident, hasn't finished its
// background initialization yet, or the `ml` feature is off —
// no network call and no model build ever happens on this path.
// This dispatcher has no tabular compressor; preserve these rows
// instead of sending structured output through lossy Kompress.
ContentType::Tabular => DispatchResult::NoOp {
content_type: content_type.as_str(),
},
ContentType::PlainText => kompress_or_noop(text, content_type),
// No HTML compressor on the Rust side; pages are handled by
// upstream extractors, not the proxy.
+8
View File
@@ -56,6 +56,14 @@ aws-smithy-runtime-api = { workspace = true }
# transitively pulled in by `aws-smithy-*` (so this is not an
# additional cold dep — promoting to a direct one for clarity).
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"
# 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
+73 -13
View File
@@ -51,10 +51,12 @@ use url::Url;
use crate::bedrock::envelope::BedrockEnvelope;
use crate::bedrock::sigv4::{sign_request, SigningInputs};
use crate::bedrock::CompressionStats;
use crate::compression::{
compress_anthropic_request, Outcome as AnthropicOutcome, PassthroughReason,
};
use crate::headers::filter_response_headers;
use crate::observability::{capture, ledger};
use crate::observability::{observe_bedrock_invoke_latency, record_bedrock_invoke};
use crate::proxy::AppState;
use crate::upstream_path::append_segments;
@@ -175,8 +177,17 @@ pub async fn handle_invoke(
"bedrock invoke route received request"
);
// Savings ledger: constructed at handler ENTRY so every exit —
// including proxy-side rejections (bad action path, missing
// credentials, SigV4 failure) — produces exactly one record. A
// credentials outage must show in /stats as a failure spike,
// not as zero traffic. `forward_http` gives its 413 rejections
// the same treatment.
let mut pending_stats =
capture::start_pending(&state, ledger::provider::BEDROCK, &model_id, &request_id);
let is_anthropic = is_anthropic_model_id(&model_id);
let outbound_body: Bytes = if is_anthropic {
let (outbound_body, compression_stats): (Bytes, CompressionStats) = if is_anthropic {
run_anthropic_compression(&body, &state, auth_mode, &request_id)
} else {
tracing::info!(
@@ -186,8 +197,15 @@ pub async fn handle_invoke(
reason = "non_anthropic_vendor",
"bedrock invoke: skipping live-zone compression for non-anthropic vendor"
);
body.clone()
(body.clone(), CompressionStats::default())
};
if let Some(p) = pending_stats.as_mut() {
p.set_compression(
compression_stats.tokens_before,
compression_stats.tokens_after,
compression_stats.transforms,
);
}
// Resolve the Bedrock action from the inbound path so `/converse`
// forwards to the upstream Converse endpoint instead of `/invoke`.
@@ -202,6 +220,7 @@ pub async fn handle_invoke(
path = %uri.path(),
"bedrock invoke: unrecognized action path"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::BAD_REQUEST,
"bedrock_invoke_action_invalid",
@@ -235,6 +254,7 @@ pub async fn handle_invoke(
error = %msg,
"bedrock invoke: failed to construct upstream URL"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::INTERNAL_SERVER_ERROR,
"bedrock_endpoint_invalid",
@@ -253,6 +273,7 @@ pub async fn handle_invoke(
model_id = %model_id,
"bedrock invoke: refusing to forward without AWS credentials"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::INTERNAL_SERVER_ERROR,
"bedrock_credentials_missing",
@@ -288,6 +309,7 @@ pub async fn handle_invoke(
error = %e,
"bedrock invoke: SigV4 signing failed; refusing to forward"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::INTERNAL_SERVER_ERROR,
"bedrock_sigv4_failed",
@@ -329,6 +351,7 @@ pub async fn handle_invoke(
error = %e,
"bedrock invoke: invalid HTTP method"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::BAD_REQUEST,
"bedrock_invalid_method",
@@ -348,6 +371,9 @@ pub async fn handle_invoke(
let upstream_resp = match upstream_resp {
Ok(r) => r,
Err(e) => {
if let Some(p) = pending_stats.take() {
p.finalize_failed();
}
tracing::warn!(
event = "bedrock_upstream_error",
request_id = %request_id,
@@ -365,6 +391,11 @@ pub async fn handle_invoke(
let status =
StatusCode::from_u16(upstream_resp.status().as_u16()).unwrap_or(StatusCode::BAD_GATEWAY);
if !status.is_success() {
if let Some(p) = pending_stats.as_mut() {
p.mark_failed();
}
}
let resp_headers = filter_response_headers(upstream_resp.headers());
tracing::info!(
@@ -376,10 +407,23 @@ pub async fn handle_invoke(
"bedrock invoke: response forwarded"
);
// Stream the response body back without buffering.
let stream = upstream_resp
.bytes_stream()
.map(|r| r.map_err(std::io::Error::other));
// Stream the response body back without buffering. When the
// savings ledger is recording, tee the bytes into a bounded
// capture task that parses the sync response's usage block
// (InvokeModel snake_case / Converse camelCase) at body end —
// best-effort, never blocking the client byte path.
let capture_tx = pending_stats
.take()
.map(|p| capture::spawn_json_usage_capture(capture::ResponseShape::Bedrock, p));
let stream = upstream_resp.bytes_stream().map(move |r| match r {
Ok(b) => {
if let Some(tx) = &capture_tx {
let _ = tx.try_send(b.clone());
}
Ok(b)
}
Err(e) => Err(std::io::Error::other(e)),
});
let body_out = Body::from_stream(stream);
let mut builder = Response::builder().status(status);
@@ -417,7 +461,7 @@ fn run_anthropic_compression(
state: &AppState,
_auth_mode: AuthMode,
request_id: &str,
) -> Bytes {
) -> (Bytes, CompressionStats) {
// Detect envelope shape. A parseable InvokeModel envelope takes the
// re-emit path below (anthropic_version pinned first); a non-envelope
// body (e.g. a Converse-shaped payload) still runs through the
@@ -453,7 +497,7 @@ fn run_anthropic_compression(
request_id,
);
match outcome {
AnthropicOutcome::NoCompression => body.clone(),
AnthropicOutcome::NoCompression => (body.clone(), CompressionStats::default()),
AnthropicOutcome::Passthrough { reason } => {
tracing::info!(
event = "bedrock_compression_passthrough",
@@ -464,15 +508,26 @@ fn run_anthropic_compression(
// The compressor's passthrough variants all leave bytes
// unchanged. Forward the original.
let _ = (PassthroughReason::ModeOff, PassthroughReason::NoMessages); // pin types
body.clone()
(body.clone(), CompressionStats::default())
}
AnthropicOutcome::Compressed { body: new_body, .. } => {
AnthropicOutcome::Compressed {
body: new_body,
tokens_before,
tokens_after,
strategies_applied,
..
} => {
let stats = CompressionStats {
tokens_before: tokens_before as u64,
tokens_after: tokens_after as u64,
transforms: strategies_applied.iter().map(|s| s.to_string()).collect(),
};
if parsed_envelope {
// Defence-in-depth: re-emit so anthropic_version is the
// first key. With preserve_order this is a no-op on the
// happy path.
match BedrockEnvelope::ensure_anthropic_version_first(&new_body) {
Ok(b) => b,
Ok(b) => (b, stats),
Err(e) => {
tracing::error!(
event = "bedrock_envelope_reemit_failed",
@@ -480,11 +535,13 @@ fn run_anthropic_compression(
error = %e,
"bedrock invoke: failed to re-emit envelope; falling back to original body"
);
body.clone()
// Original bytes forwarded ⇒ no compression
// happened as far as the wire is concerned.
(body.clone(), CompressionStats::default())
}
}
} else {
new_body
(new_body, stats)
}
}
}
@@ -631,6 +688,7 @@ mod tests {
vertex_token_source: std::sync::Arc::new(crate::vertex::StaticTokenSource::new(
"test".to_string(),
)),
stats: std::sync::Arc::new(ledger::Ledger::in_memory()),
};
let uri: Uri = "/model/anthropic.claude-3-haiku-20240307-v1:0/converse"
.parse()
@@ -669,6 +727,7 @@ mod tests {
vertex_token_source: std::sync::Arc::new(crate::vertex::StaticTokenSource::new(
"test".to_string(),
)),
stats: std::sync::Arc::new(ledger::Ledger::in_memory()),
};
let uri: Uri = "/model/anthropic.claude-3-haiku-20240307-v1:0/invoke"
.parse()
@@ -705,6 +764,7 @@ mod tests {
vertex_token_source: std::sync::Arc::new(crate::vertex::StaticTokenSource::new(
"test".to_string(),
)),
stats: std::sync::Arc::new(ledger::Ledger::in_memory()),
};
let uri: Uri = "/model/anthropic.claude-3-haiku-20240307-v1:0/invoke"
.parse()
@@ -61,10 +61,13 @@ use crate::bedrock::eventstream_to_sse::{
translate_message, OutputMode, TranslateError, TranslateOutcome,
};
use crate::bedrock::sigv4::{sign_request, SigningInputs};
use crate::bedrock::CompressionStats;
use crate::compression::{
compress_anthropic_request, Outcome as AnthropicOutcome, PassthroughReason,
};
use crate::headers::filter_response_headers;
use crate::observability::capture::TEE_QUEUE_DEPTH as SSE_PARSER_QUEUE_DEPTH;
use crate::observability::{capture, ledger};
use crate::observability::{
observe_bedrock_invoke_latency, record_bedrock_eventstream_message, record_bedrock_invoke,
};
@@ -153,9 +156,14 @@ pub async fn handle_invoke_streaming(
"bedrock invoke-with-response-stream route received request"
);
// Constructed at handler ENTRY so every exit — including
// proxy-side rejections — records exactly once.
let mut pending_stats =
capture::start_pending(&state, ledger::provider::BEDROCK, &model_id, &request_id);
// 1. Live-zone compression for Anthropic-shape bodies (same as D1).
let is_anthropic = is_anthropic_model_id(&model_id);
let outbound_body: Bytes = if is_anthropic {
let (outbound_body, compression_stats): (Bytes, CompressionStats) = if is_anthropic {
run_anthropic_compression(&body, &state, auth_mode, &request_id)
} else {
tracing::info!(
@@ -165,8 +173,15 @@ pub async fn handle_invoke_streaming(
reason = "non_anthropic_vendor",
"bedrock invoke-streaming: skipping compression for non-anthropic vendor"
);
body.clone()
(body.clone(), CompressionStats::default())
};
if let Some(p) = pending_stats.as_mut() {
p.set_compression(
compression_stats.tokens_before,
compression_stats.tokens_after,
compression_stats.transforms,
);
}
// 2. Resolve the Bedrock streaming action from the inbound path and
// build the upstream URL.
@@ -179,6 +194,7 @@ pub async fn handle_invoke_streaming(
path = %uri.path(),
"bedrock invoke-streaming: unrecognized streaming action path"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::BAD_REQUEST,
"bedrock_streaming_action_invalid",
@@ -209,6 +225,7 @@ pub async fn handle_invoke_streaming(
error = %msg,
"bedrock invoke-streaming: failed to construct upstream URL"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::INTERNAL_SERVER_ERROR,
"bedrock_endpoint_invalid",
@@ -227,6 +244,7 @@ pub async fn handle_invoke_streaming(
model_id = %model_id,
"bedrock invoke-streaming: refusing to forward without AWS credentials"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::INTERNAL_SERVER_ERROR,
"bedrock_credentials_missing",
@@ -261,6 +279,7 @@ pub async fn handle_invoke_streaming(
error = %e,
"bedrock invoke-streaming: SigV4 signing failed"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::INTERNAL_SERVER_ERROR,
"bedrock_sigv4_failed",
@@ -298,6 +317,7 @@ pub async fn handle_invoke_streaming(
error = %e,
"bedrock invoke-streaming: invalid HTTP method"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::BAD_REQUEST,
"bedrock_invalid_method",
@@ -317,6 +337,9 @@ pub async fn handle_invoke_streaming(
let upstream_resp = match upstream_resp {
Ok(r) => r,
Err(e) => {
if let Some(p) = pending_stats.take() {
p.finalize_failed();
}
tracing::warn!(
event = "bedrock_upstream_error",
request_id = %request_id,
@@ -334,6 +357,11 @@ pub async fn handle_invoke_streaming(
let status =
StatusCode::from_u16(upstream_resp.status().as_u16()).unwrap_or(StatusCode::BAD_GATEWAY);
if !status.is_success() {
if let Some(p) = pending_stats.as_mut() {
p.mark_failed();
}
}
let upstream_content_type = upstream_resp
.headers()
.get(http::header::CONTENT_TYPE)
@@ -373,10 +401,22 @@ pub async fn handle_invoke_streaming(
// Even here we drop content-length: the proxy streams the
// body and reqwest's transparent decompression may already
// have changed the byte length on the way in.
// Usage capture: this is typically an error envelope (the
// pending event is already marked failed on non-2xx); parse
// it as JSON anyway so a 2xx JSON body still yields usage.
resp_headers.remove(http::header::CONTENT_LENGTH);
let stream = upstream_resp
.bytes_stream()
.map(|r| r.map_err(std::io::Error::other));
let capture_tx = pending_stats
.take()
.map(|p| capture::spawn_json_usage_capture(capture::ResponseShape::Bedrock, p));
let stream = upstream_resp.bytes_stream().map(move |r| match r {
Ok(b) => {
if let Some(tx) = &capture_tx {
let _ = tx.try_send(b.clone());
}
Ok(b)
}
Err(e) => Err(std::io::Error::other(e)),
});
let body_out = Body::from_stream(stream);
return finish(status, resp_headers, body_out, &request_id);
}
@@ -410,7 +450,20 @@ pub async fn handle_invoke_streaming(
resp_headers.insert(http::header::CONTENT_TYPE, v);
}
}
let body_out = Body::from_stream(upstream_stream);
// Usage capture: nothing else parses the frames in
// passthrough mode, so tee the raw bytes into a bounded
// EventStream telemetry parser (chunk / metadata usage;
// finalizes the ledger event when the stream closes).
let capture_tx = pending_stats
.take()
.map(capture::spawn_eventstream_usage_capture);
let teed = upstream_stream.map(move |r| {
if let (Ok(b), Some(tx)) = (&r, &capture_tx) {
let _ = tx.try_send(b.clone());
}
r
});
let body_out = Body::from_stream(teed);
finish(status, resp_headers, body_out, &request_id)
}
OutputMode::Sse => {
@@ -429,7 +482,8 @@ pub async fn handle_invoke_streaming(
model_id.clone(),
region.clone(),
);
let translated = tee_to_anthropic_state(translated, request_id.clone());
let translated =
tee_to_anthropic_state(translated, request_id.clone(), pending_stats.take());
let body_out = Body::from_stream(translated);
finish(status, resp_headers, body_out, &request_id)
}
@@ -475,201 +529,125 @@ where
if done {
return None;
}
// First, drain any complete messages already in the
// parser's buffer (bytes from the previous chunk).
loop {
match parser.next_message() {
Ok(Some(msg)) => match translate_message(&msg, OutputMode::Sse) {
Ok(TranslateOutcome::Emit(frame)) => {
// PR-D3: per-message Prometheus metric.
// The label `event_type` is bounded by
// AWS's documented vocabulary (chunk,
// metadata, exception variants); not
// customer-controlled.
let event_type = msg.event_type().unwrap_or("unknown").to_string();
record_bedrock_eventstream_message(&model_id, &region, &event_type);
tracing::debug!(
event = "bedrock_eventstream_message",
request_id = %request_id,
event_type = %event_type,
payload_bytes = msg.payload.len(),
"translated bedrock eventstream message"
);
return Some((
Ok(frame),
(parser, upstream, false, request_id, model_id, region),
));
}
Ok(TranslateOutcome::Skip { event_type }) => {
tracing::warn!(
event = "bedrock_eventstream_unknown_event_type",
request_id = %request_id,
event_type = %event_type,
"skipping unknown bedrock eventstream message"
);
// Loop and try the next message in the buffer.
continue;
}
Err(TranslateError::UpstreamException { payload_preview }) => {
tracing::warn!(
event = "bedrock_eventstream_upstream_exception",
request_id = %request_id,
payload_preview = %payload_preview,
"bedrock eventstream upstream exception"
);
// Emit the exception as an Anthropic-shape
// SSE error frame so the client sees it.
let json = serde_json::json!({
"type": "error",
"error": {
"type": "bedrock_upstream_exception",
"message": payload_preview,
}
})
.to_string();
let mut frame = Vec::with_capacity(json.len() + 32);
frame.extend_from_slice(b"event: error\ndata: ");
frame.extend_from_slice(json.as_bytes());
frame.extend_from_slice(b"\n\n");
return Some((
Ok(Bytes::from(frame)),
(parser, upstream, true, request_id, model_id, region),
));
}
Err(TranslateError::MissingEventType) => {
tracing::warn!(
event = "bedrock_eventstream_missing_event_type",
request_id = %request_id,
"bedrock eventstream message missing :event-type; emitting error frame"
);
let frame = error_sse_frame(
"bedrock_eventstream_missing_event_type",
"Bedrock message missing :event-type header",
);
return Some((
Ok(frame),
(parser, upstream, true, request_id, model_id, region),
));
}
},
Ok(None) => break,
Err(parse_err) => {
let event_name = match &parse_err {
ParseError::PreludeCrcMismatch { .. }
| ParseError::MessageCrcMismatch { .. } => {
"bedrock_eventstream_crc_mismatch"
// Drain-first alternation: after a chunk is pushed we
// re-enter the drain phase rather than pulling again,
// so a Skip'd message can never strand complete
// messages in the parser buffer. (The previous shape
// pulled a fresh upstream chunk after a Skip —
// delaying, and at stream end DROPPING, frames that
// were already buffered behind an unknown event type.)
'parse: loop {
// Phase 1: emit complete messages already buffered.
loop {
match parser.next_message() {
Ok(Some(msg)) => match translate_message(&msg, OutputMode::Sse) {
Ok(TranslateOutcome::Emit(frame)) => {
// PR-D3: per-message Prometheus metric.
// The label `event_type` is bounded by
// AWS's documented vocabulary (chunk,
// metadata, exception variants); not
// customer-controlled.
let event_type =
msg.event_type().unwrap_or("unknown").to_string();
record_bedrock_eventstream_message(
&model_id,
&region,
&event_type,
);
tracing::debug!(
event = "bedrock_eventstream_message",
request_id = %request_id,
event_type = %event_type,
payload_bytes = msg.payload.len(),
"translated bedrock eventstream message"
);
return Some((
Ok(frame),
(parser, upstream, false, request_id, model_id, region),
));
}
Ok(TranslateOutcome::Skip { event_type }) => {
tracing::warn!(
event = "bedrock_eventstream_unknown_event_type",
request_id = %request_id,
event_type = %event_type,
"skipping unknown bedrock eventstream message"
);
// Loop and try the next message in the buffer.
continue;
}
_ => "bedrock_eventstream_parse_failed",
};
tracing::warn!(
event = event_name,
request_id = %request_id,
error = %parse_err,
"bedrock eventstream parse failure; closing translated stream"
);
let frame = error_sse_frame(event_name, &parse_err.to_string());
return Some((
Ok(frame),
(parser, upstream, true, request_id, model_id, region),
));
}
}
}
// Buffer drained; pull the next chunk from upstream.
loop {
match upstream.next().await {
Some(Ok(chunk)) => {
parser.push(&chunk);
// Loop back through the parser to emit any
// newly-complete messages.
match parser.next_message() {
Ok(Some(msg)) => match translate_message(&msg, OutputMode::Sse) {
Ok(TranslateOutcome::Emit(frame)) => {
// PR-D3: per-message Prometheus
// metric (mirror of the parser-buffer
// drain branch above).
let event_type =
msg.event_type().unwrap_or("unknown").to_string();
record_bedrock_eventstream_message(
&model_id,
&region,
&event_type,
);
tracing::debug!(
event = "bedrock_eventstream_message",
request_id = %request_id,
event_type = %event_type,
payload_bytes = msg.payload.len(),
"translated bedrock eventstream message"
);
return Some((
Ok(frame),
(parser, upstream, false, request_id, model_id, region),
));
}
Ok(TranslateOutcome::Skip { event_type }) => {
tracing::warn!(
event = "bedrock_eventstream_unknown_event_type",
request_id = %request_id,
event_type = %event_type,
"skipping unknown bedrock eventstream message"
);
// Continue draining the parser /
// pulling more chunks.
continue;
}
Err(TranslateError::UpstreamException { payload_preview }) => {
let json = serde_json::json!({
"type": "error",
"error": {
"type": "bedrock_upstream_exception",
"message": payload_preview,
}
})
.to_string();
let mut frame = Vec::with_capacity(json.len() + 32);
frame.extend_from_slice(b"event: error\ndata: ");
frame.extend_from_slice(json.as_bytes());
frame.extend_from_slice(b"\n\n");
return Some((
Ok(Bytes::from(frame)),
(parser, upstream, true, request_id, model_id, region),
));
}
Err(TranslateError::MissingEventType) => {
let frame = error_sse_frame(
"bedrock_eventstream_missing_event_type",
"Bedrock message missing :event-type header",
);
return Some((
Ok(frame),
(parser, upstream, true, request_id, model_id, region),
));
}
},
Ok(None) => continue,
Err(parse_err) => {
let event_name = match &parse_err {
ParseError::PreludeCrcMismatch { .. }
| ParseError::MessageCrcMismatch { .. } => {
"bedrock_eventstream_crc_mismatch"
Err(TranslateError::UpstreamException { payload_preview }) => {
tracing::warn!(
event = "bedrock_eventstream_upstream_exception",
request_id = %request_id,
payload_preview = %payload_preview,
"bedrock eventstream upstream exception"
);
// Emit the exception as an Anthropic-shape
// SSE error frame so the client sees it.
let json = serde_json::json!({
"type": "error",
"error": {
"type": "bedrock_upstream_exception",
"message": payload_preview,
}
_ => "bedrock_eventstream_parse_failed",
};
})
.to_string();
let mut frame = Vec::with_capacity(json.len() + 32);
frame.extend_from_slice(b"event: error\ndata: ");
frame.extend_from_slice(json.as_bytes());
frame.extend_from_slice(b"\n\n");
return Some((
Ok(Bytes::from(frame)),
(parser, upstream, true, request_id, model_id, region),
));
}
Err(TranslateError::MissingEventType) => {
tracing::warn!(
event = event_name,
event = "bedrock_eventstream_missing_event_type",
request_id = %request_id,
error = %parse_err,
"bedrock eventstream parse failure"
"bedrock eventstream message missing :event-type; emitting error frame"
);
let frame = error_sse_frame(
"bedrock_eventstream_missing_event_type",
"Bedrock message missing :event-type header",
);
let frame = error_sse_frame(event_name, &parse_err.to_string());
return Some((
Ok(frame),
(parser, upstream, true, request_id, model_id, region),
));
}
},
Ok(None) => break,
Err(parse_err) => {
let event_name = match &parse_err {
ParseError::PreludeCrcMismatch { .. }
| ParseError::MessageCrcMismatch { .. } => {
"bedrock_eventstream_crc_mismatch"
}
_ => "bedrock_eventstream_parse_failed",
};
tracing::warn!(
event = event_name,
request_id = %request_id,
error = %parse_err,
"bedrock eventstream parse failure; closing translated stream"
);
let frame = error_sse_frame(event_name, &parse_err.to_string());
return Some((
Ok(frame),
(parser, upstream, true, request_id, model_id, region),
));
}
}
}
// Phase 2: buffer fully drained — pull exactly
// one chunk, then loop back to the drain phase.
match upstream.next().await {
Some(Ok(chunk)) => {
parser.push(&chunk);
continue 'parse;
}
Some(Err(e)) => {
tracing::warn!(
event = "bedrock_eventstream_upstream_io_error",
@@ -683,10 +661,11 @@ where
));
}
None => {
// End of upstream stream. If buffered bytes
// remain that did not parse into a message,
// log loudly — we are NOT silently dropping
// them.
// End of upstream stream. The drain phase
// above ran to Ok(None) first, so no
// complete message can be stranded here;
// leftover bytes are a truncated partial
// message — log loudly, never silently.
if parser.buffered_len() > 0 {
tracing::warn!(
event = "bedrock_eventstream_truncated",
@@ -713,6 +692,7 @@ where
fn tee_to_anthropic_state<S>(
upstream: S,
request_id: String,
pending_stats: Option<capture::PendingRecord>,
) -> impl Stream<Item = Result<Bytes, std::io::Error>>
where
S: Stream<Item = Result<Bytes, std::io::Error>> + Send + 'static,
@@ -720,7 +700,7 @@ where
let (tx, rx) = tokio::sync::mpsc::channel::<Bytes>(SSE_PARSER_QUEUE_DEPTH);
let parser_request_id = request_id.clone();
tokio::spawn(async move {
run_anthropic_state_machine(rx, parser_request_id).await;
run_anthropic_state_machine(rx, parser_request_id, pending_stats).await;
});
upstream.map(move |r| {
@@ -738,8 +718,6 @@ where
})
}
const SSE_PARSER_QUEUE_DEPTH: usize = 256;
/// Dedicated state-machine task. Mirrors the
/// `run_sse_state_machine(SseStreamKind::Anthropic, ...)` arm in
/// `proxy.rs` so usage extraction works identically for direct
@@ -747,17 +725,31 @@ const SSE_PARSER_QUEUE_DEPTH: usize = 256;
async fn run_anthropic_state_machine(
mut rx: tokio::sync::mpsc::Receiver<Bytes>,
request_id: String,
pending_stats: Option<capture::PendingRecord>,
) {
use crate::sse::anthropic::AnthropicStreamState;
use crate::sse::framing::SseFramer;
let mut framer = SseFramer::new();
let mut state = AnthropicStreamState::new();
// Converse-native frames (`metadata`, `messageStart`, …) carry no
// Anthropic `type`, so they arrive here as event-name-less frames
// the Anthropic state machine drops. Their camelCase usage block
// is the ONLY usage signal on a native Converse stream — scan
// them separately so `/converse-stream` requests don't record
// zero tokens.
let mut converse_usage = ledger::Usage::default();
while let Some(chunk) = rx.recv().await {
framer.push(&chunk);
while let Some(ev_result) = framer.next_event() {
match ev_result {
Ok(ev) => {
if ev.event_name.is_none() {
if let Ok(payload) = serde_json::from_slice::<serde_json::Value>(&ev.data) {
capture::merge_stream_usage(&mut converse_usage, &payload);
}
continue;
}
if let Err(e) = state.apply(ev) {
tracing::warn!(
request_id = %request_id,
@@ -787,6 +779,16 @@ async fn run_anthropic_state_machine(
blocks = state.blocks.len(),
"bedrock translated stream: closed"
);
if let Some(mut p) = pending_stats {
// In-band `{"type":"error"}` on a 200 OK stream is not a
// billable success (same rule as the direct Anthropic lane).
if matches!(state.status, crate::sse::anthropic::StreamStatus::Errored) {
p.mark_failed();
}
let mut usage = capture::usage_from_anthropic_state(&state);
capture::merge_max(&mut usage, converse_usage);
p.finalize(usage);
}
}
/// True when the content-type is `application/vnd.amazon.eventstream`
@@ -866,7 +868,7 @@ fn run_anthropic_compression(
state: &AppState,
_auth_mode: AuthMode,
request_id: &str,
) -> Bytes {
) -> (Bytes, CompressionStats) {
use crate::bedrock::envelope::BedrockEnvelope;
let parsed_envelope = BedrockEnvelope::parse(body).is_ok();
@@ -888,7 +890,7 @@ fn run_anthropic_compression(
request_id,
);
match outcome {
AnthropicOutcome::NoCompression => body.clone(),
AnthropicOutcome::NoCompression => (body.clone(), CompressionStats::default()),
AnthropicOutcome::Passthrough { reason } => {
tracing::info!(
event = "bedrock_compression_passthrough",
@@ -897,12 +899,23 @@ fn run_anthropic_compression(
"bedrock invoke-streaming: passthrough"
);
let _ = (PassthroughReason::ModeOff, PassthroughReason::NoMessages);
body.clone()
(body.clone(), CompressionStats::default())
}
AnthropicOutcome::Compressed { body: new_body, .. } => {
AnthropicOutcome::Compressed {
body: new_body,
tokens_before,
tokens_after,
strategies_applied,
..
} => {
let stats = CompressionStats {
tokens_before: tokens_before as u64,
tokens_after: tokens_after as u64,
transforms: strategies_applied.iter().map(|s| s.to_string()).collect(),
};
if parsed_envelope {
match BedrockEnvelope::ensure_anthropic_version_first(&new_body) {
Ok(b) => b,
Ok(b) => (b, stats),
Err(e) => {
tracing::error!(
event = "bedrock_envelope_reemit_failed",
@@ -910,11 +923,13 @@ fn run_anthropic_compression(
error = %e,
"bedrock invoke-streaming: failed to re-emit envelope"
);
body.clone()
// Original bytes forwarded ⇒ no compression
// happened as far as the wire is concerned.
(body.clone(), CompressionStats::default())
}
}
} else {
new_body
(new_body, stats)
}
}
}
@@ -1035,6 +1050,7 @@ mod tests {
vertex_token_source: std::sync::Arc::new(crate::vertex::StaticTokenSource::new(
"test".to_string(),
)),
stats: std::sync::Arc::new(ledger::Ledger::in_memory()),
};
let uri: Uri = "/model/anthropic.claude-3-haiku-20240307-v1:0/invoke-with-response-stream"
.parse()
@@ -1075,6 +1091,7 @@ mod tests {
vertex_token_source: std::sync::Arc::new(crate::vertex::StaticTokenSource::new(
"test".to_string(),
)),
stats: std::sync::Arc::new(ledger::Ledger::in_memory()),
};
let uri: Uri = "/model/anthropic.claude-3-haiku-20240307-v1:0/converse-stream"
.parse()
+9
View File
@@ -54,6 +54,15 @@ pub mod invoke_streaming;
pub mod sigv4;
pub mod vendor;
/// Compression-side numbers the Bedrock handlers hand to the savings
/// ledger alongside the (possibly compressed) outbound body.
#[derive(Debug, Default, Clone)]
pub(crate) struct CompressionStats {
pub tokens_before: u64,
pub tokens_after: u64,
pub transforms: Vec<String>,
}
pub use auth_mode_layer::classify_and_attach_auth_mode;
pub use envelope::{BedrockEnvelope, EnvelopeError};
pub use eventstream::{
+34 -5
View File
@@ -13,7 +13,28 @@
/// vendor segment. Stripped (once) before vendor resolution. Kept to a
/// closed, known set so an unrelated `something.anthropic.x` id is not
/// mistaken for an Anthropic inference profile.
const GEO_PREFIXES: [&str; 4] = ["eu.", "us.", "apac.", "global."];
///
/// The set is the prefixes present in the vendored LiteLLM price
/// table (`data/model_prices_and_context_window.json`) — every one of
/// these fronts real `<geo>.anthropic.…` ids there. A missing entry
/// is not cosmetic: an unrecognized geo prefix makes
/// `is_anthropic_model_id` return false, silently skipping
/// compression for that region's inference profiles (`au.`/`jp.`/
/// `us-gov.` were missing until review of the stats work caught it).
pub(crate) const GEO_PREFIXES: [&str; 7] =
["eu.", "us.", "us-gov.", "apac.", "au.", "jp.", "global."];
/// Strip a cross-region inference-profile geo prefix, if present.
/// `eu.anthropic.claude-…` → `anthropic.claude-…`; ids without a
/// known geo prefix return unchanged. Shared with
/// `observability::pricing` so price lookups see the same canonical
/// id the vendor gate sees.
pub(crate) fn strip_geo_prefix(model_id: &str) -> &str {
GEO_PREFIXES
.iter()
.find_map(|p| model_id.strip_prefix(p))
.unwrap_or(model_id)
}
/// Resolve the canonical vendor of a Bedrock model id, stripping a
/// cross-region inference-profile geo prefix first.
@@ -21,10 +42,7 @@ const GEO_PREFIXES: [&str; 4] = ["eu.", "us.", "apac.", "global."];
/// `eu.anthropic.claude-…` → `anthropic`; `amazon.titan-…` → `amazon`;
/// `global.amazon.nova-…` → `amazon`.
pub fn canonical_vendor(model_id: &str) -> &str {
let stripped = GEO_PREFIXES
.iter()
.find_map(|p| model_id.strip_prefix(p))
.unwrap_or(model_id);
let stripped = strip_geo_prefix(model_id);
stripped.split('.').next().unwrap_or(stripped)
}
@@ -73,6 +91,17 @@ mod tests {
assert!(is_anthropic_model_id(
"global.anthropic.claude-haiku-4-5-20251001-v1:0"
));
// au./jp./us-gov. are real AWS geo prefixes (present in the
// vendored price table); they must gate as Anthropic too.
assert!(is_anthropic_model_id(
"au.anthropic.claude-sonnet-4-5-20250929-v1:0"
));
assert!(is_anthropic_model_id(
"jp.anthropic.claude-haiku-4-5-20251001-v1:0"
));
assert!(is_anthropic_model_id(
"us-gov.anthropic.claude-sonnet-4-5-20250929-v1:0"
));
// Non-Anthropic vendors, including geo-prefixed, stay false.
assert!(!is_anthropic_model_id("amazon.titan-text-express-v1"));
assert!(!is_anthropic_model_id("meta.llama3-70b-instruct-v1:0"));
@@ -66,7 +66,10 @@ pub(crate) const DEFAULT_CONTEXT_WINDOW: u32 = 128_000;
/// LiteLLM's vendored model price + context-window table. Refreshed
/// via `scripts/refresh_model_limits.sh`. ~1.4MB; embedded into the
/// binary so the proxy ships with no startup network dependency.
const VENDORED_JSON: &str = include_str!("../../data/model_prices_and_context_window.json");
// Shared with `observability::pricing`, which reads the per-token
// cost fields of the same table — one embedded copy, two consumers.
pub(crate) const VENDORED_JSON: &str =
include_str!("../../data/model_prices_and_context_window.json");
/// Parsed lookup: model id → max input tokens. Built lazily on
/// first call; subsequent calls reuse the same `HashMap`.
+90
View File
@@ -592,6 +592,34 @@ pub struct CliArgs {
default_value = "https://www.googleapis.com/auth/cloud-platform"
)]
pub vertex_adc_scope: String,
/// Native savings stats: record per-request savings/cost
/// telemetry and serve `/stats`, `/stats/timeseries`,
/// `/stats/events`, and `/dashboard`. When disabled, nothing is
/// recorded and those paths fall through to the catch-all
/// forwarder (i.e. they reach the upstream, matching the
/// pre-feature behaviour).
///
/// Source priority: CLI flag → `HEADROOM_PROXY_STATS` env var →
/// default (`false`).
#[arg(
long = "stats",
env = "HEADROOM_PROXY_STATS",
default_value_t = false,
action = clap::ArgAction::Set,
)]
pub stats: bool,
/// Where the savings ledger persists its state. When unset, the
/// proxy uses `$HEADROOM_WORKSPACE_DIR/native_stats.json` when
/// that env var is set (how the Python proxy resolves its
/// workspace), else `~/.headroom/native_stats.json`; if no home
/// directory can be resolved, stats stay in-memory (logged).
///
/// Source priority: CLI flag → `HEADROOM_PROXY_STATS_PATH`
/// env var → workspace-derived default.
#[arg(long = "stats-path", env = "HEADROOM_PROXY_STATS_PATH")]
pub stats_path: Option<std::path::PathBuf>,
}
fn parse_duration(s: &str) -> Result<Duration, String> {
@@ -708,6 +736,11 @@ pub struct Config {
/// PR-D4: GCP ADC OAuth scope used when fetching the bearer
/// token. Default `https://www.googleapis.com/auth/cloud-platform`.
pub vertex_adc_scope: String,
/// Native savings stats: record per-request telemetry and serve
/// `/stats`, `/stats/timeseries`, `/stats/events`, `/dashboard`.
pub stats: bool,
/// Ledger persistence path. `None` keeps stats in-memory.
pub stats_path: Option<std::path::PathBuf>,
}
impl Config {
@@ -775,6 +808,8 @@ impl Config {
bedrock_validate_eventstream_crc: args.bedrock_validate_eventstream_crc,
vertex_region: args.vertex_region,
vertex_adc_scope: args.vertex_adc_scope,
stats: args.stats,
stats_path: args.stats_path.or_else(default_stats_path),
}
}
@@ -838,10 +873,47 @@ impl Config {
// only; the upstream URL is `upstream`).
vertex_region: "us-central1".to_string(),
vertex_adc_scope: "https://www.googleapis.com/auth/cloud-platform".to_string(),
// Stats on (routes mounted, recording active) but
// in-memory: tests never touch a real home directory.
stats: true,
stats_path: None,
}
}
}
/// Default persistence location for the savings ledger. Honours the
/// same `HEADROOM_WORKSPACE_DIR` override the Python proxy uses for
/// its workspace, falling back to `~/.headroom`. `None` (no home
/// resolvable) keeps stats in-memory.
fn default_stats_path() -> Option<std::path::PathBuf> {
if let Ok(dir) = std::env::var("HEADROOM_WORKSPACE_DIR") {
let dir = dir.trim();
if !dir.is_empty() {
// Tilde-expand, matching the Python proxy's
// `workspace_dir()` semantics (its tests pin
// `HEADROOM_WORKSPACE_DIR=~/custom` → `$HOME/custom`).
let expanded = if let Some(rest) = dir.strip_prefix("~/") {
match home_dir() {
Some(home) => home.join(rest),
None => return None,
}
} else {
std::path::PathBuf::from(dir)
};
return Some(expanded.join("native_stats.json"));
}
}
Some(home_dir()?.join(".headroom").join("native_stats.json"))
}
fn home_dir() -> Option<std::path::PathBuf> {
std::env::var("HOME")
.ok()
.filter(|h| !h.trim().is_empty())
.or_else(|| std::env::var("USERPROFILE").ok())
.map(std::path::PathBuf::from)
}
#[cfg(test)]
mod rollout_input_tests {
use super::*;
@@ -885,4 +957,22 @@ mod rollout_input_tests {
assert!(!config.enable_responses_streaming);
assert!(!config.enable_bedrock_native);
}
#[test]
fn native_stats_require_explicit_opt_in() {
let base = ["headroom-proxy", "--upstream", "http://127.0.0.1:9"];
let default_config = Config::from_cli(CliArgs::try_parse_from(base).unwrap());
assert!(!default_config.stats);
let enabled = Config::from_cli(
CliArgs::try_parse_from([
"headroom-proxy",
"--upstream",
"http://127.0.0.1:9",
"--stats=true",
])
.unwrap(),
);
assert!(enabled.stats);
}
}
+38
View File
@@ -105,6 +105,42 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
}
}
// Savings observability: with the master compression switch on
// but the mode off, the dispatcher passes every body through and
// tokens_saved reads 0 on the dashboard with no hint why. Say so
// once at startup instead of letting the zero look like a bug.
if config.compression
&& matches!(
config.compression_mode,
headroom_proxy::config::CompressionMode::Off
)
{
tracing::warn!(
event = "compression_mode_off",
"--compression is on but --compression-mode is `off`: bodies \
pass through unmodified and the dashboard's compression \
savings will read 0. Set --compression-mode live_zone to \
engage the dispatcher."
);
}
// Savings ledger: background persistence while serving, plus a
// best-effort final flush after the server drains (capture tasks
// are detached, so a request finishing in the same instant as
// shutdown may still miss it — see observability::capture docs).
let stats_ledger = state.stats.clone();
if config.stats {
// Pay the vendored price-table parse now, not on the first
// recorded request.
headroom_proxy::observability::pricing::warm();
tracing::info!(
event = "stats_enabled",
path = ?stats_ledger.path().map(|p| p.display().to_string()),
"native savings stats active (/stats, /dashboard)"
);
headroom_proxy::observability::ledger::spawn_flusher(stats_ledger.clone());
}
let app = build_app(state).into_make_service_with_connect_info::<SocketAddr>();
let listener = tokio::net::TcpListener::bind(config.listen).await?;
@@ -122,6 +158,8 @@ async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
})
.await?;
stats_ledger.flush().await;
Ok(())
}
@@ -0,0 +1,594 @@
//! Response-usage capture — Phase H. Shared by every lane.
//!
//! Recording a request's savings needs the *response's* token usage,
//! which arrives in four wire shapes:
//!
//! - JSON bodies (non-streaming Anthropic / OpenAI / Bedrock /
//! Vertex responses),
//! - Anthropic-style SSE streams (direct, Vertex, and Bedrock's
//! SSE-translated mode) — already accumulated by
//! [`crate::sse::anthropic::AnthropicStreamState`],
//! - Converse-native frames whose usage keys are camelCase and carry
//! no Anthropic `type` (the state machine drops them),
//! - Bedrock binary EventStream passthrough, where nothing parses
//! the frames today.
//!
//! This module provides one [`PendingRecord`] (a request's
//! half-built ledger event plus the deferred-finalization contract:
//! **record only after the response is fully observed**, so
//! streaming token counts are real instead of zero) and the capture
//! tasks that feed it. Every capture path is a bounded, best-effort
//! tee off the client byte path — a stalled or hostile response can
//! delay telemetry, never the client.
//!
//! Best-effort has one deliberate edge: capture tasks are plain
//! `tokio::spawn`s with no shutdown drain, so requests still
//! in-flight when the process exits are dropped without recording.
//! Tracking them against shutdown would couple the byte path to
//! telemetry lifetime — the wrong trade for a stats ledger.
use std::sync::Arc;
use std::time::Instant;
use base64::Engine as _;
use serde_json::Value;
use super::ledger::{Ledger, RequestEvent, Usage};
/// Cap for buffered non-streaming response bodies awaiting a usage
/// parse. Bigger bodies finalize with zero usage (tokens/USD from
/// compression estimates only) rather than growing memory.
const JSON_CAPTURE_CAP: usize = 2 * 1024 * 1024;
/// Queue depth for every telemetry tee (capture bodies and the SSE
/// parser feeds in proxy/bedrock/vertex). Bounded so a stalled
/// parser task can never make the byte path wait: senders `try_send`
/// and drop on a full queue.
pub(crate) const TEE_QUEUE_DEPTH: usize = 256;
/// A request's ledger event, waiting for its response to finish.
///
/// Constructed when the request is forwarded; finalized exactly once
/// when the response is fully observed (stream closed / body ended /
/// transport failed). Latency is measured here so every lane reports
/// the same thing: time from forwarding decision to response fully
/// observed.
pub struct PendingRecord {
ledger: Arc<Ledger>,
event: RequestEvent,
started: Instant,
}
impl PendingRecord {
pub fn new(ledger: Arc<Ledger>, event: RequestEvent, started: Instant) -> Self {
Self {
ledger,
event,
started,
}
}
/// Mark the upstream outcome failed (non-2xx or transport error)
/// before finalization.
pub fn mark_failed(&mut self) {
self.event.failed = true;
}
/// Supply the model id the request side knows (path parameter,
/// or the buffered request body when compression is on).
pub fn set_model(&mut self, model: &str) {
self.event.set_model(model);
}
/// Supply the model id learned from the *response*. Recording is
/// not gated on the compression buffer (compression defaults
/// off), so on a pure passthrough request this is the only place
/// the model is known. Never overrides a request-side value.
pub fn set_model_if_unknown(&mut self, model: &str) {
if self.event.model_is_unknown() {
self.event.set_model(model);
}
}
/// Attach the compression dispatcher's before/after token
/// estimate and the strategies it applied.
pub fn set_compression(&mut self, before: u64, after: u64, transforms: Vec<String>) {
self.event.tokens_before = before;
self.event.tokens_after = after;
self.event.transforms = transforms;
}
/// Record with the captured usage. Consumes the record — each
/// request records exactly once.
pub fn finalize(mut self, usage: Usage) {
self.event.usage = usage;
self.event.latency_ms = self.started.elapsed().as_millis() as u64;
self.ledger.record(self.event);
}
/// Record a failure (zero usage, no savings — the ledger's
/// failed-path accounting).
pub fn finalize_failed(mut self) {
self.mark_failed();
self.finalize(Usage::default());
}
}
/// Build the pending ledger event for a request entering a handler
/// (`None` when `--stats` is off). One call site per lane keeps the
/// "constructed at handler entry so every exit records exactly once"
/// rule easy to audit.
pub fn start_pending(
state: &crate::proxy::AppState,
provider: &'static str,
model: &str,
request_id: &str,
) -> Option<PendingRecord> {
state.config.stats.then(|| {
PendingRecord::new(
state.stats.clone(),
RequestEvent::new(provider, model, request_id),
Instant::now(),
)
})
}
/// Finalize a pending record as failed on a proxy-side rejection
/// (bad path, missing credentials, signing failure, oversized body,
/// …). Sugar for handler early-return paths, so "every request that
/// enters a handler produces exactly one record" survives rejects: a
/// credentials outage must show in `/stats` as a failure spike, not
/// as zero traffic.
pub fn finalize_rejected(pending: Option<PendingRecord>) {
if let Some(p) = pending {
p.finalize_failed();
}
}
/// Which JSON body shape to expect when parsing a non-streaming
/// response for usage.
#[derive(Debug, Clone, Copy)]
pub enum ResponseShape {
Anthropic,
OpenAiChat,
OpenAiResponses,
/// Bedrock sync responses: InvokeModel bodies are Anthropic
/// snake_case, Converse bodies are camelCase — try both.
Bedrock,
}
/// Extract usage from a complete response body. `None` when the
/// body has no recognisable usage block (error envelopes, non-JSON).
fn usage_from_response_json(shape: ResponseShape, v: &Value) -> Option<Usage> {
usage_from_usage_block(shape, v.get("usage")?)
}
/// Parse a bare `usage` object (already extracted from its
/// envelope) — the SSE state machines hold usage in this form.
pub fn usage_from_usage_block(shape: ResponseShape, usage: &Value) -> Option<Usage> {
match shape {
ResponseShape::Anthropic => snake_usage(usage),
ResponseShape::OpenAiChat => openai_chat_usage(usage),
ResponseShape::OpenAiResponses => openai_responses_usage(usage),
ResponseShape::Bedrock => snake_usage(usage).or_else(|| camel_usage(usage)),
}
}
fn u64_at(v: &Value, key: &str) -> Option<u64> {
v.get(key).and_then(Value::as_u64)
}
/// Anthropic `usage` block (also Bedrock InvokeModel for Anthropic
/// models): `input_tokens` already EXCLUDES cache reads/writes.
fn snake_usage(usage: &Value) -> Option<Usage> {
let input = u64_at(usage, "input_tokens");
let output = u64_at(usage, "output_tokens");
if input.is_none() && output.is_none() {
return None;
}
Some(Usage {
input_tokens: input.unwrap_or(0),
output_tokens: output.unwrap_or(0),
cache_read_tokens: u64_at(usage, "cache_read_input_tokens").unwrap_or(0),
cache_write_tokens: u64_at(usage, "cache_creation_input_tokens").unwrap_or(0),
})
}
/// Bedrock Converse `usage` block: camelCase, and `inputTokens`
/// likewise excludes cache tokens.
///
/// The cache fields fall back to the `*InputTokenCount` spelling
/// after `*InputTokens`. Reading only one name would silently report
/// zero cache tokens against a response that uses the other, and a
/// miss costs one map lookup — cheap insurance on a field whose
/// whole job is to be believed.
fn camel_usage(usage: &Value) -> Option<Usage> {
let input = u64_at(usage, "inputTokens");
let output = u64_at(usage, "outputTokens");
if input.is_none() && output.is_none() {
return None;
}
Some(Usage {
input_tokens: input.unwrap_or(0),
output_tokens: output.unwrap_or(0),
cache_read_tokens: u64_at(usage, "cacheReadInputTokens")
.or_else(|| u64_at(usage, "cacheReadInputTokenCount"))
.unwrap_or(0),
cache_write_tokens: u64_at(usage, "cacheWriteInputTokens")
.or_else(|| u64_at(usage, "cacheWriteInputTokenCount"))
.unwrap_or(0),
})
}
/// OpenAI Chat Completions: `prompt_tokens` INCLUDES cached tokens —
/// normalise to the ledger's Anthropic semantics (input = uncached).
fn openai_chat_usage(usage: &Value) -> Option<Usage> {
let prompt = u64_at(usage, "prompt_tokens")?;
let cached = usage
.get("prompt_tokens_details")
.and_then(|d| u64_at(d, "cached_tokens"))
.unwrap_or(0)
.min(prompt);
Some(Usage {
input_tokens: prompt - cached,
output_tokens: u64_at(usage, "completion_tokens").unwrap_or(0),
cache_read_tokens: cached,
cache_write_tokens: 0,
})
}
/// OpenAI Responses: `input_tokens` INCLUDES cached tokens — same
/// normalisation.
fn openai_responses_usage(usage: &Value) -> Option<Usage> {
let input = u64_at(usage, "input_tokens")?;
let cached = usage
.get("input_tokens_details")
.and_then(|d| u64_at(d, "cached_tokens"))
.unwrap_or(0)
.min(input);
Some(Usage {
input_tokens: input - cached,
output_tokens: u64_at(usage, "output_tokens").unwrap_or(0),
cache_read_tokens: cached,
cache_write_tokens: 0,
})
}
/// Usage accumulated by the shared Anthropic SSE state machine.
pub fn usage_from_anthropic_state(state: &crate::sse::anthropic::AnthropicStreamState) -> Usage {
Usage {
input_tokens: state.usage.input_tokens,
output_tokens: state.usage.output_tokens,
cache_read_tokens: state.usage.cache_read_input_tokens,
cache_write_tokens: state.usage.cache_creation_input_tokens,
}
}
/// Fold one streaming frame's JSON payload into a usage accumulator.
/// Handles every Bedrock/Anthropic stream shape (fields are monotone
/// within a stream, so `max` merge is safe against repeats):
///
/// - Anthropic SSE events: `message_start.message.usage`,
/// `message_delta.usage` (snake_case),
/// - Converse-native frames: bare `usage` with camelCase keys
/// (`metadata` events — no Anthropic `type` field at all),
/// - Bedrock InvokeModel EventStream chunks: `{"bytes": "<base64>"}`
/// wrapping an Anthropic SSE event (recursed after decode).
pub fn merge_stream_usage(acc: &mut Usage, payload: &Value) {
merge_stream_usage_depth(acc, payload, 0);
}
/// Real Bedrock wraps exactly once (`{"bytes": <b64 of the Anthropic
/// event>}`); the recursion exists only for that unwrap. Cap it so a
/// crafted deeply-nested base64 payload can't blow the stack — a
/// stack overflow aborts the whole process, not just this task.
const MAX_BYTES_UNWRAP_DEPTH: u8 = 4;
fn merge_stream_usage_depth(acc: &mut Usage, payload: &Value, depth: u8) {
// InvokeModel EventStream chunk: base64-wrapped inner event.
if let Some(b64) = payload.get("bytes").and_then(Value::as_str) {
if depth >= MAX_BYTES_UNWRAP_DEPTH {
tracing::warn!(
event = "stats_capture_bytes_depth_exceeded",
depth = depth,
"nested {{\"bytes\": …}} wrapping exceeded the unwrap cap; \
ignoring the payload (real Bedrock wraps exactly once)"
);
return;
}
if let Ok(decoded) = base64::engine::general_purpose::STANDARD.decode(b64) {
if let Ok(inner) = serde_json::from_slice::<Value>(&decoded) {
merge_stream_usage_depth(acc, &inner, depth + 1);
}
}
return;
}
// message_start carries usage nested under `message`.
if let Some(u) = payload
.get("message")
.and_then(|m| m.get("usage"))
.and_then(snake_usage)
{
merge_max(acc, u);
}
// message_delta (and some terminal frames) carry a bare `usage`.
if let Some(usage) = payload.get("usage") {
if let Some(u) = snake_usage(usage).or_else(|| camel_usage(usage)) {
merge_max(acc, u);
}
}
}
/// Take the field-wise maximum of two usage snapshots (usage fields
/// are monotone within a stream, so `max` merge is repeat-safe).
pub(crate) fn merge_max(acc: &mut Usage, u: Usage) {
acc.input_tokens = acc.input_tokens.max(u.input_tokens);
acc.output_tokens = acc.output_tokens.max(u.output_tokens);
acc.cache_read_tokens = acc.cache_read_tokens.max(u.cache_read_tokens);
acc.cache_write_tokens = acc.cache_write_tokens.max(u.cache_write_tokens);
}
/// Bounded tee → JSON-body usage capture. Returns the sender to tee
/// response chunks into; finalizes `pending` when the channel
/// closes (i.e. the response body finished or the client hung up).
pub fn spawn_json_usage_capture(
shape: ResponseShape,
mut pending: PendingRecord,
) -> tokio::sync::mpsc::Sender<bytes::Bytes> {
let (tx, mut rx) = tokio::sync::mpsc::channel::<bytes::Bytes>(TEE_QUEUE_DEPTH);
tokio::spawn(async move {
let mut buf: Vec<u8> = Vec::new();
let mut truncated = false;
while let Some(chunk) = rx.recv().await {
if truncated {
continue; // keep draining so the tee never backpressures
}
if buf.len() + chunk.len() > JSON_CAPTURE_CAP {
// No silent fallbacks: the request still records, but
// its usage will read zero — say why, once.
tracing::warn!(
event = "stats_capture_body_too_large",
cap_bytes = JSON_CAPTURE_CAP,
"response body exceeded the usage-capture buffer; \
this request records with compression-side numbers \
only (tokens/USD from usage read as 0)"
);
truncated = true;
buf.clear();
continue;
}
buf.extend_from_slice(&chunk);
}
let mut usage = Usage::default();
if !truncated {
match serde_json::from_slice::<Value>(&buf) {
Ok(v) => {
if let Some(model) = v.get("model").and_then(Value::as_str) {
pending.set_model_if_unknown(model);
}
// A 2xx from an LLM endpoint carries a usage block
// in every shape we know. A miss means the wire
// format moved (or this isn't the body we think it
// is), and the request would silently record $0 —
// the phantom-zero this module exists to avoid.
// Same no-silent-fallbacks rule as the cap above.
match usage_from_response_json(shape, &v) {
Some(u) => usage = u,
None => tracing::warn!(
event = "stats_capture_no_usage_block",
shape = ?shape,
"response parsed as JSON but carried no recognisable \
usage block; recording this request with zero tokens \
and $0 spend"
),
}
}
Err(e) => tracing::warn!(
event = "stats_capture_body_not_json",
error = %e,
"response body did not parse as JSON; recording this request \
with zero tokens and $0 spend"
),
}
}
pending.finalize(usage);
});
tx
}
/// Bounded tee → Bedrock binary EventStream usage capture, for the
/// passthrough mode where no other parser sees the frames. CRC
/// validation is off — this is the telemetry side; enforcement
/// happens (or not, per config) on the byte path.
pub fn spawn_eventstream_usage_capture(
pending: PendingRecord,
) -> tokio::sync::mpsc::Sender<bytes::Bytes> {
use crate::bedrock::eventstream::{CrcValidation, EventStreamParser};
let (tx, mut rx) = tokio::sync::mpsc::channel::<bytes::Bytes>(TEE_QUEUE_DEPTH);
tokio::spawn(async move {
let mut parser = EventStreamParser::new().with_crc_validation(CrcValidation::No);
let mut usage = Usage::default();
'outer: while let Some(chunk) = rx.recv().await {
parser.push(&chunk);
loop {
match parser.next_message() {
Ok(Some(msg)) => {
if let Ok(payload) = serde_json::from_slice::<Value>(&msg.payload) {
merge_stream_usage(&mut usage, &payload);
}
}
Ok(None) => break,
Err(_) => {
// Telemetry parser out of sync — stop and
// record what accumulated so far. The channel
// is simply dropped; the tee's `try_send` on a
// closed channel is a no-op, so the byte path
// never notices.
break 'outer;
}
}
}
}
pending.finalize(usage);
});
tx
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn anthropic_json_usage_parses() {
let v = json!({"usage": {"input_tokens": 10, "output_tokens": 5,
"cache_read_input_tokens": 7, "cache_creation_input_tokens": 3}});
let u = usage_from_response_json(ResponseShape::Anthropic, &v).unwrap();
assert_eq!(
u,
Usage {
input_tokens: 10,
output_tokens: 5,
cache_read_tokens: 7,
cache_write_tokens: 3
}
);
}
#[test]
fn openai_chat_normalises_cached_out_of_prompt() {
let v = json!({"usage": {"prompt_tokens": 100, "completion_tokens": 20,
"prompt_tokens_details": {"cached_tokens": 60}}});
let u = usage_from_response_json(ResponseShape::OpenAiChat, &v).unwrap();
assert_eq!(u.input_tokens, 40, "prompt minus cached");
assert_eq!(u.cache_read_tokens, 60);
assert_eq!(u.output_tokens, 20);
// Pathological cached > prompt clamps instead of underflowing.
let v = json!({"usage": {"prompt_tokens": 10,
"prompt_tokens_details": {"cached_tokens": 60}}});
let u = usage_from_response_json(ResponseShape::OpenAiChat, &v).unwrap();
assert_eq!(u.input_tokens, 0);
assert_eq!(u.cache_read_tokens, 10);
}
#[test]
fn openai_responses_normalises_cached_out_of_input() {
let v = json!({"usage": {"input_tokens": 80, "output_tokens": 9,
"input_tokens_details": {"cached_tokens": 50}}});
let u = usage_from_response_json(ResponseShape::OpenAiResponses, &v).unwrap();
assert_eq!(u.input_tokens, 30);
assert_eq!(u.cache_read_tokens, 50);
}
#[test]
fn bedrock_shape_accepts_snake_and_camel() {
let snake = json!({"usage": {"input_tokens": 10, "output_tokens": 5}});
let camel = json!({"usage": {"inputTokens": 11, "outputTokens": 6,
"cacheReadInputTokens": 4, "cacheWriteInputTokens": 2}});
assert_eq!(
usage_from_response_json(ResponseShape::Bedrock, &snake)
.unwrap()
.input_tokens,
10
);
let u = usage_from_response_json(ResponseShape::Bedrock, &camel).unwrap();
assert_eq!(u.input_tokens, 11);
assert_eq!(u.cache_read_tokens, 4);
assert_eq!(u.cache_write_tokens, 2);
}
/// The cache fields accept the `*InputTokenCount` spelling too.
/// Untested, this fallback reads as dead code and invites
/// deletion — at which point any response using that spelling
/// silently reports zero cache tokens.
#[test]
fn bedrock_camel_usage_accepts_token_count_suffix() {
let v = json!({"usage": {"inputTokens": 11, "outputTokens": 6,
"cacheReadInputTokenCount": 4, "cacheWriteInputTokenCount": 2}});
let u = usage_from_response_json(ResponseShape::Bedrock, &v).unwrap();
assert_eq!(u.cache_read_tokens, 4);
assert_eq!(u.cache_write_tokens, 2);
// The unsuffixed spelling wins when both are present.
let both = json!({"usage": {"inputTokens": 11, "outputTokens": 6,
"cacheReadInputTokens": 9, "cacheReadInputTokenCount": 4}});
let u = usage_from_response_json(ResponseShape::Bedrock, &both).unwrap();
assert_eq!(u.cache_read_tokens, 9);
}
#[test]
fn error_envelope_yields_none() {
let v = json!({"error": {"type": "overloaded_error"}});
assert!(usage_from_response_json(ResponseShape::Anthropic, &v).is_none());
let v = json!({"usage": {"totalTokens": 5}});
assert!(usage_from_response_json(ResponseShape::Bedrock, &v).is_none());
}
#[test]
fn stream_merge_handles_all_three_wire_shapes() {
let mut acc = Usage::default();
// 1. Anthropic message_start (nested under message).
merge_stream_usage(
&mut acc,
&json!({"type": "message_start",
"message": {"usage": {"input_tokens": 25, "output_tokens": 1,
"cache_read_input_tokens": 9}}}),
);
// 2. Anthropic message_delta (bare usage, growing output).
merge_stream_usage(
&mut acc,
&json!({"type": "message_delta", "usage": {"output_tokens": 42}}),
);
// 3. Converse metadata (camelCase, no `type`).
merge_stream_usage(
&mut acc,
&json!({"usage": {"inputTokens": 25, "outputTokens": 42,
"cacheWriteInputTokens": 3}}),
);
assert_eq!(acc.input_tokens, 25);
assert_eq!(acc.output_tokens, 42);
assert_eq!(acc.cache_read_tokens, 9);
assert_eq!(acc.cache_write_tokens, 3);
}
/// A crafted payload nesting `{"bytes": …}` inside itself must
/// hit the unwrap cap instead of recursing until the stack blows
/// (a stack overflow aborts the whole process). Real Bedrock
/// wraps exactly once.
#[test]
fn stream_merge_bounds_nested_base64_depth() {
let engine = &base64::engine::general_purpose::STANDARD;
// usage buried 10 wraps deep — far past the cap.
let mut v = json!({"type": "message_delta", "usage": {"output_tokens": 99}});
for _ in 0..10 {
v = json!({"bytes": engine.encode(v.to_string())});
}
let mut acc = Usage::default();
merge_stream_usage(&mut acc, &v); // must return, not overflow
assert_eq!(
acc.output_tokens, 0,
"usage beyond the unwrap cap is ignored, not chased"
);
// …while the real single-wrap shape still works.
let single = json!({"bytes": engine.encode(
json!({"type": "message_delta", "usage": {"output_tokens": 7}}).to_string()
)});
merge_stream_usage(&mut acc, &single);
assert_eq!(acc.output_tokens, 7);
}
#[test]
fn stream_merge_decodes_invoke_model_base64_chunks() {
let inner = json!({"type": "message_delta",
"usage": {"output_tokens": 17, "input_tokens": 12}});
let b64 =
base64::engine::general_purpose::STANDARD.encode(serde_json::to_vec(&inner).unwrap());
let mut acc = Usage::default();
merge_stream_usage(&mut acc, &json!({"bytes": b64, "p": "pad"}));
assert_eq!(acc.output_tokens, 17);
assert_eq!(acc.input_tokens, 12);
// Garbage base64 is ignored, never panics.
merge_stream_usage(&mut acc, &json!({"bytes": "!!!not-base64!!!"}));
assert_eq!(acc.output_tokens, 17);
}
}
@@ -0,0 +1,722 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Headroom Proxy — Savings</title>
<!-- Inline icon: keeps the page fully self-contained (the proxy's
/favicon.ico route serves a generic icon; this one is the
dashboard's own). -->
<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Crect width='16' height='16' rx='3' fill='%232a78d6'/%3E%3Cpath d='M4 11.5V4.5M8 11.5V7M12 11.5V6' stroke='white' stroke-width='1.8' stroke-linecap='round'/%3E%3C/svg%3E">
<style>
:root {
color-scheme: light;
--page: #f9f9f7;
--surface: #fcfcfb;
--ink: #0b0b0b;
--ink-2: #52514e;
--muted: #898781;
--grid: #e1e0d9;
--baseline: #c3c2b7;
--border: rgba(11, 11, 11, 0.10);
--series-1: #2a78d6; /* spent (also anthropic/bedrock keys) */
--series-2: #008300; /* saved (also openai/vertex keys) */
--good: #0ca30c;
--good-text: #006300;
--critical: #d03b3b;
--wash: rgba(11, 11, 11, 0.04);
--shadow: rgba(0, 0, 0, 0.18);
}
@media (prefers-color-scheme: dark) {
:root {
color-scheme: dark;
--page: #0d0d0d;
--surface: #1a1a19;
--ink: #ffffff;
--ink-2: #c3c2b7;
--muted: #898781;
--grid: #2c2c2a;
--baseline: #383835;
--border: rgba(255, 255, 255, 0.10);
--series-1: #3987e5;
--series-2: #008300;
--good-text: #0ca30c;
/* #d03b3b is 3.6:1 on this surface — under AA for text, and
--critical IS text here (the "✕ N failed" badge), not a dot.
Lightened to clear 4.5:1 on #1a1a19. */
--critical: #f26a6a;
--wash: rgba(255, 255, 255, 0.06);
--shadow: rgba(0, 0, 0, 0.6);
}
}
* { box-sizing: border-box; }
body {
margin: 0;
background: var(--page);
color: var(--ink);
font: 14px/1.45 system-ui, -apple-system, "Segoe UI", sans-serif;
}
.wrap { max-width: 1180px; margin: 0 auto; padding: 20px 24px 48px; }
header { display: flex; align-items: baseline; gap: 12px; flex-wrap: wrap; margin: 4px 0 16px; }
header h1 { font-size: 17px; font-weight: 650; margin: 0; }
header .meta { color: var(--muted); font-size: 12.5px; }
header .spacer { flex: 1; }
.dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%; margin-right: 5px; vertical-align: 1px; }
.filters { display: flex; align-items: center; gap: 16px; flex-wrap: wrap; margin-bottom: 14px; }
.seg { display: inline-flex; border: 1px solid var(--border); border-radius: 8px; overflow: hidden; background: var(--surface); }
.seg button {
appearance: none; border: 0; background: transparent; color: var(--ink-2);
font: inherit; font-size: 12.5px; padding: 5px 12px; cursor: pointer;
}
.seg button:hover { background: var(--wash); }
.seg button[aria-pressed="true"] { color: var(--ink); font-weight: 650; background: var(--wash); }
.seg button[aria-pressed="true"]::before { content: "✓ "; font-weight: 700; }
.filters .flabel { color: var(--muted); font-size: 12px; }
.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(215px, 1fr)); gap: 12px; margin-bottom: 14px; }
.card {
background: var(--surface); border: 1px solid var(--border);
border-radius: 10px; padding: 14px 16px; min-width: 0;
}
.card .label { color: var(--ink-2); font-size: 12.5px; }
.card .value { font-size: 26px; font-weight: 650; margin-top: 2px; }
.card .value.hero { font-size: 48px; line-height: 1.1; letter-spacing: -0.5px; }
.card .sub { color: var(--muted); font-size: 12px; margin-top: 2px; }
.card .sub .up { color: var(--good-text); }
.card .sub .bad { color: var(--critical); }
.card svg.spark { display: block; margin-top: 8px; }
section.panel {
background: var(--surface); border: 1px solid var(--border);
border-radius: 10px; padding: 16px; margin-bottom: 14px;
}
.panel h2 { font-size: 13.5px; font-weight: 650; margin: 0 0 2px; }
.panel .desc { color: var(--muted); font-size: 12px; margin: 0 0 10px; }
.legend { display: flex; gap: 16px; align-items: center; font-size: 12px; color: var(--ink-2); margin: 2px 0 8px; }
.legend .key { display: inline-flex; align-items: center; gap: 6px; }
.legend .swatch { width: 10px; height: 10px; border-radius: 3px; }
.chart-holder { position: relative; }
#chart { display: block; width: 100%; }
/* The hovered/focused column lifts so the mark visibly responds.
Bars are <path> (rounded data-end), so key off the class alone. */
#chart .bar { transition: filter 90ms ease-out; }
#chart g.col:hover .bar, #chart g.col:focus .bar { filter: brightness(1.15); }
/* Keyboard focus needs a visible indicator beyond the brightness
lift (WCAG 2.4.7): stroke the focused column's marks in ink. */
#chart g.col:focus { outline: none; }
#chart g.col:focus .bar { stroke: var(--ink); stroke-width: 1.5; }
@media (prefers-reduced-motion: reduce) { #chart .bar { transition: none; } }
.tooltip {
position: absolute; pointer-events: none; z-index: 5; display: none;
background: var(--surface); border: 1px solid var(--border); border-radius: 8px;
padding: 8px 10px; box-shadow: 0 4px 14px var(--shadow); font-size: 12px; min-width: 170px;
}
.tooltip .t-when { color: var(--muted); margin-bottom: 4px; }
.tooltip .t-row { display: flex; align-items: center; gap: 7px; margin-top: 2px; }
.tooltip .t-key { width: 12px; height: 0; border-top: 3px solid; border-radius: 2px; }
.tooltip .t-val { font-weight: 650; margin-left: auto; font-variant-numeric: tabular-nums; }
.tooltip .t-name { color: var(--ink-2); }
.grid2 { display: grid; grid-template-columns: 1fr 1.4fr; gap: 12px; }
@media (max-width: 900px) { .grid2 { grid-template-columns: 1fr; } }
table { width: 100%; border-collapse: collapse; font-size: 12.5px; }
th {
text-align: right; color: var(--muted); font-weight: 500; font-size: 11.5px;
padding: 4px 8px; border-bottom: 1px solid var(--grid); white-space: nowrap;
}
th:first-child, td:first-child { text-align: left; padding-left: 2px; }
td {
text-align: right; padding: 5px 8px; border-bottom: 1px solid var(--grid);
font-variant-numeric: tabular-nums; white-space: nowrap;
}
tr:last-child td { border-bottom: 0; }
tr:hover td { background: var(--wash); }
td.name { max-width: 260px; overflow: hidden; text-overflow: ellipsis; color: var(--ink); }
td .provider-key { display: inline-block; width: 8px; height: 8px; border-radius: 2px; margin-right: 7px; vertical-align: 0; }
.badge-fail { color: var(--critical); font-weight: 650; }
.empty { color: var(--muted); font-size: 12.5px; padding: 14px 2px; }
.footnote { color: var(--muted); font-size: 11.5px; margin-top: 8px; }
</style>
</head>
<body>
<div class="wrap">
<header>
<h1>Headroom Proxy — Savings</h1>
<span class="meta" id="meta-version"></span>
<span class="meta" id="meta-uptime"></span>
<span class="spacer"></span>
<span class="meta" id="meta-persist"></span>
<span class="meta" id="meta-updated"></span>
</header>
<div class="filters" role="toolbar" aria-label="Scope and history filters">
<span class="flabel">Scope</span>
<div class="seg" id="scope-seg">
<button data-scope="session" aria-pressed="true">Session</button>
<button data-scope="lifetime" aria-pressed="false">Lifetime</button>
</div>
<span class="flabel">History</span>
<div class="seg" id="bucket-seg">
<button data-bucket="hour" aria-pressed="false">48 hours</button>
<button data-bucket="day" aria-pressed="true">Daily</button>
<button data-bucket="week" aria-pressed="false">Weekly</button>
<button data-bucket="month" aria-pressed="false">Monthly</button>
</div>
</div>
<div class="cards" id="kpis"></div>
<section class="panel">
<h2>Spend vs savings over time</h2>
<p class="desc" id="chart-desc">Bar height is what this traffic would have cost without Headroom.</p>
<div class="legend" id="chart-legend"></div>
<div class="chart-holder">
<svg id="chart" height="230" role="img" aria-label="Savings over time"></svg>
<div class="tooltip" id="tooltip"></div>
</div>
<div class="empty" id="chart-empty" style="display:none">No traffic recorded yet.</div>
</section>
<div class="grid2">
<section class="panel">
<h2>By provider</h2>
<p class="desc">Requests routed through each lane (<span id="scope-label-1"></span>).</p>
<div id="providers"></div>
</section>
<section class="panel">
<h2>By model</h2>
<p class="desc">Top models by USD saved (lifetime).</p>
<div id="models"></div>
</section>
</div>
<section class="panel">
<h2>Recent requests</h2>
<p class="desc">Last requests through the proxy (newest first). Failed requests accrue no savings.</p>
<div id="feed"></div>
<p class="footnote">Savings are valued from the vendored LiteLLM price table; models missing from it record $0 (logged by the proxy).</p>
</section>
</div>
<script>
"use strict";
(() => {
const $ = (id) => document.getElementById(id);
const state = { scope: "session", bucket: "day", stats: null, series: null, events: null, seq: 0 };
// ── formatting ──────────────────────────────────────────────
const COMPACT = new Intl.NumberFormat("en-US", {
notation: "compact",
maximumFractionDigits: 1,
});
// Full digits below 10k — "9,999 tokens" reads better than "10K",
// and compact notation alone would abbreviate from 1,000.
const fmtInt = (n) => {
n = Number(n) || 0;
return Math.abs(n) >= 1e4 ? COMPACT.format(n) : n.toLocaleString("en-US");
};
// Spend spans many orders of magnitude here: a dev smoke-testing
// sees fractions of a cent, a fleet sees dollars. Fixed decimals
// collapse the small end to a useless "$0.0000", so sub-cent
// values fall back to significant digits.
const fmtUsd = (n) => {
n = Number(n) || 0;
if (n < 0) return "-" + fmtUsd(-n);
if (n === 0) return "$0";
if (n >= 1000) return "$" + (n / 1000).toFixed(1) + "K";
if (n >= 1) return "$" + n.toFixed(2);
if (n >= 0.01) return "$" + n.toFixed(3);
return "$" + n.toPrecision(2);
};
const fmtPct = (n) => (Number(n) || 0).toFixed(1) + "%";
const fmtUptime = (s) => {
s = Number(s) || 0;
if (s < 90) return s + "s";
if (s < 5400) return Math.round(s / 60) + "m";
if (s < 172800) return (s / 3600).toFixed(1) + "h";
return Math.round(s / 86400) + "d";
};
const el = (tag, cls, text) => {
const e = document.createElement(tag);
if (cls) e.className = cls;
if (text !== undefined) e.textContent = text; // untrusted-safe
return e;
};
// ── data ────────────────────────────────────────────────────
async function getJson(url) {
const r = await fetch(url, { cache: "no-store" });
if (!r.ok) throw new Error(url + " → " + r.status);
return r.json();
}
async function refresh() {
// Monotonic sequence guard: a bucket-toggle fetch racing a slow
// interval fetch must not let the stale response win.
const seq = ++state.seq;
// allSettled, not all: the three endpoints fail independently.
// /stats/events is loopback-only, so viewing this page from
// another host 404s it by design — that must not blank the spend
// panels that answered perfectly well.
const [stats, series, events] = await Promise.allSettled([
getJson("/stats"),
getJson("/stats/timeseries?bucket=" + state.bucket),
getJson("/stats/events?limit=30"),
]);
if (seq !== state.seq) return; // superseded by a newer refresh
if (stats.status === "fulfilled") state.stats = stats.value;
if (series.status === "fulfilled") state.series = series.value;
state.events = events.status === "fulfilled" ? events.value : null;
// The feed is the only endpoint whose 404 is a policy, not a
// fault — tell the reader which it was.
state.feedLocalOnly = events.status === "rejected" && /→ 404$/.test(events.reason.message);
if (stats.status === "fulfilled") {
render();
$("meta-updated").textContent = "updated " + new Date().toLocaleTimeString();
return;
}
$("meta-updated").textContent = "unreachable — retrying";
if (!state.stats) {
// Cold load with the proxy down: say so in the page body,
// not just the header corner.
const kpis = $("kpis");
kpis.textContent = "";
kpis.appendChild(el("div", "empty", "Waiting for the proxy at " + location.origin + " …"));
}
}
// ── filters ─────────────────────────────────────────────────
function wireSeg(segId, attr, onPick) {
$(segId).addEventListener("click", (ev) => {
const b = ev.target.closest("button"); if (!b) return;
for (const btn of $(segId).querySelectorAll("button"))
btn.setAttribute("aria-pressed", String(btn === b));
onPick(b.dataset[attr]);
});
}
wireSeg("scope-seg", "scope", (v) => { state.scope = v; render(); });
wireSeg("bucket-seg", "bucket", (v) => { state.bucket = v; refresh(); });
// ── header + KPIs ───────────────────────────────────────────
function scoped() {
const s = state.stats;
return state.scope === "lifetime" ? s.lifetime : s.session;
}
function renderHeader() {
const s = state.stats;
$("meta-version").textContent = "v" + (s.version || "?") + " · rust-native";
$("meta-uptime").textContent = "up " + fmtUptime(s.uptime_seconds);
const p = s.persistence || {};
const persist = $("meta-persist");
persist.textContent = "";
const dot = el("span", "dot");
dot.style.background = p.enabled && p.healthy ? "var(--good)" : (p.enabled ? "var(--critical)" : "var(--muted)");
persist.appendChild(dot);
persist.appendChild(document.createTextNode(
p.enabled ? (p.healthy ? "persisted" : "persistence error") : "memory only"
));
persist.title = p.path || "";
}
// Shared SVG element factory (sparklines + the main chart).
const SVG_NS = "http://www.w3.org/2000/svg";
function mk(tag, attrs) {
const e = document.createElementNS(SVG_NS, tag);
for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v);
return e;
}
function sparkline(points) {
const vals = points.slice(-12).map(
(p) => (Number(p.input_cost_usd) || 0) + (Number(p.output_cost_usd) || 0));
if (vals.length < 2) return null;
const w = 120, h = 28, max = Math.max(...vals, 1);
const step = w / (vals.length - 1);
const y = (v) => h - 3 - (v / max) * (h - 6);
const d = vals.map((v, i) => (i ? "L" : "M") + (i * step).toFixed(1) + " " + y(v).toFixed(1)).join(" ");
const svg = mk("svg", { class: "spark", width: w, height: h, "aria-hidden": "true" });
svg.appendChild(mk("path", {
d, fill: "none", stroke: "var(--muted)", "stroke-width": 2,
"stroke-linecap": "round", "stroke-linejoin": "round",
}));
svg.appendChild(mk("circle", {
cx: (vals.length - 1) * step, cy: y(vals[vals.length - 1]), r: 4,
fill: "var(--series-1)", stroke: "var(--surface)", "stroke-width": 2,
}));
return svg;
}
function tile({ label, value, hero, subParts, spark }) {
const card = el("div", "card");
card.appendChild(el("div", "label", label));
card.appendChild(el("div", "value" + (hero ? " hero" : ""), value));
if (subParts && subParts.length) {
const sub = el("div", "sub");
subParts.forEach((p, i) => {
if (i) sub.appendChild(document.createTextNode(" · "));
sub.appendChild(typeof p === "string" ? document.createTextNode(p) : p);
});
card.appendChild(sub);
}
if (spark) card.appendChild(spark);
return card;
}
function renderKpis() {
const t = scoped();
const hours = (state.seriesHourly && state.seriesHourly.points) || [];
const kpis = $("kpis");
kpis.textContent = "";
kpis.appendChild(tile({
label: "Saved (" + state.scope + ")",
value: fmtUsd(t.savings_usd),
hero: true,
subParts: [
fmtInt(t.tokens_saved) + " tokens removed",
el("span", "up", fmtPct(t.savings_percent) + " of would-be input"),
],
}));
kpis.appendChild(tile({
label: "Spend",
value: fmtUsd(t.total_cost_usd),
subParts: [
fmtUsd(t.input_cost_usd) + " in",
fmtUsd(t.output_cost_usd) + " out",
],
spark: hours.length ? sparkline(hours) : null,
}));
const failed = Number(t.failed) || 0;
kpis.appendChild(tile({
label: "Requests",
value: fmtInt(t.requests),
subParts: [
fmtInt(t.compressed) + " compressed",
failed ? el("span", "bad", "✕ " + fmtInt(failed) + " failed") : "0 failed",
],
}));
kpis.appendChild(tile({
label: "Cache reads",
value: fmtInt(t.cache_read_tokens),
subParts: [
fmtPct(t.cache_hit_percent) + " of input from cache",
fmtUsd(t.cache_savings_usd) + " net saved",
],
}));
$("scope-label-1").textContent = state.scope;
}
// ── the chart ───────────────────────────────────────────────
//
// Stacked part-to-whole: what you paid + what Headroom saved =
// what the traffic would have cost without it. Charting savings
// alone would leave the panel empty on the default config
// (compression is off by default), which is exactly the
// deployment that most wants to see its spend.
const SERIES = [
{
name: "Spent", color: "var(--series-1)",
usd: (p) => (Number(p.input_cost_usd) || 0) + (Number(p.output_cost_usd) || 0),
tok: (p) => (Number(p.input_tokens) || 0) + (Number(p.cache_read_tokens) || 0) +
(Number(p.cache_write_tokens) || 0),
},
{
name: "Saved", color: "var(--series-2)",
usd: (p) => (Number(p.compression_savings_usd) || 0) + (Number(p.cache_savings_usd) || 0),
tok: (p) => Number(p.tokens_saved) || 0,
},
];
function niceMax(v) {
if (v <= 0) return 1;
const exp = Math.pow(10, Math.floor(Math.log10(v)));
const m = v / exp;
return (m <= 1 ? 1 : m <= 2 ? 2 : m <= 5 ? 5 : 10) * exp;
}
function renderChart() {
const points = (state.series && state.series.points) || [];
const svg = $("chart");
svg.textContent = "";
const legend = $("chart-legend");
legend.textContent = "";
const hasTraffic = points.some((p) => (Number(p.requests) || 0) > 0);
$("chart-empty").style.display = hasTraffic ? "none" : "";
svg.style.display = hasTraffic ? "" : "none";
legend.style.display = hasTraffic ? "" : "none";
if (!hasTraffic) return;
// Nothing priced yet (e.g. every model missing from the price
// table)? Chart tokens rather than a row of flat $0 bars.
const usdTotal = points.reduce((a, p) => a + SERIES.reduce((b, s) => b + s.usd(p), 0), 0);
const mode = usdTotal > 0 ? "usd" : "tokens";
$("chart-desc").textContent = mode === "usd"
? "Bar height is what this traffic would have cost without Headroom."
: "Input tokens vs tokens saved (nothing priced yet — see the note below).";
const valOf = (p, s) => (mode === "usd" ? s.usd(p) : s.tok(p));
const fmtVal = mode === "usd" ? fmtUsd : fmtInt;
for (const s of SERIES) {
const k = el("span", "key");
const sw = el("span", "swatch"); sw.style.background = s.color;
k.appendChild(sw); k.appendChild(el("span", null, s.name));
legend.appendChild(k);
}
const W = Math.max(svg.clientWidth || 900, 320), H = 230;
// Left margin fits the widest tick: sub-cent USD renders with
// significant digits (e.g. "$0.000025"), which overflows a
// narrow gutter and clips the top label.
const m = { top: 10, right: 8, bottom: 24, left: 72 };
svg.setAttribute("viewBox", "0 0 " + W + " " + H);
const iw = W - m.left - m.right, ih = H - m.top - m.bottom;
const max = niceMax(Math.max(...points.map((p) => SERIES.reduce((a, s) => a + valOf(p, s), 0))));
// Gridlines + ticks (hairline, recessive; clean numbers).
// Token counts are integers, so quartering a niceMax of 10 would
// print "2.5 tokens". Drop to whole steps when the axis is small
// enough that quarters aren't whole.
const ticks = mode === "usd" || max % 4 === 0 ? 4 : Math.min(4, max);
for (let i = 0; i <= ticks; i++) {
const v = (max / ticks) * i, y = m.top + ih - (v / max) * ih;
if (i > 0) svg.appendChild(mk("line", { x1: m.left, x2: W - m.right, y1: y, y2: y, stroke: "var(--grid)", "stroke-width": 1 }));
const t = mk("text", { x: m.left - 8, y: y + 4, "text-anchor": "end", fill: "var(--muted)", "font-size": 11 });
t.textContent = mode === "usd" ? fmtUsd(v) : fmtInt(Math.round(v));
svg.appendChild(t);
}
svg.appendChild(mk("line", { x1: m.left, x2: W - m.right, y1: m.top + ih, y2: m.top + ih, stroke: "var(--baseline)", "stroke-width": 1 }));
const n = points.length;
const band = iw / n;
const barW = Math.min(24, Math.max(3, band * 0.6));
const gap = 2; // surface gap between stack segments
const tipEl = $("tooltip");
// Per-column keyboard stops are useful at hour/week/month density
// but hostile at daily density (up to 400 Tab presses to cross
// the chart). Past this cap, columns stay hoverable and the data
// remains reachable via /stats/timeseries; the svg's own
// aria-label summarizes the series.
const focusableColumns = n <= 90;
svg.setAttribute(
"aria-label",
"Spend vs savings, " + n + " " + state.bucket + " buckets" +
(focusableColumns ? "" : " — full data at /stats/timeseries?bucket=" + state.bucket)
);
points.forEach((p, i) => {
const x = m.left + i * band + (band - barW) / 2;
const colLabel = p.timestamp + ": " + fmtInt(p.requests) + " requests, " +
SERIES.map((s) => s.name + " " + fmtVal(valOf(p, s))).join(", ");
const colAttrs = { class: "col", role: "img", "aria-label": colLabel };
if (focusableColumns) colAttrs.tabindex = "0";
const col = mk("g", colAttrs);
let yCursor = m.top + ih;
const segs = [];
SERIES.forEach((s, si) => {
const v = valOf(p, s);
const hpx = (v / max) * ih;
if (hpx <= 0) return;
const isTop = si === SERIES.length - 1 ||
SERIES.slice(si + 1).every((s2) => valOf(p, s2) <= 0);
// Segment occupies [stackTop, bottom]; the 2px surface gap is
// shaved off THIS segment's top when another segment sits
// above it, so the sliver of background appears BETWEEN
// segments — never between the stack and the axis. The next
// segment still starts from the un-shaved stackTop.
const bottom = yCursor;
const stackTop = yCursor - hpx;
const y = stackTop + (isTop ? 0 : Math.min(gap, hpx - 1));
const drawH = Math.max(1, bottom - y);
const r = isTop ? Math.min(4, barW / 2, drawH) : 0;
// Rounded data-end (top) only; square at the baseline.
const path = "M" + x + " " + (y + drawH) +
" L" + x + " " + (y + r) +
" Q" + x + " " + y + " " + (x + r) + " " + y +
" L" + (x + barW - r) + " " + y +
" Q" + (x + barW) + " " + y + " " + (x + barW) + " " + (y + r) +
" L" + (x + barW) + " " + (y + drawH) + " Z";
segs.push(mk("path", { d: path, fill: s.color, class: "bar" }));
yCursor = stackTop;
});
segs.reverse().forEach((sEl) => col.appendChild(sEl));
// Hit target wider than the mark (full band, full height).
col.appendChild(mk("rect", { x: m.left + i * band, y: m.top, width: band, height: ih, fill: "transparent" }));
const show = () => {
tipEl.textContent = "";
tipEl.appendChild(el("div", "t-when", p.timestamp));
SERIES.forEach((s) => {
const row = el("div", "t-row");
const key = el("span", "t-key"); key.style.borderTopColor = s.color;
row.appendChild(key);
row.appendChild(el("span", "t-name", s.name));
row.appendChild(el("span", "t-val", fmtVal(valOf(p, s))));
tipEl.appendChild(row);
});
const meta = el("div", "t-when");
meta.style.marginTop = "5px";
meta.textContent = fmtInt(p.requests) + " req · " + fmtInt(p.tokens_saved) +
" tok saved" + (Number(p.failed) ? " · " + fmtInt(p.failed) + " failed" : "");
tipEl.appendChild(meta);
tipEl.style.display = "block";
const holder = svg.parentElement.getBoundingClientRect();
const frac = (m.left + i * band + band / 2) / W;
let left = frac * holder.width - tipEl.offsetWidth / 2;
left = Math.max(0, Math.min(left, holder.width - tipEl.offsetWidth));
tipEl.style.left = left + "px";
tipEl.style.top = "6px";
};
const hide = () => { tipEl.style.display = "none"; };
col.addEventListener("pointerenter", show);
col.addEventListener("pointerleave", hide);
col.addEventListener("focus", show);
col.addEventListener("blur", hide);
svg.appendChild(col);
// Sparse x labels: first, last, and every ~quarter.
if (i === 0 || i === n - 1 || (n > 6 && i % Math.ceil(n / 4) === 0)) {
const t = mk("text", {
x: m.left + i * band + band / 2, y: H - 7,
"text-anchor": "middle", fill: "var(--muted)", "font-size": 11,
});
t.textContent = shortLabel(p.timestamp);
svg.appendChild(t);
}
});
}
function shortLabel(ts) {
if (!ts) return "";
if (state.bucket === "hour") return ts.slice(11, 16) || ts;
if (state.bucket === "month") return ts;
return ts.slice(5); // MM-DD
}
// ── tables ──────────────────────────────────────────────────
function table(headers, rows, emptyMsg) {
if (!rows.length) return el("div", "empty", emptyMsg);
const t = el("table");
const tr = el("tr");
headers.forEach((h) => {
const th = el("th", null, h);
th.setAttribute("scope", "col");
tr.appendChild(th);
});
t.appendChild(tr);
rows.forEach((cells) => {
const r = el("tr");
cells.forEach((c) => r.appendChild(c));
t.appendChild(r);
});
return t;
}
const PROVIDER_COLOR = {
anthropic: "var(--series-1)", openai_chat: "var(--series-2)",
openai_responses: "var(--series-2)", bedrock: "var(--series-1)", vertex: "var(--series-2)",
};
function renderProviders() {
const s = state.stats;
const map = state.scope === "lifetime" ? s.lifetime_by_provider : s.session_by_provider;
const rows = Object.entries(map || {}).map(([name, t]) => {
const nameCell = el("td", "name");
nameCell.appendChild(el("span", null, name));
return [
nameCell,
el("td", null, fmtInt(t.requests)),
el("td", null, fmtInt(t.tokens_saved)),
el("td", null, fmtUsd(t.savings_usd)),
el("td", null, fmtInt(t.failed)),
];
});
const holder = $("providers");
holder.textContent = "";
holder.appendChild(table(
["Provider", "Requests", "Tok saved", "Saved", "Failed"],
rows, "No traffic in this scope yet."));
}
function renderModels() {
const s = state.stats;
const entries = Object.entries(s.lifetime_by_model || {})
.sort((a, b) => (b[1].savings_usd + b[1].total_cost_usd) - (a[1].savings_usd + a[1].total_cost_usd))
.slice(0, 10);
const rows = entries.map(([name, t]) => [
el("td", "name", name),
el("td", null, fmtInt(t.requests)),
el("td", null, fmtInt(t.tokens_saved)),
el("td", null, fmtInt(t.cache_read_tokens)),
el("td", null, fmtUsd(t.savings_usd)),
el("td", null, fmtUsd(t.total_cost_usd)),
]);
const holder = $("models");
holder.textContent = "";
holder.appendChild(table(
["Model", "Requests", "Tok saved", "Cache reads", "Saved", "Spend"],
rows, "No models recorded yet."));
}
function renderFeed() {
const events = (state.events && state.events.events) || [];
const rows = events.map((e) => {
const when = el("td", null, (e.timestamp || "").slice(11, 19));
const model = el("td", "name");
const pk = el("span", "provider-key");
pk.style.background = PROVIDER_COLOR[e.provider] || "var(--muted)";
model.appendChild(pk);
model.appendChild(el("span", null, (e.provider || "?") + " · " + (e.model || "?")));
model.title = e.request_id || "";
const status = el("td");
if (e.failed) status.appendChild(el("span", "badge-fail", "✕ failed"));
else status.appendChild(el("span", null, fmtPct(e.compression_percent)));
// Input column: the provider-billed (uncached) input is the
// number that always exists. Only show the compression
// before→after arrow when compression actually ran — otherwise
// it reads a meaningless "0 → 0".
const inputCell = Number(e.tokens_before) > 0
? el("td", null, fmtInt(e.tokens_before) + " → " + fmtInt(e.tokens_after))
: el("td", null, fmtInt(e.input_tokens));
return [
when, model,
inputCell,
el("td", null, fmtInt(e.tokens_saved)),
el("td", null, fmtInt(e.cache_read_tokens) + " / " + fmtInt(e.cache_write_tokens)),
el("td", null, fmtInt(e.output_tokens)),
el("td", null, fmtUsd((Number(e.compression_savings_usd) || 0) + (Number(e.cache_savings_usd) || 0))),
el("td", null, (Number(e.latency_ms) || 0) + "ms"),
status,
];
});
const holder = $("feed");
holder.textContent = "";
if (state.feedLocalOnly) {
// Not an error: the per-request feed is served to local callers
// only. Say which, so nobody debugs a working proxy.
holder.appendChild(el("div", "empty",
"The per-request feed is available to local callers only. " +
"Totals above cover all traffic; open this dashboard on the proxy host " +
"(or over a tunnel to it) to see individual requests."));
return;
}
holder.appendChild(table(
["Time", "Lane · model", "Input tok", "Saved", "Cache r/w", "Out tok", "Saved $", "Latency", "Compr %"],
rows, "No requests yet — point a client at this proxy and refresh."));
}
function render() {
if (!state.stats) return;
renderHeader();
renderKpis();
renderChart();
renderProviders();
renderModels();
renderFeed();
}
// Keep an hourly series around for the KPI sparkline regardless of
// the selected history bucket.
async function refreshHourly() {
try { state.seriesHourly = await getJson("/stats/timeseries?bucket=hour"); } catch (e) { /* keep last */ }
}
refreshHourly().then(refresh);
setInterval(refresh, 3000);
setInterval(refreshHourly, 15000);
window.addEventListener("resize", () => state.stats && renderChart());
})();
</script>
</body>
</html>
File diff suppressed because it is too large Load Diff
@@ -39,10 +39,14 @@
//! revisit if multi-process aggregation lands.
pub mod cache_hit_rate;
pub mod capture;
pub mod compression_ratio;
pub mod ledger;
pub mod metric_names;
pub mod pricing;
pub mod prometheus;
pub mod proxy_metrics;
pub mod stats_http;
pub use prometheus::{
handle_metrics, observe_bedrock_invoke_latency, record_bedrock_eventstream_message,
@@ -0,0 +1,414 @@
//! Per-token USD pricing — Phase H. Used to value spend and savings.
//!
//! Reads the LiteLLM price table already vendored for
//! [`crate::compression::model_limits`] — one embedded copy, two
//! consumers. No new data file, and no startup network dependency:
//! the table ships inside the binary and parses lazily on first
//! lookup.
//!
//! # Lookup discipline
//!
//! Lookup is exact-match over a small, deterministic candidate list
//! derived from the request's model id (lowercased, then: geo prefix
//! stripped, `:rev` suffix trimmed, provider path segment dropped).
//! We deliberately do NOT substring-scan the table: a short or
//! generic id must miss (and be logged) rather than misprice against
//! whichever stored id happens to contain it.
//!
//! **The unmodified id is always tried first**, because Bedrock
//! cross-region pricing is genuinely region-specific — e.g.
//! `eu.anthropic.claude-3-5-haiku-20241022-v1:0` bills at $0.25/M
//! against `anthropic.claude-3-5-haiku-20241022-v1:0`'s $0.80/M. Any
//! region the table tracks therefore gets its true price. The
//! geo-stripped candidate is only a *fallback* for a (region, model)
//! pair the table does not list, where the base price is a far
//! better estimate than $0 — approximate, but never silently
//! preferred over an exact regional entry.
//!
//! # Coverage
//!
//! The vendored snapshot tracks current model generations plus every
//! Bedrock/Vertex-prefixed id, but it does not carry every legacy
//! direct-API id (`claude-3-5-sonnet-20241022`, for one, is absent
//! while its Bedrock form is present). Those price at $0 with a WARN
//! until the table is refreshed — see the module note below.
//!
//! # Unknown models price at $0
//!
//! A miss returns `None`; the ledger then records $0 for every USD
//! field and this module logs one WARN naming the model. We
//! deliberately do NOT substitute a blended fallback rate: phantom
//! dollars on a cost dashboard are worse than an obvious zero, and
//! the WARN tells an operator exactly which id to add by refreshing
//! the vendored table (`scripts/refresh_model_limits.sh`).
use std::collections::HashMap;
use std::sync::{OnceLock, RwLock};
use crate::bedrock::vendor::strip_geo_prefix;
use crate::compression::model_limits::VENDORED_JSON;
/// Per-token USD prices for one model. All fields are $/token
/// (LiteLLM stores them that way natively — no per-million
/// conversion happens here).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ModelPrice {
pub input: f64,
pub output: f64,
pub cache_read: f64,
pub cache_write: f64,
}
impl ModelPrice {
/// USD saved by removing `tokens_saved` input tokens before they
/// were sent (compression savings).
pub fn compression_savings_usd(&self, tokens_saved: u64) -> f64 {
tokens_saved as f64 * self.input
}
/// NET USD saved by prompt caching for one request: the read
/// discount (`reads × (input − cache_read)`) minus the write
/// premium (`writes × (cache_write − input)` — cache writes bill
/// ABOVE list price, typically 1.25×). Reporting the gross read
/// discount alone overstates the benefit on write-heavy traffic,
/// which is exactly the phantom-dollars failure mode this module
/// exists to avoid. Floored at $0 per request: a warm-up turn
/// that only writes is an investment, not negative savings —
/// its real cost is already carried by [`Self::input_cost_usd`].
///
/// Known bias, stated because it's the honest thing to state:
/// the ledger sums these per-request values, and a floored
/// request contributes 0 rather than its true negative, so
/// `sum(max(0, net))` ≥ `max(0, sum(net))`. Aggregate cache
/// savings therefore skew slightly high. The gap is one write
/// premium per floored request, which in practice means the
/// first turn of a session: once a prefix is cached, later turns
/// read far more than they write and net positive well clear of
/// the floor (100k reads + 5k writes on Sonnet nets +$0.266, vs
/// a $0.004 premium). Fixing it properly means accumulating a
/// signed net and flooring once at the aggregate — worth doing
/// if cache-heavy traffic ever makes the skew material, but not
/// worth a signed accumulator (and a persisted-negative
/// migration) for single-digit thousandths of a cent today.
pub fn cache_savings_usd(&self, cache_read_tokens: u64, cache_write_tokens: u64) -> f64 {
let read_discount = (self.input - self.cache_read).max(0.0);
let write_premium = (self.cache_write - self.input).max(0.0);
let net =
cache_read_tokens as f64 * read_discount - cache_write_tokens as f64 * write_premium;
net.max(0.0)
}
/// USD spent on generated output for a request. Output bills at
/// its own rate — typically 4-5x input — so a "spend" figure that
/// omits it understates the bill by more than it reports on a
/// short-prompt/long-answer turn.
pub fn output_cost_usd(&self, output_tokens: u64) -> f64 {
output_tokens as f64 * self.output
}
/// USD actually spent on input for a request, using the cache
/// breakdown when any segment is non-zero (never adding the
/// total on top of the breakdown — that would double-count).
pub fn input_cost_usd(
&self,
uncached_input_tokens: u64,
cache_read_tokens: u64,
cache_write_tokens: u64,
) -> f64 {
uncached_input_tokens as f64 * self.input
+ cache_read_tokens as f64 * self.cache_read
+ cache_write_tokens as f64 * self.cache_write
}
}
static BOOK: OnceLock<HashMap<String, ModelPrice>> = OnceLock::new();
/// Bounded once-per-model warn set so an unknown model logs one WARN,
/// not one per request. Capped so attacker-controlled model ids can't
/// grow it without bound; once full, further unknown models simply
/// stop logging (they still price at $0). RwLock so the steady-state
/// path for an already-known-unknown model (every miss after the
/// first) is a shared read, not serialized writes on the record path.
static WARNED: OnceLock<RwLock<std::collections::HashSet<String>>> = OnceLock::new();
const WARNED_CAP: usize = 256;
/// Parse the vendored table now instead of on the first recorded
/// request. Called once at startup (main.rs) so the ~1.4 MB JSON
/// parse never stalls tokio workers when a burst of first requests
/// lands together.
pub fn warm() {
let _ = book();
}
fn book() -> &'static HashMap<String, ModelPrice> {
BOOK.get_or_init(parse_vendored)
}
fn parse_vendored() -> HashMap<String, ModelPrice> {
let raw: serde_json::Value = serde_json::from_str(VENDORED_JSON)
.expect("vendored LiteLLM JSON must parse — same invariant as model_limits");
let mut out = HashMap::new();
let Some(obj) = raw.as_object() else {
return out;
};
for (model_id, spec) in obj {
if model_id == "sample_spec" {
continue;
}
let Some(spec) = spec.as_object() else {
continue;
};
let input = spec.get("input_cost_per_token").and_then(|v| v.as_f64());
let output = spec.get("output_cost_per_token").and_then(|v| v.as_f64());
let (Some(input), Some(output)) = (input, output) else {
continue;
};
if !input.is_finite() || !output.is_finite() || input < 0.0 || output < 0.0 {
continue;
}
let cache_read = spec
.get("cache_read_input_token_cost")
.and_then(|v| v.as_f64())
.filter(|c| c.is_finite() && *c >= 0.0)
.unwrap_or(input);
let cache_write = spec
.get("cache_creation_input_token_cost")
.and_then(|v| v.as_f64())
.filter(|c| c.is_finite() && *c >= 0.0)
.unwrap_or(input);
out.insert(
model_id.to_ascii_lowercase(),
ModelPrice {
input,
output,
cache_read,
cache_write,
},
);
}
out
}
/// Candidate keys tried, in order, for a request model id. Exact
/// matches only — see module doc for why there is no substring scan.
fn candidates(model: &str) -> Vec<String> {
let lower = model.trim().to_ascii_lowercase();
let mut out = Vec::with_capacity(6);
let mut push = |s: String| {
if !s.is_empty() && !out.contains(&s) {
out.push(s);
}
};
push(lower.clone());
// Bedrock cross-region profile: `eu.anthropic.claude…` falls back
// to `anthropic.claude…` when the region itself isn't in the
// table. GEO_PREFIXES (shared with the compression vendor gate)
// covers every geo the vendored table fronts, `us-gov.` included.
let geo = strip_geo_prefix(&lower).to_string();
push(geo.clone());
// Bedrock revision suffix: `…-v1:0`. ONLY a numeric suffix is
// trimmed. A non-numeric colon suffix is a routing/tier variant
// (`:exacto`, `:free`, `:nitro`) that can genuinely bill at its
// own rate — the vendored table lists
// `openrouter/z-ai/glm-4.6` at $0.40/M and its `:exacto` variant
// at $0.45/M. Trimming those would hand an uncatalogued variant
// its sibling's price with no warning: a confident wrong number,
// which this module exists to avoid. They miss and WARN instead.
push_revision_trimmed(&mut push, &geo);
push_revision_trimmed(&mut push, &lower);
// Provider-routed ids (`openai/gpt-4o`, `github-copilot/claude…`):
// the bare tail is how LiteLLM stores first-party models. Try the
// tail both verbatim and `:rev`-trimmed, so a combined
// `vendor/model:rev` id can still reach a fully-stripped entry.
if let Some((_, tail)) = lower.rsplit_once('/') {
push(tail.to_string());
push_revision_trimmed(&mut push, tail);
}
out
}
/// Push `id` minus a trailing `:<digits>` revision, if it has one.
fn push_revision_trimmed(push: &mut impl FnMut(String), id: &str) {
if let Some((head, rev)) = id.rsplit_once(':') {
if !rev.is_empty() && rev.bytes().all(|b| b.is_ascii_digit()) {
push(head.to_string());
}
}
}
/// Look up per-token pricing for a model id. `None` means "not in
/// the vendored table" — the caller records $0 for USD fields and
/// this module logs one WARN per distinct model id.
pub fn lookup(model: &str) -> Option<ModelPrice> {
let table = book();
for key in candidates(model) {
if let Some(p) = table.get(&key) {
return Some(*p);
}
}
warn_once(model);
None
}
fn warn_once(model: &str) {
let set = WARNED.get_or_init(|| RwLock::new(std::collections::HashSet::new()));
{
let read = set
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner);
if read.len() >= WARNED_CAP || read.contains(model) {
return;
}
}
let mut write = set
.write()
.unwrap_or_else(std::sync::PoisonError::into_inner);
if write.len() >= WARNED_CAP || !write.insert(model.to_string()) {
return;
}
drop(write);
tracing::warn!(
event = "stats_price_unknown_model",
model = %model,
"model id not in the vendored price table; both spend AND savings \
for it record as $0 — refresh data/model_prices_and_context_window.json \
via scripts/refresh_model_limits.sh to add it"
);
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn known_anthropic_direct_id_prices() {
let p = lookup("claude-sonnet-4-5-20250929").expect("priced");
assert!(p.input > 0.0 && p.output > p.input);
assert!(p.cache_read < p.input, "cache reads are discounted");
assert!(p.cache_write > p.input, "cache writes carry a premium");
}
/// Bedrock cross-region pricing is region-specific, so an exact
/// regional entry must win over the geo-stripped base id.
#[test]
fn exact_regional_bedrock_entry_wins_over_base() {
let base = lookup("anthropic.claude-3-5-haiku-20241022-v1:0").expect("base priced");
let eu = lookup("eu.anthropic.claude-3-5-haiku-20241022-v1:0").expect("eu priced");
assert!(
(base.input - 8e-7).abs() < 1e-12,
"base id prices at list rate, got {}",
base.input
);
assert!(
(eu.input - 2.5e-7).abs() < 1e-12,
"eu id must use its own regional rate, got {}",
eu.input
);
assert_ne!(
base, eu,
"geo-stripping must not clobber a tracked regional price"
);
}
/// A region the table does NOT list falls back to the base id —
/// approximate, but far better than $0.
/// Every published geo prefix must fall back to the base entry
/// when the table doesn't carry that exact (region, model) pair.
/// Table-driven over GEO_PREFIXES itself, so adding a prefix
/// without its pricing fallback fails here — the `au.`/`jp.`/
/// `us-gov.` gap this PR fixes was exactly that.
#[test]
fn every_geo_prefix_falls_back_to_base_price() {
const BASE: &str = "anthropic.claude-3-5-haiku-20241022-v1:0";
let base = lookup(BASE).expect("base priced");
for geo in crate::bedrock::vendor::GEO_PREFIXES {
let id = format!("{geo}{BASE}");
if book().get(&id).is_some() {
continue; // table lists this region explicitly — priced on its own terms
}
assert_eq!(
lookup(&id).unwrap_or_else(|| panic!("{id} must fall back")),
base,
"{geo} must strip to the base entry when unlisted"
);
}
}
#[test]
fn provider_path_segment_falls_back_to_bare_tail() {
let bare = lookup("gpt-4o").expect("bare id priced");
let routed = lookup("openai/gpt-4o").expect("routed id priced");
assert_eq!(bare, routed);
}
#[test]
fn unknown_model_misses_instead_of_mispricing() {
assert!(lookup("claude").is_none(), "generic id must not match");
assert!(lookup("totally-unknown-model-xyz").is_none());
assert!(lookup("").is_none());
}
#[test]
fn case_insensitive_lookup() {
assert_eq!(
lookup("GPT-4o").expect("priced"),
lookup("gpt-4o").expect("priced")
);
}
/// A combined `vendor/model:rev` id must reach a table entry
/// stored fully stripped — the slash-tail is also tried with its
/// `:rev` suffix trimmed.
#[test]
fn provider_path_and_revision_compose() {
let bare = lookup("gpt-4o").expect("bare id priced");
let combined = lookup("openai/gpt-4o:2").expect("combined form priced");
assert_eq!(bare, combined, "provider path + numeric revision compose");
}
/// A non-numeric colon suffix is a pricing-relevant variant, not a
/// revision. It must NOT inherit the bare model's rate: the table
/// prices `openrouter/z-ai/glm-4.6` at $0.40/M and `:exacto` at
/// $0.45/M, so borrowing across that boundary invents dollars.
#[test]
fn variant_suffix_never_borrows_the_bare_models_price() {
let bare = lookup("openrouter/z-ai/glm-4.6").expect("bare variant priced");
let exacto = lookup("openrouter/z-ai/glm-4.6:exacto").expect("listed variant priced");
assert_ne!(bare.input, exacto.input, "fixture guard: these must differ");
// An UNLISTED variant must miss loudly, not silently take the
// bare price.
assert!(
lookup("openrouter/z-ai/glm-4.6:priority").is_none(),
"an uncatalogued variant must record $0 + WARN, never a guessed rate"
);
}
#[test]
fn usd_helpers_compute_list_price_math() {
let p = ModelPrice {
input: 3e-6,
output: 15e-6,
cache_read: 3e-7,
cache_write: 3.75e-6,
};
assert!((p.compression_savings_usd(1_000_000) - 3.0).abs() < 1e-9);
// Cache savings = read discount, NET of the write premium.
assert!((p.cache_savings_usd(1_000_000, 0) - 2.7).abs() < 1e-9);
// 1M reads save $2.70; 1M writes cost a $0.75 premium → net $1.95.
assert!((p.cache_savings_usd(1_000_000, 1_000_000) - 1.95).abs() < 1e-9);
// Write-only warm-up floors at $0, never negative savings
// (the premium itself is billed via input_cost_usd).
assert_eq!(p.cache_savings_usd(0, 1_000_000), 0.0);
// Breakdown input cost: uncached + cache_read + cache_write.
let usd = p.input_cost_usd(1_000_000, 1_000_000, 1_000_000);
assert!((usd - (3.0 + 0.3 + 3.75)).abs() < 1e-9);
// Inverted cache pricing clamps to $0, never negative savings.
let inverted = ModelPrice {
input: 1e-6,
output: 1e-6,
cache_read: 2e-6,
cache_write: 1e-6,
};
assert_eq!(inverted.cache_savings_usd(1000, 0), 0.0);
}
}
@@ -0,0 +1,216 @@
//! HTTP surface for the native savings ledger — Phase H:
//! `GET /stats`, `GET /stats/timeseries`, `GET /stats/events`, and
//! the embedded `GET /dashboard` page.
//!
//! All handlers are read-only snapshots over
//! [`super::ledger::Ledger`] — no handler can mutate accounting
//! state. Mounted by [`crate::proxy::build_app`] when
//! `Config::stats` is explicitly enabled; when off (the default), the paths fall through
//! to the catch-all forwarder like any other route.
//!
//! # Exposure: aggregate tier is open, per-request tier is local-only
//!
//! There is no auth here, and `--listen` defaults to `0.0.0.0:8787`,
//! so the payloads are split by sensitivity the same way the Python
//! proxy splits its own `/stats`:
//!
//! - **Aggregates** (spend, tokens, per-model/provider rollups,
//! history) are served to anyone, like the Prometheus `/metrics`
//! endpoint next door — same data class, same stance.
//! - **Per-request rows** (`recent_requests`, all of
//! `/stats/events`) and the ledger's filesystem path are served
//! only to local callers ([`caller_is_local`]). A request id plus a
//! model plus a timestamp is a different tier from a counter, and
//! `/metrics` never exposes it — so "same as /metrics" would be the
//! wrong argument for handing it to the open internet.
//!
//! `--stats=false` removes the routes entirely. Making the local-only
//! tier reachable from a trusted reverse proxy is tracked upstream in
//! headroomlabs-ai/headroom#1959, which is defining that policy for
//! the Python dashboard first; this surface should adopt whatever
//! lands there rather than invent a second scheme.
use std::net::{IpAddr, SocketAddr};
use axum::extract::{ConnectInfo, Query, State};
use axum::http::header::HOST;
use axum::http::{HeaderMap, StatusCode};
use axum::response::{Html, IntoResponse, Response};
use axum::Json;
use serde::Deserialize;
use serde_json::Value;
use crate::proxy::AppState;
/// True when the caller is genuinely local — gates the per-request
/// tier of `/stats` and the whole of `/stats/events`.
///
/// BOTH conditions are required, mirroring the Python proxy's
/// `loopback_guard`:
///
/// 1. the TCP peer is a loopback address, and
/// 2. the `Host` header names loopback.
///
/// (2) is not redundant with (1) — it is the DNS-rebinding defence. A
/// hostile page can rebind its own domain to `127.0.0.1`, so the
/// victim's browser connects to this proxy *from* loopback and (1)
/// passes, while `Host` still reads the attacker's name and their JS
/// reads the response. A real local tool always sends a loopback
/// `Host`; a rebound request does not.
pub(crate) fn caller_is_local(peer: SocketAddr, headers: &HeaderMap) -> bool {
peer.ip().is_loopback()
&& headers
.get(HOST)
.and_then(|h| h.to_str().ok())
.is_some_and(host_is_loopback)
}
/// `127.0.0.1`, `127.0.0.1:8787`, `[::1]:8787`, `localhost:8787`, …
fn host_is_loopback(host: &str) -> bool {
let host = host.trim();
// A bare IP with no port must be recognised before any port
// split: `::1` is all colons.
if let Ok(ip) = host.parse::<IpAddr>() {
return ip.is_loopback();
}
let name = match host.strip_prefix('[') {
Some(rest) => match rest.split_once(']') {
Some((inner, _)) => inner,
None => return false,
},
None => host.rsplit_once(':').map_or(host, |(h, _)| h),
};
name.eq_ignore_ascii_case("localhost")
|| name.parse::<IpAddr>().is_ok_and(|ip| ip.is_loopback())
}
/// The dashboard page, embedded at compile time so the binary is
/// self-contained (no template dir to deploy, no CDN dependency).
const DASHBOARD_HTML: &str = include_str!("dashboard.html");
pub async fn handle_stats(
State(state): State<AppState>,
ConnectInfo(peer): ConnectInfo<SocketAddr>,
headers: HeaderMap,
) -> Json<Value> {
Json(state.stats.stats_payload(caller_is_local(peer, &headers)))
}
#[derive(Deserialize)]
pub struct TimeseriesParams {
/// hour | day | week | month (default: day)
bucket: Option<String>,
}
pub async fn handle_timeseries(
State(state): State<AppState>,
Query(params): Query<TimeseriesParams>,
) -> Response {
let bucket = params.bucket.as_deref().unwrap_or("day");
match state.stats.timeseries_payload(bucket) {
Some(payload) => Json(payload).into_response(),
None => (
StatusCode::BAD_REQUEST,
// The Anthropic-style envelope the Bedrock lanes emit
// (`bedrock::invoke::error_response`). Note this is NOT
// universal: `ProxyError` renders plain text, and axum's
// `Query` extractor rejects a malformed `?bucket=` with
// its own plain-text 400 before this handler runs — so a
// client can't assume JSON for every 4xx from this path.
Json(serde_json::json!({
"error": {
"type": "unknown_bucket",
"message": "bucket must be one of: hour, day, week, month",
}
})),
)
.into_response(),
}
}
#[derive(Deserialize)]
pub struct EventsParams {
limit: Option<usize>,
}
/// This endpoint is per-request metadata end to end — there is no
/// aggregate tier to hand a network caller, so the whole thing is
/// gated. 404 rather than 403, matching the Python guard's stance:
/// keep the surface invisible to scanners rather than merely refuse
/// them.
pub async fn handle_events(
State(state): State<AppState>,
ConnectInfo(peer): ConnectInfo<SocketAddr>,
headers: HeaderMap,
Query(params): Query<EventsParams>,
) -> Response {
if !caller_is_local(peer, &headers) {
return (StatusCode::NOT_FOUND, "not found").into_response();
}
Json(state.stats.events_payload(params.limit.unwrap_or(50))).into_response()
}
/// `Html` already sets `text/html; charset=utf-8`.
pub async fn handle_dashboard() -> Html<&'static str> {
Html(DASHBOARD_HTML)
}
#[cfg(test)]
mod tests {
use super::*;
fn headers_with_host(host: &str) -> HeaderMap {
let mut h = HeaderMap::new();
h.insert(HOST, host.parse().unwrap());
h
}
fn peer(addr: &str) -> SocketAddr {
addr.parse().unwrap()
}
#[test]
fn local_caller_needs_loopback_peer_and_loopback_host() {
for host in [
"127.0.0.1:8787",
"127.0.0.1",
"localhost:8787",
"LOCALHOST",
"[::1]:8787",
"::1",
"127.5.6.7:8787", // the whole 127/8 block is loopback
] {
assert!(
caller_is_local(peer("127.0.0.1:5555"), &headers_with_host(host)),
"{host} should read as local"
);
}
}
/// The DNS-rebinding case, and the entire reason the `Host` check
/// exists: the victim's browser really is on loopback, so the peer
/// check alone would wave this through while attacker JS reads the
/// per-request feed.
#[test]
fn loopback_peer_with_foreign_host_is_not_local() {
for host in ["attacker.com", "attacker.com:8787", "evil.localhost.dev"] {
assert!(
!caller_is_local(peer("127.0.0.1:5555"), &headers_with_host(host)),
"{host} must not read as local — DNS rebinding"
);
}
}
#[test]
fn remote_peer_is_never_local_even_claiming_a_loopback_host() {
assert!(!caller_is_local(
peer("10.1.2.3:5555"),
&headers_with_host("127.0.0.1:8787")
));
}
#[test]
fn missing_host_header_fails_closed() {
assert!(!caller_is_local(peer("127.0.0.1:5555"), &HeaderMap::new()));
}
}
+227 -14
View File
@@ -26,6 +26,7 @@ use crate::config::Config;
use crate::error::ProxyError;
use crate::headers::{build_forward_request_headers, filter_response_headers};
use crate::health::{healthz, healthz_upstream, rollout_status};
use crate::observability::{capture, ledger};
use crate::websocket::ws_handler;
// Phase F PR-F1: imported as `classify_auth_mode` to make the call
// site self-documenting. `AuthMode` is re-exported under the same
@@ -80,6 +81,13 @@ pub struct AppState {
/// route hits `bearer()`. Tests override via
/// [`AppState::with_token_source`].
pub vertex_token_source: Arc<dyn crate::vertex::TokenSource>,
/// Native savings ledger (one per process). Loaded from
/// `Config::stats_path` when persistence is configured, else
/// in-memory. Handlers record into it after each finished
/// request; `/stats*` and `/dashboard` read from it. Recording
/// call sites gate on `Config::stats` — when stats are disabled
/// this is an inert in-memory ledger.
pub stats: Arc<ledger::Ledger>,
}
/// PR-E6: maximum number of sessions tracked by the drift detector
@@ -126,6 +134,15 @@ impl AppState {
let vertex_token_source: Arc<dyn crate::vertex::TokenSource> =
Arc::new(crate::vertex::adc::GcpAdcTokenSource::new());
let stats = if config.stats {
match config.stats_path.clone() {
Some(path) => Arc::new(ledger::Ledger::load(path)),
None => Arc::new(ledger::Ledger::in_memory()),
}
} else {
Arc::new(ledger::Ledger::in_memory())
};
Ok(Self {
config: Arc::new(config),
client,
@@ -135,6 +152,7 @@ impl AppState {
cache_stabilization::beta_sticky::BETA_TRACKER_CAPACITY,
),
vertex_token_source,
stats,
})
}
@@ -199,7 +217,39 @@ pub fn build_app(state: AppState) -> Router {
let mut router = Router::new()
.route("/healthz", get(healthz))
.route("/healthz/upstream", get(healthz_upstream))
.route("/rollout/status", get(rollout_status))
.route("/rollout/status", get(rollout_status));
// Native savings stats + dashboard. Served locally (never
// tunnelled upstream) so the Rust proxy is self-sufficient for
// savings observability. Gated on `--stats` so an operator can
// restore pure-passthrough behaviour for these paths.
if state.config.stats {
router = router
.route(
"/stats",
get(crate::observability::stats_http::handle_stats),
)
.route(
"/stats/timeseries",
get(crate::observability::stats_http::handle_timeseries),
)
.route(
"/stats/events",
get(crate::observability::stats_http::handle_events),
)
.route(
"/dashboard",
get(crate::observability::stats_http::handle_dashboard),
);
} else {
tracing::warn!(
event = "stats_disabled",
"native savings stats disabled by --stats=false; \
/stats*, /dashboard fall through to the upstream forwarder \
and no request telemetry is recorded"
);
}
router = router
// PR-C2: explicit POST route for /v1/chat/completions. The
// handler buffers the body and re-injects it into
// `forward_http`, which runs the OpenAI live-zone gate
@@ -614,10 +664,10 @@ pub(crate) async fn forward_http(
// controls what the buffered branch does (currently both `Off`
// and `LiveZone` passthrough); Phase B will branch on it inside
// `compress_anthropic_request`.
let should_intercept = state.config.compression
&& method == axum::http::Method::POST
let is_llm_json_post = method == axum::http::Method::POST
&& compression::is_compressible_path(uri.path())
&& is_application_json(req.headers());
let should_intercept = state.config.compression && is_llm_json_post;
// PR-E6: capture a header snapshot BEFORE the body is consumed so
// the drift detector can derive a per-session key from
@@ -635,6 +685,33 @@ pub(crate) async fn forward_http(
let reqwest_method = reqwest::Method::from_bytes(method.as_str().as_bytes())
.map_err(|e| ProxyError::InvalidHeader(e.to_string()))?;
// Savings ledger. Deliberately NOT gated on `should_intercept`:
// spend/caching stats are worth answering on a pure passthrough
// deployment too (compression savings are truthfully 0 there),
// so the gate is the LLM-endpoint shape alone and the model id
// is learned from the response when the request didn't carry it.
// Finalized exactly once, when the response is fully observed.
let should_record = state.config.stats && is_llm_json_post;
let mut pending_stats = should_record
.then(|| compression::classify_compressible_path(uri.path()))
.flatten()
.map(|endpoint| {
let provider = match endpoint {
compression::CompressibleEndpoint::AnthropicMessages => ledger::provider::ANTHROPIC,
compression::CompressibleEndpoint::OpenAiChatCompletions => {
ledger::provider::OPENAI_CHAT
}
compression::CompressibleEndpoint::OpenAiResponses => {
ledger::provider::OPENAI_RESPONSES
}
};
capture::PendingRecord::new(
state.stats.clone(),
ledger::RequestEvent::new(provider, "", &request_id),
start,
)
});
let upstream_resp = if should_intercept {
// Buffer up to `compression_max_body_bytes`. If the body
// exceeds this, the body is already partially consumed and
@@ -660,6 +737,9 @@ pub(crate) async fn forward_http(
"compression: Content-Length exceeds buffer limit; \
returning 413 without consuming body"
);
// A proxy-side rejection is still an outcome:
// record it as failed rather than dropping it.
capture::finalize_rejected(pending_stats.take());
return Err(ProxyError::PayloadTooLarge(format!(
"request Content-Length {len} exceeds compression \
buffer limit ({max} bytes)"
@@ -677,6 +757,7 @@ pub(crate) async fn forward_http(
"compression: body exceeds buffer limit; failing loudly (cannot \
resume streaming once the body has been partially consumed)"
);
capture::finalize_rejected(pending_stats.take());
return Err(ProxyError::PayloadTooLarge(format!(
"request body exceeds compression buffer limit ({max} bytes): {e}"
)));
@@ -735,7 +816,14 @@ pub(crate) async fn forward_http(
// enough that a canonical-bytes hash would compare apples
// to oranges. The volatile detector handles its own
// shape-dispatch via `ApiKind::from_endpoint`.
let mut stats_model: Option<String> = None;
if let Ok(parsed) = serde_json::from_slice::<serde_json::Value>(&buffered) {
// Model id for the savings ledger — read from the same
// sanitized bytes the dispatcher compresses.
stats_model = parsed
.get("model")
.and_then(|m| m.as_str())
.map(str::to_owned);
// PR-E5: volatile-content detector. Emits one WARN per
// finding (capped at 10) for content that busts cache
// (timestamps, UUIDs, ID-named fields).
@@ -807,6 +895,10 @@ pub(crate) async fn forward_http(
}
}
}
// Compression-side numbers for the savings ledger, captured
// out of the Compressed arm below (the outcome is consumed
// by the body-selection match).
let mut stats_compression: (u64, u64, Vec<String>) = (0, 0, Vec::new());
let outcome = match endpoint {
compression::CompressibleEndpoint::AnthropicMessages => {
// PR-E3: thread the F1-classified auth_mode into the
@@ -892,6 +984,11 @@ pub(crate) async fn forward_http(
markers_inserted,
per_strategy_tokens,
} => {
stats_compression = (
tokens_before as u64,
tokens_after as u64,
strategies_applied.iter().map(|s| s.to_string()).collect(),
);
tracing::info!(
request_id = %request_id,
path = %path_for_log,
@@ -1012,34 +1109,71 @@ pub(crate) async fn forward_http(
compression::CompressibleEndpoint::AnthropicMessages => body_to_send,
};
if let Some(p) = pending_stats.as_mut() {
// Request-side model (already `[1m]`-sanitized above, so
// it matches what upstream bills) wins over the response
// echo; the compression numbers are only knowable here.
if let Some(m) = stats_model.as_deref() {
p.set_model(m);
}
let (before, after, transforms) = stats_compression;
p.set_compression(before, after, transforms);
}
// Forward the (Phase A: identical) buffered bytes. reqwest
// sets its own Content-Length from the body bytes — the
// existing `build_forward_request_headers` already strips
// the client-supplied Content-Length for us.
state
match state
.client
.request(reqwest_method, upstream_url.clone())
.headers(outgoing_headers)
.body(body_to_send)
.send()
.await?
.await
{
Ok(resp) => resp,
Err(e) => {
// Transport/connect failures are request outcomes
// too — record them so outages are visible in /stats.
capture::finalize_rejected(pending_stats.take());
return Err(e.into());
}
}
} else {
// Pure streaming path — the original passthrough behaviour.
let body_stream =
TryStreamExt::map_err(req.into_body().into_data_stream(), std::io::Error::other);
let reqwest_body = reqwest::Body::wrap_stream(body_stream);
state
match state
.client
.request(reqwest_method, upstream_url.clone())
.headers(outgoing_headers)
.body(reqwest_body)
.send()
.await?
.await
{
Ok(resp) => resp,
Err(e) => {
// Same contract as the buffered arm.
capture::finalize_rejected(pending_stats.take());
return Err(e.into());
}
}
};
let upstream_status = upstream_resp.status();
let status = StatusCode::from_u16(upstream_status.as_u16()).unwrap_or(StatusCode::BAD_GATEWAY);
// Savings honesty rule: a non-2xx upstream is a failed request —
// it counts, but accrues no savings (the ledger enforces this on
// the failed flag).
if !upstream_status.is_success() {
if let Some(p) = pending_stats.as_mut() {
p.mark_failed();
}
}
// PR-A8 / P5-57: capture the upstream request id BEFORE we move
// `upstream_resp.headers()` into the response filter. Anthropic
// emits `request-id` (lowercase, no `x-`); OpenAI emits
@@ -1155,8 +1289,32 @@ pub(crate) async fn forward_http(
let parser_tx = if !matches!(sse_kind, SseStreamKind::None) {
let (tx, rx) = tokio::sync::mpsc::channel::<bytes::Bytes>(SSE_PARSER_QUEUE_DEPTH);
let rid_for_parser = request_id.clone();
tokio::spawn(run_sse_state_machine(sse_kind, rx, rid_for_parser));
// Deferred recording: the pending stats event rides into the
// state machine and is finalized when the stream closes, so
// output/cache token counts come from the real SSE usage
// frames instead of recording zero at header time.
tokio::spawn(run_sse_state_machine(
sse_kind,
rx,
rid_for_parser,
pending_stats.take(),
));
Some(tx)
} else if let Some(p) = pending_stats.take() {
// Non-SSE response on a recorded LLM path: tee the JSON body
// into a bounded buffer and parse usage when it completes.
let shape = match SseStreamKind::for_request_path(&path_for_log) {
SseStreamKind::OpenAiChat => capture::ResponseShape::OpenAiChat,
SseStreamKind::OpenAiResponses => capture::ResponseShape::OpenAiResponses,
// Anthropic (/v1/messages). Note: /v1/responses with the
// streaming state machine disabled still matches the
// OpenAiResponses arm above — for_request_path classifies
// by path, independent of the enable flag. An SSE body
// teed here simply fails the JSON parse and records
// compression-side numbers alone.
_ => capture::ResponseShape::Anthropic,
};
Some(capture::spawn_json_usage_capture(shape, p))
} else {
None
};
@@ -1221,11 +1379,9 @@ pub(crate) async fn forward_http(
}
/// Bound on the in-flight queue between the byte-passthrough and the
/// SSE state-machine task. Picked so that under steady-state streaming
/// load (~5 events/100ms typical) the parser is never blocked on
/// queue space, yet a stalled parser can't grow memory unboundedly.
/// Tunable via `proxy.toml` if a deployment finds this insufficient.
const SSE_PARSER_QUEUE_DEPTH: usize = 256;
/// SSE state-machine task — see [`TEE_QUEUE_DEPTH`] for the sizing
/// rationale it shares with every other telemetry tee.
use crate::observability::capture::TEE_QUEUE_DEPTH as SSE_PARSER_QUEUE_DEPTH;
/// Which provider's state machine should run on this stream. Picked
/// from the *request* path because the response content-type
@@ -1381,10 +1537,15 @@ fn maybe_inject_openai_prompt_cache_key(
/// Drive the per-provider state machine over a stream of byte chunks.
/// Lives in its own task; the byte path never waits on it.
///
/// `pending_stats` (when the savings ledger is recording this
/// request) is finalized here — after the stream closes — with the
/// usage the state machine accumulated.
async fn run_sse_state_machine(
kind: SseStreamKind,
mut rx: tokio::sync::mpsc::Receiver<bytes::Bytes>,
request_id: String,
pending_stats: Option<capture::PendingRecord>,
) {
use crate::sse::framing::SseFramer;
@@ -1455,6 +1616,20 @@ async fn run_sse_state_machine(
blocks = state.blocks.len(),
"sse stream closed"
);
if let Some(mut p) = pending_stats {
if let Some(model) = state.model.as_deref() {
p.set_model_if_unknown(model);
}
// A 200 OK stream can still fail in-band: Anthropic
// emits `{"type":"error"}` mid-stream (e.g. overloaded
// during generation) and the state machine lands in
// `Errored`. That is not a billable success — record
// it as failed so retries can't inflate savings.
if matches!(state.status, crate::sse::anthropic::StreamStatus::Errored) {
p.mark_failed();
}
p.finalize(capture::usage_from_anthropic_state(&state));
}
}
SseStreamKind::OpenAiChat => {
let mut state = crate::sse::openai_chat::ChunkState::new();
@@ -1558,6 +1733,19 @@ async fn run_sse_state_machine(
has_usage = state.usage.is_some(),
"sse stream closed"
);
if let Some(mut p) = pending_stats {
if let Some(model) = state.model.as_deref() {
p.set_model_if_unknown(model);
}
let usage = state
.usage
.as_ref()
.and_then(|u| {
capture::usage_from_usage_block(capture::ResponseShape::OpenAiChat, u)
})
.unwrap_or_default();
p.finalize(usage);
}
}
SseStreamKind::OpenAiResponses => {
let mut state = crate::sse::openai_responses::ResponseState::new();
@@ -1689,8 +1877,33 @@ async fn run_sse_state_machine(
incomplete_reason = state.incomplete_reason.as_deref().unwrap_or(""),
"sse stream closed"
);
if let Some(mut p) = pending_stats {
if let Some(model) = state.model.as_deref() {
p.set_model_if_unknown(model);
}
// `response.failed` / `response.incomplete` are not
// billable successes — count them as failures even
// though the HTTP status was 2xx.
if matches!(state.terminal_status(), Some("failed") | Some("incomplete")) {
p.mark_failed();
}
let usage = state
.usage
.as_ref()
.and_then(|u| {
capture::usage_from_usage_block(capture::ResponseShape::OpenAiResponses, u)
})
.unwrap_or_default();
p.finalize(usage);
}
}
SseStreamKind::None => {
if let Some(p) = pending_stats {
// No parser for this stream — record what the
// request side knew (compression estimates only).
p.finalize(ledger::Usage::default());
}
}
SseStreamKind::None => {}
}
}
+29
View File
@@ -124,6 +124,35 @@ impl SseFramer {
if chunk.is_empty() {
return;
}
// Cap the accumulator: a stream that never emits a blank-line
// terminator (a non-SSE body routed here, or a hostile
// upstream) would otherwise grow this buffer for the life of
// the stream. A real SSE event is a few KB; 4 MiB is orders
// of magnitude past any legitimate frame.
//
// On overflow we drop the buffer and the triggering chunk, so
// parsing resumes mid-stream at an arbitrary byte offset.
// Usually that garbage forms a prefix-less line the parser
// ignores; it CAN also resume on a syntactically valid
// `data:` line and yield one truncated event. That is
// acceptable only because every consumer is a telemetry tee
// off the byte path (`SseFramer` is never on the client
// path — see the three callers), so the worst case is a wrong
// usage number for one stream, bounded further by the
// ledger's own per-event token ceiling. Client bytes are
// never touched. Revisit this cap before framing anything
// client-facing with it.
const MAX_BUFFERED_BYTES: usize = 4 * 1024 * 1024;
if self.buf.len() + chunk.len() > MAX_BUFFERED_BYTES {
tracing::warn!(
event = "sse_framer_buffer_overflow",
buffered = self.buf.len(),
"no event terminator within 4 MiB; discarding buffered \
bytes (telemetry-only consumer — client stream unaffected)"
);
self.buf.clear();
return;
}
self.buf.extend_from_slice(chunk);
}
+16
View File
@@ -90,6 +90,7 @@ use axum::http::{HeaderMap, Method, StatusCode, Uri};
use axum::response::Response;
use std::net::SocketAddr;
use crate::observability::{capture, ledger};
use crate::proxy::AppState;
/// Single axum handler mounted at the
@@ -157,6 +158,15 @@ pub async fn handle_vertex_predict_dispatch(
segment = %model_action,
"vertex path final segment missing `:verb` separator"
);
// A proxy-side rejection is still an outcome for this
// request. The model id is whatever the caller sent (it
// is what failed to parse); the ledger clamps it.
capture::finalize_rejected(capture::start_pending(
&state,
ledger::provider::VERTEX,
&model_action,
&request_id,
));
return Response::builder()
.status(StatusCode::NOT_FOUND)
.body(Body::from("vertex path: bad model_action"))
@@ -173,6 +183,12 @@ pub async fn handle_vertex_predict_dispatch(
verb = %verb_str,
"vertex path verb not recognized; only rawPredict / streamRawPredict are supported"
);
capture::finalize_rejected(capture::start_pending(
&state,
ledger::provider::VERTEX,
model_id,
&request_id,
));
return Response::builder()
.status(StatusCode::NOT_FOUND)
.body(Body::from("vertex: unknown verb"))
@@ -36,6 +36,8 @@ use std::net::SocketAddr;
use crate::compression;
use crate::headers::{build_forward_request_headers, filter_response_headers};
use crate::observability::capture::TEE_QUEUE_DEPTH as VERTEX_SSE_QUEUE_DEPTH;
use crate::observability::{capture, ledger};
use crate::proxy::AppState;
use crate::vertex::{adc::TokenSourceError, envelope, VertexVerb};
@@ -76,6 +78,13 @@ pub(crate) async fn forward_vertex_request(
) -> Response {
let path_for_log = uri.path().to_string();
// Constructed at handler ENTRY so every exit — including
// proxy-side rejections (oversized body, envelope mismatch, ADC
// failure) — records exactly once. An ADC outage must show in
// /stats as a failure spike, not zero traffic.
let mut pending_stats =
capture::start_pending(&state, ledger::provider::VERTEX, &ctx.model_id, &request_id);
// ─── 1. BUFFER BODY ────────────────────────────────────────────────
let max = state.config.compression_max_body_bytes as usize;
let buffered = match to_bytes(body, max).await {
@@ -89,6 +98,7 @@ pub(crate) async fn forward_vertex_request(
error = %e,
"vertex request body exceeds compression buffer limit; failing loudly"
);
capture::finalize_rejected(pending_stats.take());
return error_response(
StatusCode::PAYLOAD_TOO_LARGE,
"request body exceeds buffer limit",
@@ -122,6 +132,7 @@ pub(crate) async fn forward_vertex_request(
error = %e,
"vertex envelope did not match expected shape; rejecting with 400"
);
capture::finalize_rejected(pending_stats.take());
return error_response(StatusCode::BAD_REQUEST, "vertex envelope invalid");
}
}
@@ -133,6 +144,7 @@ pub(crate) async fn forward_vertex_request(
// The dispatcher uses RawValue-based surgery so `anthropic_version`
// (and any other non-`messages` top-level field) round-trips
// byte-equal. Compression off → buffered bytes used unchanged.
let mut stats_compression: (u64, u64, Vec<String>) = (0, 0, Vec::new());
let body_to_send = if state.config.compression {
// PR-E3: Vertex uses GCP ADC bearer-token auth downstream, not
// Anthropic credentials, so the PAYG/OAuth/subscription
@@ -177,6 +189,11 @@ pub(crate) async fn forward_vertex_request(
markers = markers_inserted.len(),
"vertex live-zone compression applied"
);
stats_compression = (
tokens_before as u64,
tokens_after as u64,
strategies_applied.iter().map(|s| s.to_string()).collect(),
);
body
}
compression::Outcome::Passthrough { reason } => {
@@ -201,6 +218,11 @@ pub(crate) async fn forward_vertex_request(
buffered
};
if let Some(p) = pending_stats.as_mut() {
let (before, after, transforms) = stats_compression;
p.set_compression(before, after, transforms);
}
// ─── 4. RESOLVE BEARER TOKEN ───────────────────────────────────────
let bearer = match state.vertex_token_source.bearer().await {
Ok(t) => t,
@@ -221,6 +243,7 @@ pub(crate) async fn forward_vertex_request(
TokenSourceError::ProviderInit(_) => StatusCode::BAD_GATEWAY,
TokenSourceError::Fetch(_) => StatusCode::BAD_GATEWAY,
};
capture::finalize_rejected(pending_stats.take());
return error_response(status, "vertex ADC token fetch failed");
}
};
@@ -248,6 +271,7 @@ pub(crate) async fn forward_vertex_request(
error = %e,
"could not construct vertex upstream URL"
);
capture::finalize_rejected(pending_stats.take());
return error_response(StatusCode::BAD_GATEWAY, "vertex upstream URL build failed");
}
};
@@ -293,6 +317,7 @@ pub(crate) async fn forward_vertex_request(
error = %e,
"ADC bearer token contained invalid header bytes; refusing to forward"
);
capture::finalize_rejected(pending_stats.take());
return error_response(StatusCode::BAD_GATEWAY, "vertex auth header build failed");
}
}
@@ -308,9 +333,11 @@ pub(crate) async fn forward_vertex_request(
error = %e,
"could not convert axum method to reqwest method"
);
capture::finalize_rejected(pending_stats.take());
return error_response(StatusCode::BAD_REQUEST, "vertex method invalid");
}
};
let upstream_resp = match state
.client
.request(reqwest_method, upstream_url.clone())
@@ -321,6 +348,9 @@ pub(crate) async fn forward_vertex_request(
{
Ok(r) => r,
Err(e) => {
if let Some(p) = pending_stats.take() {
p.finalize_failed();
}
tracing::warn!(
event = "vertex_upstream_error",
request_id = %request_id,
@@ -335,6 +365,11 @@ pub(crate) async fn forward_vertex_request(
// ─── 8. STREAM RESPONSE ────────────────────────────────────────────
let upstream_status = upstream_resp.status();
let status = StatusCode::from_u16(upstream_status.as_u16()).unwrap_or(StatusCode::BAD_GATEWAY);
if !upstream_status.is_success() {
if let Some(p) = pending_stats.as_mut() {
p.mark_failed();
}
}
let resp_headers = filter_response_headers(upstream_resp.headers());
// PR-C1 reuse: when `attach_sse_tee` is set AND the upstream
@@ -355,7 +390,11 @@ pub(crate) async fn forward_vertex_request(
let parser_tx = if attach_sse_tee && is_sse {
let (tx, rx) = tokio::sync::mpsc::channel::<bytes::Bytes>(VERTEX_SSE_QUEUE_DEPTH);
let rid = request_id.clone();
tokio::spawn(run_anthropic_sse_state_machine(rx, rid));
tokio::spawn(run_anthropic_sse_state_machine(
rx,
rid,
pending_stats.take(),
));
tracing::info!(
event = "vertex_sse_tee_engaged",
request_id = %request_id,
@@ -363,7 +402,12 @@ pub(crate) async fn forward_vertex_request(
);
Some(tx)
} else {
None
// Non-SSE (rawPredict, or a JSON error on the streaming
// verb): tee the body into a bounded buffer and parse the
// Anthropic-shape usage block when it completes.
pending_stats
.take()
.map(|p| capture::spawn_json_usage_capture(capture::ResponseShape::Anthropic, p))
};
use futures_util::StreamExt as _;
@@ -434,13 +478,6 @@ fn error_response(status: StatusCode, msg: &'static str) -> Response {
.expect("static error response")
}
/// Bound on the in-flight queue between the byte-passthrough and the
/// SSE state-machine task. Mirrors the
/// `crate::proxy::SSE_PARSER_QUEUE_DEPTH` rationale (256 events ≈ 5
/// seconds of typical Anthropic streaming under the per-100ms event
/// rate; keeps memory bounded even if the parser stalls).
const VERTEX_SSE_QUEUE_DEPTH: usize = 256;
/// Drive the Anthropic SSE state machine over a stream of byte
/// chunks. Lives in its own spawned task; the byte path is fed via a
/// best-effort tee from [`forward_vertex_request`] and never blocks
@@ -448,6 +485,7 @@ const VERTEX_SSE_QUEUE_DEPTH: usize = 256;
async fn run_anthropic_sse_state_machine(
mut rx: tokio::sync::mpsc::Receiver<bytes::Bytes>,
request_id: String,
pending_stats: Option<capture::PendingRecord>,
) {
use crate::sse::framing::SseFramer;
let mut framer = SseFramer::new();
@@ -487,4 +525,12 @@ async fn run_anthropic_sse_state_machine(
blocks = state.blocks.len(),
"vertex sse stream closed"
);
if let Some(mut p) = pending_stats {
// In-band `{"type":"error"}` on a 200 OK stream is not a
// billable success (same rule as the direct Anthropic lane).
if matches!(state.status, crate::sse::anthropic::StreamStatus::Errored) {
p.mark_failed();
}
p.finalize(capture::usage_from_anthropic_state(&state));
}
}
+14
View File
@@ -111,3 +111,17 @@ pub fn install_static_token_source(mut state: AppState, bearer: &str) -> AppStat
pub fn _config_ref() -> Arc<Config> {
Arc::new(Config::for_test(Url::parse("http://127.0.0.1:1").unwrap()))
}
/// Static, obviously-fake AWS credentials for SigV4-signing tests.
/// Shared by every Bedrock test binary — the mock upstream never
/// validates the signature, only that one is present.
#[allow(dead_code)]
pub fn test_credentials() -> aws_credential_types::Credentials {
aws_credential_types::Credentials::new(
"AKIAEXAMPLEAKIDFORTEST",
"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
None,
None,
"test",
)
}
@@ -20,14 +20,13 @@
mod common;
use aws_credential_types::Credentials;
use axum::body::Body;
use axum::extract::{Extension, State};
use axum::http::StatusCode;
use axum::routing::post;
use axum::Router;
use bytes::Bytes;
use common::start_proxy_with_state;
use common::{start_proxy_with_state, test_credentials};
use headroom_core::auth_mode::AuthMode;
use headroom_proxy::AppState;
use serde_json::{json, Value};
@@ -41,16 +40,6 @@ use wiremock::{Mock, MockServer, ResponseTemplate};
const TEST_MODEL: &str = "anthropic.claude-3-haiku-20240307-v1:0";
fn test_credentials() -> Credentials {
Credentials::new(
"AKIAEXAMPLEAKIDFORTEST",
"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
None,
None,
"test",
)
}
#[derive(Default, Clone, Debug)]
struct CapturedRequest {
body: Option<Vec<u8>>,
@@ -35,8 +35,7 @@
mod common;
use aws_credential_types::Credentials;
use common::start_proxy_with_state;
use common::{start_proxy_with_state, test_credentials};
use serde_json::{json, Value};
use sha2::{Digest, Sha256};
use std::sync::{Arc, Mutex};
@@ -132,16 +131,6 @@ fn assert_byte_equal_sha256(inbound: &[u8], received: &[u8]) {
);
}
fn test_credentials() -> Credentials {
Credentials::new(
"AKIAEXAMPLEAKIDFORTEST",
"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
None,
None,
"test",
)
}
/// Boot a proxy pointed at the wiremock upstream as the Bedrock
/// endpoint. The fake-upstream URL goes into `bedrock_endpoint`;
/// the regular `upstream` field is set to a sentinel because the
@@ -23,9 +23,8 @@
mod common;
use aws_credential_types::Credentials;
use bytes::{Bytes, BytesMut};
use common::start_proxy_with_state;
use common::{start_proxy_with_state, test_credentials};
use headroom_proxy::bedrock::MessageBuilder;
use serde_json::json;
use url::Url;
@@ -49,16 +48,6 @@ const TEST_REGION_LATENCY: &str = "us-test-latency-1";
const TEST_REGION_EVENTSTREAM: &str = "us-test-eventstream-1";
const TEST_REGION_SCRAPE: &str = "us-test-scrape-1";
fn test_credentials() -> Credentials {
Credentials::new(
"AKIAEXAMPLEAKIDFORTEST",
"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
None,
None,
"test",
)
}
async fn bedrock_proxy_with_region(
upstream: &MockServer,
region: &str,
@@ -22,9 +22,8 @@
mod common;
use aws_credential_types::Credentials;
use bytes::{Bytes, BytesMut};
use common::start_proxy_with_state;
use common::{start_proxy_with_state, test_credentials};
use headroom_proxy::bedrock::{
parse_eventstream, CrcValidation, EventStreamParser, HeaderValue, MessageBuilder, ParseError,
};
@@ -36,16 +35,6 @@ use wiremock::{Mock, MockServer, ResponseTemplate};
const TEST_MODEL: &str = "anthropic.claude-3-haiku-20240307-v1:0";
fn test_credentials() -> Credentials {
Credentials::new(
"AKIAEXAMPLEAKIDFORTEST",
"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
None,
None,
"test",
)
}
/// Synthesise a minimal Bedrock-shape Anthropic stream as binary
/// EventStream bytes. The exact JSON payload mirrors what real
/// Bedrock emits for a 2-token completion.
@@ -577,3 +566,77 @@ proptest! {
}
}
}
/// Regression (caught in review of the first stats PR, #1057; the fix
/// never landed with it): in SSE-translation mode, an unknown
/// `:event-type` (`TranslateOutcome::Skip`) arriving in the same
/// upstream chunk as known messages must not strand the known
/// messages in the parser buffer. The pre-fix drain shape pulled a
/// FRESH upstream chunk after a Skip, so when the Skip'd frame sat in
/// the final chunk, every complete message buffered behind it was
/// dropped and the client's stream ended early.
#[tokio::test]
async fn skip_in_final_chunk_does_not_strand_buffered_frames() {
// One chunk, three messages: known → unknown → known.
let mut buf = bytes::BytesMut::new();
let frame = |event_type: &str, payload: serde_json::Value| {
MessageBuilder::new()
.header_string(":event-type", event_type)
.header_string(":content-type", "application/json")
.header_string(":message-type", "event")
.payload(Bytes::from(serde_json::to_string(&payload).unwrap()))
.build()
};
buf.extend_from_slice(&frame(
"chunk",
serde_json::json!({"type": "message_start",
"message": {"id": "m1", "usage": {"input_tokens": 3}}}),
));
buf.extend_from_slice(&frame(
"somethingNewFromAws",
serde_json::json!({"novel": true}),
));
buf.extend_from_slice(&frame("chunk", serde_json::json!({"type": "message_stop"})));
let body = buf.freeze();
let upstream = MockServer::start().await;
Mock::given(method("POST"))
.and(path(
"/model/anthropic.claude-3-haiku-20240307-v1:0/invoke-with-response-stream",
))
.respond_with(
ResponseTemplate::new(200)
.insert_header("content-type", "application/vnd.amazon.eventstream")
.set_body_raw(body.to_vec(), "application/vnd.amazon.eventstream"),
)
.mount(&upstream)
.await;
let proxy = bedrock_proxy(&upstream, |_| {}).await;
let resp = reqwest::Client::new()
.post(format!(
"{}/model/anthropic.claude-3-haiku-20240307-v1:0/invoke-with-response-stream",
proxy.url()
))
.header("content-type", "application/json")
.header("accept", "text/event-stream")
.json(&serde_json::json!({
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 8,
"messages": [{"role": "user", "content": "hi"}]
}))
.send()
.await
.unwrap();
assert_eq!(resp.status(), 200);
let text = resp.text().await.unwrap();
assert!(
text.contains("message_start"),
"frame before the Skip must arrive: {text}"
);
assert!(
text.contains("message_stop"),
"frame buffered BEHIND the Skip'd message must still arrive \
(pre-fix behaviour dropped it): {text}"
);
}
@@ -0,0 +1,911 @@
//! Integration tests for the native savings stats surface:
//! `/stats`, `/stats/timeseries`, `/stats/events`, `/dashboard`,
//! and the per-lane recording hooks (deferred SSE finalization,
//! non-streaming JSON usage capture, failed-request accounting,
//! Bedrock camelCase usage).
mod common;
use std::time::Duration;
use common::{
install_static_token_source, start_proxy_with, start_proxy_with_state, test_credentials,
};
use headroom_proxy::bedrock::MessageBuilder;
use serde_json::{json, Value};
use url::Url;
use wiremock::matchers::{method, path, path_regex};
use wiremock::{Mock, MockServer, ResponseTemplate};
/// The capture tasks finalize asynchronously after the client sees
/// the response — poll /stats until the predicate holds.
async fn wait_for_stats<F>(base: &str, pred: F) -> Value
where
F: Fn(&Value) -> bool,
{
let client = reqwest::Client::new();
for _ in 0..100 {
let v: Value = client
.get(format!("{base}/stats"))
.send()
.await
.expect("GET /stats")
.json()
.await
.expect("stats json");
if pred(&v) {
return v;
}
tokio::time::sleep(Duration::from_millis(50)).await;
}
panic!("stats predicate not satisfied within 5s");
}
/// POST a JSON body the way every recording test does.
async fn post_json(url: String, body: &Value) -> reqwest::Response {
reqwest::Client::new()
.post(url)
.header("content-type", "application/json")
.json(body)
.send()
.await
.expect("POST")
}
/// One binary EventStream frame with the standard event headers.
fn event_frame(event_type: &str, payload: &Value) -> bytes::Bytes {
MessageBuilder::new()
.header_string(":message-type", "event")
.header_string(":event-type", event_type)
.header_string(":content-type", "application/json")
.payload(payload.to_string().into())
.build()
}
#[tokio::test]
async fn stats_endpoints_serve_locally_and_validate_input() {
let upstream = MockServer::start().await;
let proxy = start_proxy_with(&upstream.uri(), |_| {}).await;
let client = reqwest::Client::new();
let stats: Value = client
.get(format!("{}/stats", proxy.url()))
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert_eq!(stats["proxy"], "headroom-rust");
assert_eq!(stats["requests"]["total"], 0);
// headway's unified-stats reader contract.
assert!(stats["summary"]["api_requests"].is_u64());
assert!(stats["tokens"]["proxy_compression_saved"].is_u64());
assert!(stats["requests"]["cached"].is_u64());
let ts: Value = client
.get(format!("{}/stats/timeseries?bucket=day", proxy.url()))
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert_eq!(ts["bucket"], "day");
let bad = client
.get(format!("{}/stats/timeseries?bucket=fortnight", proxy.url()))
.send()
.await
.unwrap();
assert_eq!(bad.status(), 400);
let events: Value = client
.get(format!("{}/stats/events", proxy.url()))
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert!(events["events"].as_array().unwrap().is_empty());
let dash = client
.get(format!("{}/dashboard", proxy.url()))
.send()
.await
.unwrap();
assert_eq!(dash.status(), 200);
let ct = dash
.headers()
.get("content-type")
.unwrap()
.to_str()
.unwrap();
assert!(ct.starts_with("text/html"), "content-type: {ct}");
let body = dash.text().await.unwrap();
assert!(body.contains("Headroom Proxy — Savings"));
// Self-contained page: no network resource references of any
// kind. The only URLs allowed are XML namespaces and data: URIs.
for needle in [
"src=\"http",
"src=\"//",
"href=\"http",
"href=\"//",
"@import",
"fonts.googleapis",
"cdn.",
] {
assert!(
!body.contains(needle),
"dashboard must be self-contained; found {needle:?}"
);
}
}
#[tokio::test]
async fn stats_disabled_falls_through_to_upstream() {
let upstream = MockServer::start().await;
Mock::given(method("GET"))
.and(path("/stats"))
.respond_with(ResponseTemplate::new(200).set_body_string("python-proxy-stats"))
.mount(&upstream)
.await;
let proxy = start_proxy_with(&upstream.uri(), |c| c.stats = false).await;
let body = reqwest::Client::new()
.get(format!("{}/stats", proxy.url()))
.send()
.await
.unwrap()
.text()
.await
.unwrap();
assert_eq!(
body, "python-proxy-stats",
"with --stats=false the path must tunnel upstream (pre-feature behaviour)"
);
}
#[tokio::test]
async fn anthropic_non_streaming_response_records_usage() {
let upstream = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/v1/messages"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"id": "msg_1",
"type": "message",
"model": "claude-sonnet-4-5-20250929",
"content": [{"type": "text", "text": "hi"}],
"usage": {
"input_tokens": 100,
"output_tokens": 25,
"cache_read_input_tokens": 40,
"cache_creation_input_tokens": 10
}
})))
.mount(&upstream)
.await;
// compression=true engages the buffered arm (mode stays Off —
// recording must work in pure-passthrough deployments too).
let proxy = start_proxy_with(&upstream.uri(), |c| c.compression = true).await;
let resp = post_json(
format!("{}/v1/messages", proxy.url()),
&json!({
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 32,
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap(); // drain so the capture tee closes
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(stats["tokens"]["input"], 100);
assert_eq!(stats["tokens"]["output"], 25);
assert_eq!(stats["tokens"]["cache_read"], 40);
assert_eq!(stats["tokens"]["cache_write"], 10);
assert_eq!(stats["requests"]["failed"], 0);
// 40 cache-read tokens ⇒ this request counts as a cache hit.
assert_eq!(stats["requests"]["cached"], 1);
assert_eq!(stats["session_by_provider"]["anthropic"]["requests"], 1);
// 40 cache reads on sonnet pricing → non-zero cache savings.
assert!(stats["session"]["cache_savings_usd"].as_f64().unwrap() > 0.0);
assert!(stats["session"]["input_cost_usd"].as_f64().unwrap() > 0.0);
// Model attribution landed.
assert_eq!(
stats["lifetime_by_model"]["claude-sonnet-4-5-20250929"]["requests"],
1
);
// Timeseries picked it up.
let ts: Value = reqwest::Client::new()
.get(format!("{}/stats/timeseries?bucket=hour", proxy.url()))
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert_eq!(ts["points"][0]["requests"], 1);
}
/// Recording must not depend on the compression master switch —
/// it is OFF by default, and spend/cache observability is the whole
/// point of the feature on a passthrough deployment. The model is
/// learned from the response there (the request body is never
/// buffered), and compression savings are legitimately 0.
#[tokio::test]
async fn records_with_compression_off_using_model_from_response() {
let upstream = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/v1/messages"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"id": "msg_1",
"type": "message",
"model": "claude-sonnet-4-5-20250929",
"content": [{"type": "text", "text": "hi"}],
"usage": {"input_tokens": 200, "output_tokens": 10,
"cache_read_input_tokens": 80}
})))
.mount(&upstream)
.await;
// Config::for_test defaults compression to false — same as the
// shipped binary's default.
let proxy = start_proxy_with(&upstream.uri(), |c| {
assert!(!c.compression, "guard: this test covers compression OFF");
})
.await;
let resp = post_json(
format!("{}/v1/messages", proxy.url()),
&json!({
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 32,
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap();
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(stats["tokens"]["input"], 200);
assert_eq!(stats["tokens"]["cache_read"], 80);
assert_eq!(stats["tokens"]["saved"], 0, "no compression ran → 0 saved");
// Model came from the response envelope, so spend is priced.
assert_eq!(
stats["lifetime_by_model"]["claude-sonnet-4-5-20250929"]["requests"], 1,
"model must be learned from the response when the request isn't buffered"
);
assert!(stats["session"]["input_cost_usd"].as_f64().unwrap() > 0.0);
assert!(stats["session"]["cache_savings_usd"].as_f64().unwrap() > 0.0);
}
#[tokio::test]
async fn anthropic_sse_stream_records_deferred_usage() {
let upstream = MockServer::start().await;
let sse_body = concat!(
"event: message_start\n",
"data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_1\",\"usage\":",
"{\"input_tokens\":50,\"output_tokens\":1,\"cache_read_input_tokens\":12}}}\n\n",
"event: content_block_delta\n",
"data: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":",
"{\"type\":\"text_delta\",\"text\":\"hey\"}}\n\n",
"event: message_delta\n",
"data: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\"},",
"\"usage\":{\"output_tokens\":30}}\n\n",
"event: message_stop\n",
"data: {\"type\":\"message_stop\"}\n\n",
);
Mock::given(method("POST"))
.and(path("/v1/messages"))
.respond_with(
ResponseTemplate::new(200)
.insert_header("content-type", "text/event-stream")
.set_body_raw(sse_body.as_bytes().to_vec(), "text/event-stream"),
)
.mount(&upstream)
.await;
let proxy = start_proxy_with(&upstream.uri(), |c| c.compression = true).await;
let resp = post_json(
format!("{}/v1/messages", proxy.url()),
&json!({
"model": "claude-haiku-4-5-20251001",
"max_tokens": 32,
"stream": true,
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap();
// Deferred recording: counts come from the stream's usage
// frames, observed only after the stream closed.
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(stats["tokens"]["input"], 50);
assert_eq!(
stats["tokens"]["output"], 30,
"output from message_delta, not 0"
);
assert_eq!(stats["tokens"]["cache_read"], 12);
}
#[tokio::test]
async fn failed_upstream_counts_but_accrues_no_savings() {
let upstream = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/v1/messages"))
.respond_with(ResponseTemplate::new(529).set_body_json(json!({
"type": "error",
"error": {"type": "overloaded_error", "message": "overloaded"}
})))
.mount(&upstream)
.await;
let proxy = start_proxy_with(&upstream.uri(), |c| c.compression = true).await;
let resp = post_json(
format!("{}/v1/messages", proxy.url()),
&json!({
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 32,
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 529);
let _ = resp.bytes().await.unwrap();
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(stats["requests"]["failed"], 1);
assert_eq!(stats["tokens"]["saved"], 0);
assert_eq!(stats["session"]["savings_usd"], 0.0);
assert_eq!(stats["session"]["input_cost_usd"], 0.0);
// Visible in the feed, flagged.
let events: Value = reqwest::Client::new()
.get(format!("{}/stats/events?limit=5", proxy.url()))
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert_eq!(events["events"][0]["failed"], true);
assert_eq!(events["events"][0]["tokens_saved"], 0);
}
#[tokio::test]
async fn openai_chat_response_normalises_cached_tokens() {
let upstream = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/v1/chat/completions"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"id": "chatcmpl-1",
"object": "chat.completion",
"model": "gpt-4o",
"choices": [{"index": 0, "message": {"role": "assistant", "content": "hi"},
"finish_reason": "stop"}],
"usage": {
"prompt_tokens": 90,
"completion_tokens": 12,
"prompt_tokens_details": {"cached_tokens": 60}
}
})))
.mount(&upstream)
.await;
let proxy = start_proxy_with(&upstream.uri(), |c| c.compression = true).await;
let resp = post_json(
format!("{}/v1/chat/completions", proxy.url()),
&json!({
"model": "gpt-4o",
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap();
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
// prompt_tokens INCLUDES cached — the ledger stores the split.
assert_eq!(stats["tokens"]["input"], 30);
assert_eq!(stats["tokens"]["cache_read"], 60);
assert_eq!(stats["tokens"]["output"], 12);
// Provider label matches the Prometheus vocabulary
// (`metric_names`): the chat lane is `openai_chat`, not `openai`.
assert_eq!(stats["session_by_provider"]["openai_chat"]["requests"], 1);
}
#[tokio::test]
async fn bedrock_converse_sync_records_camelcase_usage() {
let upstream = MockServer::start().await;
let model_id = "anthropic.claude-3-5-haiku-20241022-v1:0";
Mock::given(method("POST"))
.and(path(format!("/model/{model_id}/converse")))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"output": {"message": {"role": "assistant",
"content": [{"text": "hello"}]}},
"stopReason": "end_turn",
"usage": {"inputTokens": 9, "outputTokens": 4,
"cacheReadInputTokens": 2, "cacheWriteInputTokens": 1}
})))
.mount(&upstream)
.await;
let endpoint: Url = upstream.uri().parse().unwrap();
let proxy = start_proxy_with_state(
&upstream.uri(),
|c| c.bedrock_endpoint = Some(endpoint),
|s| s.with_bedrock_credentials(test_credentials()),
)
.await;
let resp = post_json(
format!("{}/model/{model_id}/converse", proxy.url()),
&json!({
"messages": [{"role": "user", "content": [{"text": "hello"}]}]
}),
)
.await;
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap();
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(stats["session_by_provider"]["bedrock"]["requests"], 1);
assert_eq!(stats["tokens"]["input"], 9);
assert_eq!(stats["tokens"]["output"], 4);
assert_eq!(stats["tokens"]["cache_read"], 2);
assert_eq!(stats["tokens"]["cache_write"], 1);
// Bedrock model ids price via the vendored table (cache reads
// discounted vs list input price).
assert!(stats["session"]["cache_savings_usd"].as_f64().unwrap() > 0.0);
assert_eq!(stats["lifetime_by_model"][model_id]["requests"], 1);
}
#[tokio::test]
async fn bedrock_invoke_sync_records_snake_case_usage() {
let upstream = MockServer::start().await;
let model_id = "anthropic.claude-3-5-haiku-20241022-v1:0";
Mock::given(method("POST"))
.and(path(format!("/model/{model_id}/invoke")))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"id": "msg_1", "type": "message", "role": "assistant",
"model": "claude-3-5-haiku-20241022",
"content": [{"type": "text", "text": "ok"}],
"usage": {"input_tokens": 12, "output_tokens": 4}
})))
.mount(&upstream)
.await;
let endpoint: Url = upstream.uri().parse().unwrap();
let proxy = start_proxy_with_state(
&upstream.uri(),
|c| c.bedrock_endpoint = Some(endpoint),
|s| s.with_bedrock_credentials(test_credentials()),
)
.await;
let resp = post_json(
format!("{}/model/{model_id}/invoke", proxy.url()),
&json!({
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap();
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(stats["tokens"]["input"], 12);
assert_eq!(stats["tokens"]["output"], 4);
assert_eq!(stats["session_by_provider"]["bedrock"]["requests"], 1);
// The request-side model id (with region/revision) wins over the
// response echo's bare id.
assert_eq!(stats["lifetime_by_model"][model_id]["requests"], 1);
}
/// The passthrough lane nothing else parses: binary EventStream
/// (`Accept: application/vnd.amazon.eventstream`), with InvokeModel's
/// base64-wrapped Anthropic events. Usage must come out of the tee's
/// telemetry parser while the client receives byte-equal frames.
#[tokio::test]
async fn bedrock_eventstream_passthrough_records_usage() {
use base64::Engine as _;
let b64 = |v: &Value| base64::engine::general_purpose::STANDARD.encode(v.to_string());
let frame = |inner: &Value| event_frame("chunk", &json!({"bytes": b64(inner)}));
let mut body_bytes: Vec<u8> = Vec::new();
for inner in [
json!({"type": "message_start",
"message": {"id": "msg_1", "usage": {"input_tokens": 21, "output_tokens": 1,
"cache_read_input_tokens": 7}}}),
json!({"type": "content_block_delta", "index": 0,
"delta": {"type": "text_delta", "text": "ok"}}),
json!({"type": "message_delta", "delta": {"stop_reason": "end_turn"},
"usage": {"output_tokens": 9}}),
json!({"type": "message_stop"}),
] {
body_bytes.extend_from_slice(&frame(&inner));
}
let upstream = MockServer::start().await;
let model_id = "anthropic.claude-3-5-haiku-20241022-v1:0";
Mock::given(method("POST"))
.and(path(format!(
"/model/{model_id}/invoke-with-response-stream"
)))
.respond_with(
ResponseTemplate::new(200)
.insert_header("content-type", "application/vnd.amazon.eventstream")
// Cloned: the assertion below compares the client's
// bytes against these exact frames.
.set_body_raw(body_bytes.clone(), "application/vnd.amazon.eventstream"),
)
.mount(&upstream)
.await;
let endpoint: Url = upstream.uri().parse().unwrap();
let proxy = start_proxy_with_state(
&upstream.uri(),
|c| c.bedrock_endpoint = Some(endpoint),
|s| s.with_bedrock_credentials(test_credentials()),
)
.await;
let resp = reqwest::Client::new()
.post(format!(
"{}/model/{model_id}/invoke-with-response-stream",
proxy.url()
))
.header("content-type", "application/json")
// EventStream passthrough mode — the client wants raw frames.
.header("accept", "application/vnd.amazon.eventstream")
.json(&json!({
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hello"}]
}))
.send()
.await
.unwrap();
assert_eq!(resp.status(), 200);
let echoed = resp.bytes().await.unwrap();
// The whole claim of this lane is that telemetry rides alongside
// the bytes without touching them. Assert that literally: the
// client's stream must be byte-identical to what the upstream
// sent, tee or no tee. `!is_empty()` would pass a mangled body.
assert_eq!(
echoed.as_ref(),
body_bytes.as_slice(),
"EventStream passthrough must be byte-identical through the tee"
);
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(
stats["tokens"]["input"], 21,
"from base64-wrapped message_start"
);
assert_eq!(
stats["tokens"]["output"], 9,
"monotone max from message_delta"
);
assert_eq!(stats["tokens"]["cache_read"], 7);
assert_eq!(stats["requests"]["cached"], 1);
}
/// Converse-stream in SSE-translation mode: usage arrives ONLY in the
/// camelCase `metadata` frame, which carries no Anthropic `type` and
/// is dropped by the Anthropic state machine — the fallback scan must
/// pick it up.
#[tokio::test]
async fn bedrock_converse_stream_sse_records_camel_metadata_usage() {
let mut body_bytes: Vec<u8> = Vec::new();
for (et, payload) in [
("messageStart", json!({"role": "assistant"})),
(
"contentBlockDelta",
json!({"contentBlockIndex": 0, "delta": {"text": "ok"}}),
),
("messageStop", json!({"stopReason": "end_turn"})),
(
"metadata",
json!({"usage": {"inputTokens": 15, "outputTokens": 6,
"cacheWriteInputTokens": 11},
"metrics": {"latencyMs": 250}}),
),
] {
body_bytes.extend_from_slice(&event_frame(et, &payload));
}
let upstream = MockServer::start().await;
let model_id = "anthropic.claude-3-5-haiku-20241022-v1:0";
Mock::given(method("POST"))
.and(path(format!("/model/{model_id}/converse-stream")))
.respond_with(
ResponseTemplate::new(200)
.insert_header("content-type", "application/vnd.amazon.eventstream")
.set_body_raw(body_bytes, "application/vnd.amazon.eventstream"),
)
.mount(&upstream)
.await;
let endpoint: Url = upstream.uri().parse().unwrap();
let proxy = start_proxy_with_state(
&upstream.uri(),
|c| c.bedrock_endpoint = Some(endpoint),
|s| s.with_bedrock_credentials(test_credentials()),
)
.await;
let resp = reqwest::Client::new()
.post(format!("{}/model/{model_id}/converse-stream", proxy.url()))
.header("content-type", "application/json")
.header("accept", "text/event-stream") // SSE translation mode
.json(&json!({
"messages": [{"role": "user", "content": [{"text": "hello"}]}]
}))
.send()
.await
.unwrap();
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap();
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(
stats["tokens"]["input"], 15,
"camelCase metadata usage captured"
);
assert_eq!(stats["tokens"]["output"], 6);
assert_eq!(stats["tokens"]["cache_write"], 11);
}
#[tokio::test]
async fn vertex_raw_predict_records_usage() {
let upstream = MockServer::start().await;
Mock::given(method("POST"))
.and(path_regex(
r"^/v1beta1/projects/[^/]+/locations/[^/]+/publishers/anthropic/models/.+:rawPredict$",
))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"id": "msg_1", "type": "message", "role": "assistant",
"model": "claude-sonnet-4-5",
"content": [{"type": "text", "text": "ok"}],
"usage": {"input_tokens": 33, "output_tokens": 8,
"cache_read_input_tokens": 5}
})))
.mount(&upstream)
.await;
let proxy = start_proxy_with_state(
&upstream.uri(),
|_| {},
|s| install_static_token_source(s, "ya29.stats-test-bearer"),
)
.await;
let resp = reqwest::Client::new()
.post(format!(
"{}/v1beta1/projects/p1/locations/us-central1/publishers/anthropic/models/claude-sonnet-4-5@20250929:rawPredict",
proxy.url()
))
.header("content-type", "application/json")
.json(&json!({
"anthropic_version": "vertex-2023-10-16",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hello"}]
}))
.send()
.await
.unwrap();
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap();
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(stats["session_by_provider"]["vertex"]["requests"], 1);
assert_eq!(stats["tokens"]["input"], 33);
assert_eq!(stats["tokens"]["output"], 8);
assert_eq!(stats["tokens"]["cache_read"], 5);
}
/// A proxy-side rejection (here: no AWS credentials configured) is an
/// outcome too — it must show in /stats as a failure, not vanish. An
/// operator-side credentials outage reading as "zero traffic" would
/// hide exactly the incident this dashboard exists to surface.
#[tokio::test]
async fn bedrock_proxy_side_rejection_records_failure() {
let upstream = MockServer::start().await;
let model_id = "anthropic.claude-3-5-haiku-20241022-v1:0";
let endpoint: Url = upstream.uri().parse().unwrap();
// No .with_bedrock_credentials(...) → handler must 5xx before
// any upstream attempt.
let proxy = start_proxy_with(&upstream.uri(), |c| c.bedrock_endpoint = Some(endpoint)).await;
let resp = post_json(
format!("{}/model/{model_id}/invoke", proxy.url()),
&json!({
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 500);
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(stats["requests"]["failed"], 1);
assert_eq!(stats["tokens"]["input"], 0);
assert_eq!(stats["session"]["savings_usd"], 0.0);
assert_eq!(stats["session_by_provider"]["bedrock"]["failed"], 1);
}
/// Persistence through the real config surface: proxy A (started with
/// a stats path) records and flushes; proxy B on the same path serves
/// the lifetime numbers proxy A earned.
#[tokio::test]
async fn stats_path_survives_across_proxy_instances() {
let dir = std::env::temp_dir().join(format!("stats-restart-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
let stats_path = dir.join("native_stats.json");
let upstream = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/v1/messages"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"id": "msg_1", "type": "message",
"model": "claude-sonnet-4-5-20250929",
"content": [{"type": "text", "text": "hi"}],
"usage": {"input_tokens": 60, "output_tokens": 6}
})))
.mount(&upstream)
.await;
// Proxy A: record one request, then flush via the ledger handle
// (the background flusher + shutdown flush live in main.rs, which
// this in-process harness deliberately doesn't run).
let ledger_slot: std::sync::Arc<
std::sync::Mutex<Option<std::sync::Arc<headroom_proxy::observability::ledger::Ledger>>>,
> = Default::default();
let slot = ledger_slot.clone();
let sp = stats_path.clone();
let proxy_a = start_proxy_with_state(
&upstream.uri(),
move |c| c.stats_path = Some(sp),
move |s| {
*slot.lock().unwrap() = Some(s.stats.clone());
s
},
)
.await;
let resp = post_json(
format!("{}/v1/messages", proxy_a.url()),
&json!({
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 16,
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap();
wait_for_stats(&proxy_a.url(), |v| v["requests"]["total"] == 1).await;
let ledger = ledger_slot.lock().unwrap().take().unwrap();
ledger.flush().await;
proxy_a.shutdown().await;
assert!(stats_path.exists(), "flush persisted the ledger");
// Proxy B on the same path: lifetime carries over, session fresh.
let sp = stats_path.clone();
let proxy_b = start_proxy_with(&upstream.uri(), move |c| c.stats_path = Some(sp)).await;
let stats: Value = reqwest::Client::new()
.get(format!("{}/stats", proxy_b.url()))
.send()
.await
.unwrap()
.json()
.await
.unwrap();
assert_eq!(
stats["lifetime"]["requests"], 1,
"lifetime survived restart"
);
assert_eq!(stats["lifetime"]["input_tokens"], 60);
assert_eq!(stats["session"]["requests"], 0, "session resets per boot");
let _ = std::fs::remove_dir_all(&dir);
}
/// A 200 OK SSE stream that fails IN-BAND (`{"type":"error"}` mid-
/// stream — e.g. Anthropic overloading during generation) is not a
/// billable success. The state machine lands in `Errored`; the
/// ledger must count the request as failed and accrue nothing.
#[tokio::test]
async fn in_stream_error_event_records_failure() {
let sse_body = concat!(
"event: message_start\n",
"data: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_1\",\"usage\":",
"{\"input_tokens\":50,\"output_tokens\":1}}}\n\n",
"event: error\n",
"data: {\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",",
"\"message\":\"Overloaded\"}}\n\n",
);
let upstream = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/v1/messages"))
.respond_with(
ResponseTemplate::new(200)
.insert_header("content-type", "text/event-stream")
.set_body_raw(sse_body.as_bytes().to_vec(), "text/event-stream"),
)
.mount(&upstream)
.await;
let proxy = start_proxy_with(&upstream.uri(), |_| {}).await;
let resp = post_json(
format!("{}/v1/messages", proxy.url()),
&json!({
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 32,
"stream": true,
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 200, "the HTTP status was a success");
let _ = resp.bytes().await.unwrap();
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
assert_eq!(
stats["requests"]["failed"], 1,
"in-band stream error must count as a failed request"
);
assert_eq!(
stats["tokens"]["input"], 0,
"failed requests accrue nothing"
);
assert_eq!(stats["session"]["input_cost_usd"], 0.0);
}
/// A hostile (or buggy) upstream reporting absurd token counts must
/// not poison the lifetime aggregates: the ledger clamps every
/// per-event token field to its 50M ceiling before pricing.
#[tokio::test]
async fn hostile_usage_counts_are_clamped_before_recording() {
let upstream = MockServer::start().await;
Mock::given(method("POST"))
.and(path("/v1/messages"))
.respond_with(ResponseTemplate::new(200).set_body_json(json!({
"id": "msg_1",
"type": "message",
"model": "claude-sonnet-4-5-20250929",
"content": [{"type": "text", "text": "hi"}],
"usage": {
"input_tokens": u64::MAX,
"output_tokens": 9_000_000_000_000u64,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0
}
})))
.mount(&upstream)
.await;
let proxy = start_proxy_with(&upstream.uri(), |_| {}).await;
let resp = post_json(
format!("{}/v1/messages", proxy.url()),
&json!({
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 32,
"messages": [{"role": "user", "content": "hello"}]
}),
)
.await;
assert_eq!(resp.status(), 200);
let _ = resp.bytes().await.unwrap();
let stats = wait_for_stats(&proxy.url(), |v| v["requests"]["total"] == 1).await;
const CEILING: u64 = 50_000_000;
assert_eq!(stats["tokens"]["input"], CEILING, "input clamped");
assert_eq!(stats["tokens"]["output"], CEILING, "output clamped");
let cost = stats["session"]["input_cost_usd"].as_f64().unwrap();
assert!(
cost.is_finite() && cost < 1_000.0,
"clamped pricing stays sane: {cost}"
);
}
+5 -2
View File
@@ -6,7 +6,8 @@
* client sends AND exactly what happens to it on arrival. "Trust us" is not a
* privacy policy.
*
* Deployed at otlp.headroomlabs.ai. Three jobs:
* Deployed at headroom-beacon.headroom-beacon.workers.dev (otlp.headroomlabs.ai
* is planned but not yet routed; see wrangler.toml). Three jobs:
*
* 1. Allowlist. Drop every field not on ALLOWED_KEYS before anything is
* written. This is the only privacy control that works retroactively —
@@ -25,7 +26,9 @@
*
* What this deliberately does NOT do: log, store, or forward the source IP.
* Cloudflare offers it as cf-connecting-ip; it is the one field that would
* deanonymise install_id, so it is never read.
* deanonymise install_id, so it is never read. Cloudflare's own per-request
* invocation logs would record it regardless of this code, which is why
* wrangler.toml turns them off (observability.logs.invocation_logs = false).
*/
// Mostly mirrors the payload built by _Session.payload(); an extension may
+8
View File
@@ -53,6 +53,14 @@ subrequests = 100000
[observability]
enabled = true
# Invocation logs record every request's headers and Cloudflare metadata,
# which includes the sender's IP address (cf-connecting-ip, x-real-ip) and
# their city, postal code and coordinates. worker.js never reads these, but
# with invocation logs on, Cloudflare writes them to Workers Logs for every
# beacon POST anyway. Keep them off; errors and console.log still appear.
[observability.logs]
invocation_logs = false
# Rate limiting is configured in the Cloudflare dashboard, not here — this
# endpoint is unauthenticated by design (anonymity is the product), so it is
# the only thing between the Worker and a bored stranger:
+13 -1
View File
@@ -1,4 +1,5 @@
import { RootProvider } from 'fumadocs-ui/provider/next';
import { Banner } from 'fumadocs-ui/components/banner';
import './global.css';
import { Inter } from 'next/font/google';
import type { Metadata } from 'next';
@@ -48,7 +49,18 @@ export default function Layout({ children }: LayoutProps<'/'>) {
return (
<html lang="en" className={inter.className} suppressHydrationWarning>
<body className="flex flex-col min-h-screen">
<RootProvider>{children}</RootProvider>
<RootProvider>
{/* Dismissible; Fumadocs remembers the dismissal per id in localStorage. */}
<Banner id="teams-perk-2026">
<a
href="https://headroom-perks.vercel.app/?source=github&utm_source=docs&utm_medium=banner"
className="font-medium underline-offset-4 hover:underline"
>
Headroom for Teams: 3 months free with a 12-month plan →
</a>
</Banner>
{children}
</RootProvider>
</body>
</html>
);
+237 -221
View File
@@ -5,113 +5,113 @@
"": {
"name": "headroom-docs",
"dependencies": {
"@radix-ui/react-slot": "1.3.0",
"@radix-ui/react-slot": "1.3.3",
"class-variance-authority": "0.7.1",
"clsx": "2.1.1",
"dotted-map": "^3.1.0",
"fumadocs-core": "16.11.5",
"fumadocs-mdx": "15.2.0",
"fumadocs-twoslash": "^3.3.0",
"fumadocs-typescript": "^5.3.0",
"fumadocs-ui": "16.11.5",
"lucide-react": "^1.7.0",
"next": "16.3.0",
"react": "^19.2.7",
"react-dom": "^19.2.7",
"recharts": "^3.9.2",
"tailwind-merge": "^3.5.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",
"lucide-react": "^1.48.0",
"next": "^16.3.8",
"react": "^19.3.0",
"react-dom": "^19.3.0",
"recharts": "^3.10.1",
"tailwind-merge": "^3.7.0",
},
"devDependencies": {
"@ai-sdk/openai": "^3.0.51",
"@anthropic-ai/sdk": "^0.111.0",
"@tailwindcss/postcss": "^4.3.2",
"@ai-sdk/openai": "^4.0.79",
"@anthropic-ai/sdk": "^0.129.0",
"@tailwindcss/postcss": "^4.3.3",
"@types/mdx": "^2.0.14",
"@types/node": "^26.1.1",
"@types/react": "^19.2.17",
"@types/react-dom": "^19.2.3",
"ai": "7.0.59",
"openai": "^6.47.0",
"postcss": "^8.5.26",
"@types/node": "^26.6.3",
"@types/react": "^19.3.0",
"@types/react-dom": "^19.3.0",
"ai": "7.0.119",
"openai": "^7.23.0",
"postcss": "^8.5.28",
"tailwindcss": "^4.2.2",
"typescript": "^5.9.3",
"typescript": "^7.0.2",
},
},
},
"overrides": {
"postcss": "^8.5.26",
"postcss": "^8.5.28",
},
"packages": {
"@ai-sdk/gateway": ["@ai-sdk/gateway@4.0.47", "", { "dependencies": { "@ai-sdk/provider": "4.0.7", "@ai-sdk/provider-utils": "5.0.26", "@vercel/oidc": "3.2.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-BuWWlA8atWEnEJzN4eamCpGZWkoK9V3TCyNaMwgRIazhqkgWkA1Wp36si3j2JeVYzlvlEAOWrJ92dr92j/Vkqg=="],
"@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/openai": ["@ai-sdk/openai@3.0.51", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@ai-sdk/provider-utils": "4.0.23" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, ""],
"@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/provider": ["@ai-sdk/provider@3.0.8", "", { "dependencies": { "json-schema": "^0.4.0" } }, ""],
"@ai-sdk/provider": ["@ai-sdk/provider@4.0.23", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-TdEzgE1ndBGhDDwZcg/WZG3IeUj8Yz7/DkUG4ctMyK5HdNXTEKpjkCdwX8ayvkgluTv7yjnqCdOkB8/q1nfaNQ=="],
"@ai-sdk/provider-utils": ["@ai-sdk/provider-utils@4.0.23", "", { "dependencies": { "@ai-sdk/provider": "3.0.8", "@standard-schema/spec": "^1.1.0", "eventsource-parser": "^3.0.6" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, ""],
"@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=="],
"@alloc/quick-lru": ["@alloc/quick-lru@5.2.0", "", {}, ""],
"@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.111.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-1hUqKi+uJQoS5X90+InwHbFAXMvgq0DnsC5hVLEeSRaODiU5WvmqDAcVCmGS2wC0pN9Z8jtWCbWw7JLzeDdm/Q=="],
"@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=="],
"@babel/runtime": ["@babel/runtime@7.29.2", "", {}, ""],
"@base-ui/react": ["@base-ui/react@1.7.0", "", { "dependencies": { "@babel/runtime": "^7.29.2", "@base-ui/utils": "0.3.2", "@floating-ui/react-dom": "^2.1.9", "@floating-ui/utils": "^0.2.12", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "@date-fns/tz": "^1.2.0", "@types/react": "^17 || ^18 || ^19", "date-fns": "^4.0.0", "react": "^17 || ^18 || ^19", "react-dom": "^17 || ^18 || ^19" }, "optionalPeers": ["@date-fns/tz", "@types/react", "date-fns"] }, "sha512-j+8QjX44C32jrXD/qyEAGpFr70FRpGL2CY61mQd9nBPWN737CK0xxD1ceJ055rW4RtdvFDT1e7otzdlfxvsYug=="],
"@base-ui/react": ["@base-ui/react@1.8.0", "", { "dependencies": { "@babel/runtime": "^7.29.7", "@base-ui/utils": "0.4.0", "@floating-ui/react-dom": "^2.1.9", "@floating-ui/utils": "^0.2.12", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "@date-fns/tz": "^1.2.0", "@types/react": "^17 || ^18 || ^19", "date-fns": "^4.0.0", "react": "^17 || ^18 || ^19", "react-dom": "^17 || ^18 || ^19" }, "optionalPeers": ["@date-fns/tz", "@types/react", "date-fns"] }, "sha512-P0/1sxo6SBVZOklKMIedvTWqw2s2IQzi9x5bIVsXu980cuSOD4NeuRSs+/L7LZQfDkZP/uRZyGPyfFl/B1oH+Q=="],
"@base-ui/utils": ["@base-ui/utils@0.3.2", "", { "dependencies": { "@babel/runtime": "^7.29.2", "@floating-ui/utils": "^0.2.12", "reselect": "^5.2.0", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "@types/react": "^17 || ^18 || ^19", "react": "^17 || ^18 || ^19", "react-dom": "^17 || ^18 || ^19" }, "optionalPeers": ["@types/react"] }, "sha512-oWy1aq/I2GmYjpl4PhEAhzflF8VPGKgZeq0xAWTbfD5KBWyxcN0ZP2+WHSUm/5Z6lVMBDLReLcoXwSYoRc/zNQ=="],
"@base-ui/utils": ["@base-ui/utils@0.4.0", "", { "dependencies": { "@babel/runtime": "^7.29.7", "@floating-ui/utils": "^0.2.12", "reselect": "^5.2.0", "use-sync-external-store": "^1.6.0" }, "peerDependencies": { "@types/react": "^17 || ^18 || ^19", "react": "^17 || ^18 || ^19", "react-dom": "^17 || ^18 || ^19" }, "optionalPeers": ["@types/react"] }, "sha512-bO9fz25kKtPf+aZVyfQrC0PDmJdmVni31W2hCS5/Owb+inwdIL3XU26pCPRPlt4LSxZrBgLwubXQXQlKaFEZzw=="],
"@emnapi/runtime": ["@emnapi/runtime@1.11.3", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA=="],
"@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.28.1", "", { "os": "aix", "cpu": "ppc64" }, "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ=="],
"@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.28.2", "", { "os": "aix", "cpu": "ppc64" }, "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ=="],
"@esbuild/android-arm": ["@esbuild/android-arm@0.28.1", "", { "os": "android", "cpu": "arm" }, "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ=="],
"@esbuild/android-arm": ["@esbuild/android-arm@0.28.2", "", { "os": "android", "cpu": "arm" }, "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg=="],
"@esbuild/android-arm64": ["@esbuild/android-arm64@0.28.1", "", { "os": "android", "cpu": "arm64" }, "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg=="],
"@esbuild/android-arm64": ["@esbuild/android-arm64@0.28.2", "", { "os": "android", "cpu": "arm64" }, "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A=="],
"@esbuild/android-x64": ["@esbuild/android-x64@0.28.1", "", { "os": "android", "cpu": "x64" }, "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng=="],
"@esbuild/android-x64": ["@esbuild/android-x64@0.28.2", "", { "os": "android", "cpu": "x64" }, "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q=="],
"@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.28.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q=="],
"@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.28.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw=="],
"@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.28.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ=="],
"@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.28.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw=="],
"@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.28.1", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw=="],
"@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.28.2", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw=="],
"@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.28.1", "", { "os": "freebsd", "cpu": "x64" }, "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ=="],
"@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.28.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg=="],
"@esbuild/linux-arm": ["@esbuild/linux-arm@0.28.1", "", { "os": "linux", "cpu": "arm" }, "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ=="],
"@esbuild/linux-arm": ["@esbuild/linux-arm@0.28.2", "", { "os": "linux", "cpu": "arm" }, "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w=="],
"@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.28.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g=="],
"@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.28.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug=="],
"@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.28.1", "", { "os": "linux", "cpu": "ia32" }, "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w=="],
"@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.28.2", "", { "os": "linux", "cpu": "ia32" }, "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ=="],
"@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg=="],
"@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.28.2", "", { "os": "linux", "cpu": "none" }, "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ=="],
"@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ=="],
"@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.28.2", "", { "os": "linux", "cpu": "none" }, "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA=="],
"@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.28.1", "", { "os": "linux", "cpu": "ppc64" }, "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ=="],
"@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.28.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ=="],
"@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.28.1", "", { "os": "linux", "cpu": "none" }, "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ=="],
"@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.28.2", "", { "os": "linux", "cpu": "none" }, "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA=="],
"@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.28.1", "", { "os": "linux", "cpu": "s390x" }, "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag=="],
"@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.28.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg=="],
"@esbuild/linux-x64": ["@esbuild/linux-x64@0.28.1", "", { "os": "linux", "cpu": "x64" }, "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA=="],
"@esbuild/linux-x64": ["@esbuild/linux-x64@0.28.2", "", { "os": "linux", "cpu": "x64" }, "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ=="],
"@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.28.1", "", { "os": "none", "cpu": "arm64" }, "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw=="],
"@esbuild/netbsd-arm64": ["@esbuild/netbsd-arm64@0.28.2", "", { "os": "none", "cpu": "arm64" }, "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw=="],
"@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.28.1", "", { "os": "none", "cpu": "x64" }, "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg=="],
"@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.28.2", "", { "os": "none", "cpu": "x64" }, "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw=="],
"@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.28.1", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q=="],
"@esbuild/openbsd-arm64": ["@esbuild/openbsd-arm64@0.28.2", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ=="],
"@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.28.1", "", { "os": "openbsd", "cpu": "x64" }, "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw=="],
"@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.28.2", "", { "os": "openbsd", "cpu": "x64" }, "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw=="],
"@esbuild/openharmony-arm64": ["@esbuild/openharmony-arm64@0.28.1", "", { "os": "none", "cpu": "arm64" }, "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg=="],
"@esbuild/openharmony-arm64": ["@esbuild/openharmony-arm64@0.28.2", "", { "os": "none", "cpu": "arm64" }, "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q=="],
"@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.28.1", "", { "os": "sunos", "cpu": "x64" }, "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ=="],
"@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.28.2", "", { "os": "sunos", "cpu": "x64" }, "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g=="],
"@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.28.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA=="],
"@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.28.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ=="],
"@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.28.1", "", { "os": "win32", "cpu": "ia32" }, "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg=="],
"@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.28.2", "", { "os": "win32", "cpu": "ia32" }, "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA=="],
"@esbuild/win32-x64": ["@esbuild/win32-x64@0.28.1", "", { "os": "win32", "cpu": "x64" }, "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A=="],
"@esbuild/win32-x64": ["@esbuild/win32-x64@0.28.2", "", { "os": "win32", "cpu": "x64" }, "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g=="],
"@floating-ui/core": ["@floating-ui/core@1.8.0", "", { "dependencies": { "@floating-ui/utils": "^0.2.12" } }, "sha512-0CIZ5itps/8x7BG8dEIhs53BvCUH2PCoogtakwRTut+Arm58sJooJ0AuZhLw2HJYIR5cMLNPBSS728sPho2khQ=="],
@@ -123,61 +123,63 @@
"@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.1", "", { "peerDependencies": { "tailwindcss": "^4.0.0" }, "optionalPeers": ["tailwindcss"] }, "sha512-BnPe52UxSaG8yKlHMKBxXw8h6GpK5qO55ci6+Qd5JnquTvIw6SpfbC1P+qAi82PuPWv1KZAWY8bxRk4+x9ctXw=="],
"@fumadocs/tailwind": ["@fumadocs/tailwind@0.1.2", "", { "peerDependencies": { "tailwindcss": "^4.0.0" }, "optionalPeers": ["tailwindcss"] }, "sha512-VppeXgIRXjZMgpf2qijj1hcfxyeYl1s0ok8k6N3jyjiX64M7sDwnt2zGPd6dbfDybgbBvDw6C6J1e42gB5NzsA=="],
"@fumari/image-size": ["@fumari/image-size@0.1.1", "", {}, "sha512-iaiV2wyzJ4mW358NX4CX3yGit+WjKYzpaQ+rldK9BjL/5jFpeV6ruWnZVq7MEyMn3Gd0DLi8g/79NZAAQaGscw=="],
"@img/colour": ["@img/colour@1.1.0", "", {}, ""],
"@img/sharp-darwin-arm64": ["@img/sharp-darwin-arm64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-arm64": "1.3.2" }, "os": "darwin", "cpu": "arm64" }, "sha512-RMnFX7YQsMoh7lWfcM4NEHHymBX/rLuKNPVM84XE9ONPcaSCDgE7CHIHpSgPcO2xcRthgBy1HfNO319mwhIAkg=="],
"@img/sharp-darwin-arm64": ["@img/sharp-darwin-arm64@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-arm64": "1.3.4" }, "os": "darwin", "cpu": "arm64" }, "sha512-QRUlFQ0WxvdWyqqG/WtI3iupfD5rBzmCHXSdPsY91sAtVtTo7Q4cb6zOccZ3gqEqkr0f1As1ehLqmEpDsRf+lg=="],
"@img/sharp-darwin-x64": ["@img/sharp-darwin-x64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-x64": "1.3.2" }, "os": "darwin", "cpu": "x64" }, "sha512-Xo+5uFBtLN0BKqieTxiFzFPQAUlBbbH5iBKyRX/z1JrbnYsHTfKJnUfL8+p2TPXr1pXqao4eeL4Rl144uDpK9w=="],
"@img/sharp-darwin-x64": ["@img/sharp-darwin-x64@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-darwin-x64": "1.3.4" }, "os": "darwin", "cpu": "x64" }, "sha512-+BR255RhDlpygUpOc/Jdt1nT6DQ3XG/ERo5wbcdOf5Q320dKtPCKPLR1LJs9VGXRaMa8l1uUa0tkCNOXiAxZUw=="],
"@img/sharp-freebsd-wasm32": ["@img/sharp-freebsd-wasm32@0.35.3", "", { "dependencies": { "@img/sharp-wasm32": "0.35.3" }, "os": "freebsd" }, "sha512-lUxcqWIj2wMQ9BrwNjngcr1gWUr5xgaGThBRqPPalIC2n67Cqj1uPh8NnA/ZhAg8hUbKl+kVHKwgUIwe6ZYPrg=="],
"@img/sharp-freebsd-wasm32": ["@img/sharp-freebsd-wasm32@0.35.5", "", { "dependencies": { "@img/sharp-wasm32": "0.35.5" }, "os": "freebsd" }, "sha512-Y/z91nEZ4uIBX5X3nfTovjU9lHNKFYbL2lpHCLVNmXQK03VIZvXBBt0KxbPGp2SdGSF+2mQU4e+hQaWOt86iAw=="],
"@img/sharp-libvips-darwin-arm64": ["@img/sharp-libvips-darwin-arm64@1.3.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-9J6ypZFpQBj4YnePGoq/S38w6nz+vqg5WZLrLGY4YuSemdMq47GMLBPO42MzwdGwpg/agZ7xzZcFHa48xlywfg=="],
"@img/sharp-libvips-darwin-arm64": ["@img/sharp-libvips-darwin-arm64@1.3.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-5R89nBYiRdUlSWJxPhO+GVtaXzXSxKnRu/xqMn3KTA3L9EB9Oy/P+Nn2f2vlhPuUdy/Zusb2DarbyTpGCfEDuw=="],
"@img/sharp-libvips-darwin-x64": ["@img/sharp-libvips-darwin-x64@1.3.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-m2pW1n6cns9VaubNwsZ+c3CRYjxNQWgJ5gPlnL1nbBcpkBvFm6SCFN5o0psFHI8w9n11NKhFkeEDns98tiqbEw=="],
"@img/sharp-libvips-darwin-x64": ["@img/sharp-libvips-darwin-x64@1.3.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-iR2OKH80yi0U+dUplyh3/xdpFvps6YkCwsXenIJxqxR1v9o+xtKTGbS9H7cps+2Vxjc8B1j96p75NmTGjIhtpQ=="],
"@img/sharp-libvips-linux-arm": ["@img/sharp-libvips-linux-arm@1.3.2", "", { "os": "linux", "cpu": "arm" }, "sha512-1eMLzy92I4J6rmi4mAT8yC3HxOtniyGELlzGbNMLLeqe052ahFQ0h6LFq+lh5DsDIdYViIDst08abvSbcEdLXQ=="],
"@img/sharp-libvips-linux-arm": ["@img/sharp-libvips-linux-arm@1.3.4", "", { "os": "linux", "cpu": "arm" }, "sha512-LmRtTsOHuvM2+wlO2Db37dx5MiZhB0FvSunciw48YjdOkZz9KAiRbm8ujeMOA1INqmei5NapFxYEK1D1ZSidmw=="],
"@img/sharp-libvips-linux-arm64": ["@img/sharp-libvips-linux-arm64@1.3.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-dqVSFynCox4C/J8kT16V7SIFAns0IjgLwkvYT7p8LQVmJ5OS5b6tI9IGflxTeuBS//zXeFIUbwt5dwxyZ17cnA=="],
"@img/sharp-libvips-linux-arm64": ["@img/sharp-libvips-linux-arm64@1.3.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-Y3dgX/6lE2QhQb+Gxy0WZxfg9MEm/JBjamZpS2IklP7xIQoKN4hzAm7KcMVGtaVDt3neE9OKBC7vAfonA/Lr1A=="],
"@img/sharp-libvips-linux-ppc64": ["@img/sharp-libvips-linux-ppc64@1.3.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-3z0NHDxD6n5I9gc05U1eW1AyRm+Gznzq3naMrthPNqE6oYykcogW0l/jfpJdjYnuNl8R7yI9pNbE1XiUeyq0Aw=="],
"@img/sharp-libvips-linux-ppc64": ["@img/sharp-libvips-linux-ppc64@1.3.4", "", { "os": "linux", "cpu": "ppc64" }, "sha512-Le6boB8Tai0Nis+gIxIpKx68UDVVIqdR8Tin5Yf1z2LJJQLDJvCDRqRu+jC2qCoD+eIomonmOwB4smBRxfVpYQ=="],
"@img/sharp-libvips-linux-riscv64": ["@img/sharp-libvips-linux-riscv64@1.3.2", "", { "os": "linux", "cpu": "none" }, "sha512-bsb4rI+NldGOsXuej2r8OdSS8+zXDVaCWxyWrcv6kneTOlgAHtZABRzBBCwdsPiD90J4myNJuHpg6kA20ImW/w=="],
"@img/sharp-libvips-linux-riscv64": ["@img/sharp-libvips-linux-riscv64@1.3.4", "", { "os": "linux", "cpu": "none" }, "sha512-aHkkIEHPRdQEegJN20MLmGtxYD9R2wQr3Cwpddnu5+YKMt6Uzax7S9h5gpZTo8wyrGuZSlfQ63OevL5mTyOC7Q=="],
"@img/sharp-libvips-linux-s390x": ["@img/sharp-libvips-linux-s390x@1.3.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-/ABshyj8gCpyIrNXnHn4LorDJ0HHm1VhXPBlxZ8zAtfVPAaSafXPGn+sUSIRiwaSBy0mmFjSjiXI5mkcwdChKQ=="],
"@img/sharp-libvips-linux-s390x": ["@img/sharp-libvips-linux-s390x@1.3.4", "", { "os": "linux", "cpu": "s390x" }, "sha512-ra/mB6MikESDUO7Yg+Mi95bFBb9GsObURuhnOv3OqknjGe9sZrG8tCe9q0xSIGrtLgvgw0gKnFWcK4blSgQOuQ=="],
"@img/sharp-libvips-linux-x64": ["@img/sharp-libvips-linux-x64@1.3.2", "", { "os": "linux", "cpu": "x64" }, "sha512-ITPEtgffGJ0S6G9dRyw/366tJQqFRcHWPHhC+Stpg3Z8AEMrDrTr2lhdz4f/Y/HMbRh//7Z5mBzEpVdi62Oc3w=="],
"@img/sharp-libvips-linux-x64": ["@img/sharp-libvips-linux-x64@1.3.4", "", { "os": "linux", "cpu": "x64" }, "sha512-GJ//SSXbnwSDes02umB3nDJLFcQzw8a18V8fyhqr6tV515tOEMdImjjxj1AoafMRz56F3PHgftnj1QEKSU1zkw=="],
"@img/sharp-libvips-linuxmusl-arm64": ["@img/sharp-libvips-linuxmusl-arm64@1.3.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-zE9EdiUzUmg5mDT5a1rk5fYJ6GWPloTwWBYDS14naqHsL+EaMpDj1AWnpLgh3u0YCORv2Tt50wrcrpYqkP97Kw=="],
"@img/sharp-libvips-linuxmusl-arm64": ["@img/sharp-libvips-linuxmusl-arm64@1.3.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-hvulFwtjUcagsis6BBxHwGFwWoNZjgYmULGVrZcyfNbjA8hKILbRxGg15/7w5HDyXHXUos/j6baAWqnCyQ2DWA=="],
"@img/sharp-libvips-linuxmusl-x64": ["@img/sharp-libvips-linuxmusl-x64@1.3.2", "", { "os": "linux", "cpu": "x64" }, "sha512-m0lrLiUt+lBYnCFr8qV/65yMR4E/c7/wf78I5eKTdkEakFAlZ9QlzEM3QIhhAwVeUhLAHLcCq7a7Vszq/oFNZQ=="],
"@img/sharp-libvips-linuxmusl-x64": ["@img/sharp-libvips-linuxmusl-x64@1.3.4", "", { "os": "linux", "cpu": "x64" }, "sha512-6zXKeE/p39I1AmA3cJG35eyBGNqNddLnUXjhwBnsGjFPWqf5VKkDBEqaEkPDoTEtkxwi2vv8Tcr2mDyP4So7Fg=="],
"@img/sharp-linux-arm": ["@img/sharp-linux-arm@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-arm": "1.3.2" }, "os": "linux", "cpu": "arm" }, "sha512-affVWCTLooy8TSxbDx2qkzuDeaWLNVBA+P//FNBirHsXpP2fuBhk5AuboYUnrDnzoXes8GFjpTx0SBFOCRg+FA=="],
"@img/sharp-linux-arm": ["@img/sharp-linux-arm@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-linux-arm": "1.3.4" }, "os": "linux", "cpu": "arm" }, "sha512-LEaXK2WdXVK5ykcw0buWyPMsmLLL2vpHLD6yrNSW+JGEL3BZPA4tpKN6iaMc4AxTTAoaX/sU1rOL51lcIz48ZQ=="],
"@img/sharp-linux-arm64": ["@img/sharp-linux-arm64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-arm64": "1.3.2" }, "os": "linux", "cpu": "arm64" }, "sha512-QgKDspHPnrU+GQ55XPhGwyhC8acLVOOSyAvo1oVfFmrIXLkDNmGWzAfDZ4xK8oSA1qBQrALcHX0G5UZni/SuFQ=="],
"@img/sharp-linux-arm64": ["@img/sharp-linux-arm64@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-linux-arm64": "1.3.4" }, "os": "linux", "cpu": "arm64" }, "sha512-LYVx5JTsOM2CBzmxreh+nl64/3H6Xb09iSLknqH47z2T2DFFxDeFLP5y4dJwe6H7uGQlHPyEEtIqyo3DYsRwdQ=="],
"@img/sharp-linux-ppc64": ["@img/sharp-linux-ppc64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-ppc64": "1.3.2" }, "os": "linux", "cpu": "ppc64" }, "sha512-sMd8rDxmpLOwv/7N44klFjOD5DUO7FLdjiXDI0hoxYaf7Ar262dQIEkosE98bps+5HPLtp/EvNqeqQtOycP/IA=="],
"@img/sharp-linux-ppc64": ["@img/sharp-linux-ppc64@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-linux-ppc64": "1.3.4" }, "os": "linux", "cpu": "ppc64" }, "sha512-QVxAAq8evVRI9ia2vqgwrmWucn5Dfv+JdWzj75pD8omHLPSP7f8p20O8jxzjCcuCEQEOtYOZUmX1hkiZ0kdevA=="],
"@img/sharp-linux-riscv64": ["@img/sharp-linux-riscv64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-riscv64": "1.3.2" }, "os": "linux", "cpu": "none" }, "sha512-0Eob78yjlYPfL5vMNWAW55l3R9Y6BQS/gOfe0ZcP9mEz9ohhKSt4im1hayiknXgf8AWrFqMvJcKIdmLmEe7yeQ=="],
"@img/sharp-linux-riscv64": ["@img/sharp-linux-riscv64@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-linux-riscv64": "1.3.4" }, "os": "linux", "cpu": "none" }, "sha512-LtdreXguaavKODPIfzJ4kffx7UNt1omwtK0rch4EBbbSTXPnxWmYSayXdLJw0fJzQ97kHt1gL/yh4tvU+nCyRQ=="],
"@img/sharp-linux-s390x": ["@img/sharp-linux-s390x@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-s390x": "1.3.2" }, "os": "linux", "cpu": "s390x" }, "sha512-KgAxQ0DxpNOq1rG2t5cgTgShJFGSuU7XO45cqC+1NVOuZnP6tlgZRuSYOfNupGkHID0o3cJOsw4DVeJpMovcGw=="],
"@img/sharp-linux-s390x": ["@img/sharp-linux-s390x@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-linux-s390x": "1.3.4" }, "os": "linux", "cpu": "s390x" }, "sha512-UZasTOFiYzotTsGOCu42BfUzP6Tu6Do/947iRm1RsLKvlllxwGcn4RN27LibGWceix4Y+Pmw3jsnTcCQIgWjqA=="],
"@img/sharp-linux-x64": ["@img/sharp-linux-x64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linux-x64": "1.3.2" }, "os": "linux", "cpu": "x64" }, "sha512-8pqvxubL2PGdhlPy6GLqzDYMUjyRmKAwKHYKixpdJYBUK7PJ0C029XdsnpFIdgRZG68fZiGdHVWcKPvtiPB4cA=="],
"@img/sharp-linux-x64": ["@img/sharp-linux-x64@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-linux-x64": "1.3.4" }, "os": "linux", "cpu": "x64" }, "sha512-SxFtLTeJInhAA9Q836kux2vZNeOBQEx658qvbboZScr0wIARym3IcGmW7KpVD5sbVg0Ojy+udFQdayYIZyoNog=="],
"@img/sharp-linuxmusl-arm64": ["@img/sharp-linuxmusl-arm64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linuxmusl-arm64": "1.3.2" }, "os": "linux", "cpu": "arm64" }, "sha512-Vz0iQjzzcSX3HCbfwFfCSG/9SCIqyO0mH2sXyiHaAYfBk0cRsCWXRyQYX0ovCK/PAQBbTzQ0dsPQHh5MAFL59w=="],
"@img/sharp-linuxmusl-arm64": ["@img/sharp-linuxmusl-arm64@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-linuxmusl-arm64": "1.3.4" }, "os": "linux", "cpu": "arm64" }, "sha512-9HbMclmI1zlNkFRs3z9/eBtDjfD0sGlrX1z6b1qwmiFY5ElDLh4BC0LPBdVp7z1DXFiKlIcznf+ZlsuZzLxQqg=="],
"@img/sharp-linuxmusl-x64": ["@img/sharp-linuxmusl-x64@0.35.3", "", { "optionalDependencies": { "@img/sharp-libvips-linuxmusl-x64": "1.3.2" }, "os": "linux", "cpu": "x64" }, "sha512-6O1NPKcDVj9QEdg7Hx549EX8U0rp6yXQERqru6yRN7fGBn32UvIRJUlWnk+8xDCiG76hXVBbX82NZ/ZKr0euIg=="],
"@img/sharp-linuxmusl-x64": ["@img/sharp-linuxmusl-x64@0.35.5", "", { "optionalDependencies": { "@img/sharp-libvips-linuxmusl-x64": "1.3.4" }, "os": "linux", "cpu": "x64" }, "sha512-4KOphqB035HrVdqLZfCgMzzERrQkkzOwRhl4OAkRO1YCldbaFjySXMaK534Mo0V+LndnlJk+sbUyLeU0ULyD1A=="],
"@img/sharp-wasm32": ["@img/sharp-wasm32@0.35.3", "", { "dependencies": { "@emnapi/runtime": "^1.11.1" } }, "sha512-cZ0XkcYGpHZkqW6iCkqTcmUC0CD9DhD5d/qeZlZkfRBn6GnHniZXLUo5+9xw8Iv76YE6LQFN9YNBlKREcCG76w=="],
"@img/sharp-wasm32": ["@img/sharp-wasm32@0.35.5", "", { "dependencies": { "@emnapi/runtime": "^1.11.3" } }, "sha512-Ptsga1su4tQx+LLF1ECS9U6nz5kmrXKo6XVbtR48Ke3ZRxxgaWBu7IDtEe1quo8hiupwm6WFqxVlXaSf7IINGQ=="],
"@img/sharp-webcontainers-wasm32": ["@img/sharp-webcontainers-wasm32@0.35.3", "", { "dependencies": { "@img/sharp-wasm32": "0.35.3" }, "cpu": "none" }, "sha512-2rnq7bX3NzeR2T4YWgz8qiG4h3TSdMe+vN1iQXpJleSJ3SM5zQ8Fy2SyyXAWlbxpEZ2Y+Z4u1BePgJEYbSy80Q=="],
"@img/sharp-webcontainers-wasm32": ["@img/sharp-webcontainers-wasm32@0.35.5", "", { "dependencies": { "@img/sharp-wasm32": "0.35.5" }, "cpu": "none" }, "sha512-hfhF/FmoQyTUkA0bIKFOtw536BQSeBMe6BF6QyWlrPxT754+TFLaZ7sKKTfvvM0yJgKgaYTwnFCIZ/GuDw5SUA=="],
"@img/sharp-win32-arm64": ["@img/sharp-win32-arm64@0.35.3", "", { "os": "win32", "cpu": "arm64" }, "sha512-4bPwFdMbeC4JQ8L8LOyWp6nsHcboP5fxkp6iPOXz2Vg49R42TuMs2whkJ5OAP4/Ul035qOzy0AecOF9VOscn4w=="],
"@img/sharp-win32-arm64": ["@img/sharp-win32-arm64@0.35.5", "", { "os": "win32", "cpu": "arm64" }, "sha512-X4t7g+7ZA5DKblCBEXGjUqqemj4vczING/5viFwAL8h4N3qYeyjwdCvRLHi4EdOUI+2Z7UFlp1VM+p/AuEtm6Q=="],
"@img/sharp-win32-ia32": ["@img/sharp-win32-ia32@0.35.3", "", { "os": "win32", "cpu": "ia32" }, "sha512-r53mXsBN6lFUDiST764SvgwUdHAqM4rPAiDzAmf4fLoB6X/rkfyTrLCg6+g17wJJiCmB3JYgHuUldCWUIRFSXw=="],
"@img/sharp-win32-ia32": ["@img/sharp-win32-ia32@0.35.5", "", { "os": "win32", "cpu": "ia32" }, "sha512-5Zm82LoBc43nhwNybZlG7Y1KO//Zhsn306fQl29ZOuStHLGTo3BWL83q3cznX0poxSAMuYL1On/BHBxkBeKr6A=="],
"@img/sharp-win32-x64": ["@img/sharp-win32-x64@0.35.3", "", { "os": "win32", "cpu": "x64" }, "sha512-D4y1vNeZrIIJCN+uHaWVtH86B+aCrdMYYjicy9pXHvbGZeGYLLSd3wdVuC37FxVXlU1ARsk84eKWfWMXGYEqvA=="],
"@img/sharp-win32-x64": ["@img/sharp-win32-x64@0.35.5", "", { "os": "win32", "cpu": "x64" }, "sha512-x76eH0vEiHlcMQu8Y8IenntaACtddpT6W0wmXtWrnKcnKI7ME5DdgqhAD6SEWOEl1v2zDvkZDhFA9KnURwpfqg=="],
"@jridgewell/gen-mapping": ["@jridgewell/gen-mapping@0.3.13", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.0", "@jridgewell/trace-mapping": "^0.3.24" } }, ""],
@@ -185,31 +187,29 @@
"@jridgewell/resolve-uri": ["@jridgewell/resolve-uri@3.1.2", "", {}, ""],
"@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "", {}, ""],
"@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.6.0", "", {}, "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw=="],
"@jridgewell/trace-mapping": ["@jridgewell/trace-mapping@0.3.31", "", { "dependencies": { "@jridgewell/resolve-uri": "^3.1.0", "@jridgewell/sourcemap-codec": "^1.4.14" } }, ""],
"@mdx-js/mdx": ["@mdx-js/mdx@3.1.1", "", { "dependencies": { "@types/estree": "^1.0.0", "@types/estree-jsx": "^1.0.0", "@types/hast": "^3.0.0", "@types/mdx": "^2.0.0", "acorn": "^8.0.0", "collapse-white-space": "^2.0.0", "devlop": "^1.0.0", "estree-util-is-identifier-name": "^3.0.0", "estree-util-scope": "^1.0.0", "estree-walker": "^3.0.0", "hast-util-to-jsx-runtime": "^2.0.0", "markdown-extensions": "^2.0.0", "recma-build-jsx": "^1.0.0", "recma-jsx": "^1.0.0", "recma-stringify": "^1.0.0", "rehype-recma": "^1.0.0", "remark-mdx": "^3.0.0", "remark-parse": "^11.0.0", "remark-rehype": "^11.0.0", "source-map": "^0.7.0", "unified": "^11.0.0", "unist-util-position-from-estree": "^2.0.0", "unist-util-stringify-position": "^4.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0" } }, ""],
"@next/env": ["@next/env@16.3.0", "", {}, "sha512-o9r1S0BNiNreHP9Vs+Qnqd9kviDkJh8xIACY7UFZSmiGbbQRzPBBosvHzAU4TULHOIuOj/18RSsyz2qrREmIFw=="],
"@next/env": ["@next/env@16.4.0", "", {}, "sha512-pyLlT5oafGlX8X7xjgGNXz5dNIDSxREm+qD6i9VLSZiZFopA/XWl8NM/KPmLx/8EG/++c49iid3gNWSQW1+2dQ=="],
"@next/swc-darwin-arm64": ["@next/swc-darwin-arm64@16.3.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-55hpqq18bEVAlxedlTt3tFqZmKg2nUXT1kn1G/BGEy0R13h3LwtwHPVzzjG6P4LLeOHE32PFDQUVaJEWvBEZBw=="],
"@next/swc-darwin-arm64": ["@next/swc-darwin-arm64@16.4.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-yyZ+9MgViAKLLb5l1gPBGjRwnq3teNLb5Zx6JEw8LzNSTjlsnp+baUHFxTgl7PpjCmKf48VQfyipG1eBflb48Q=="],
"@next/swc-darwin-x64": ["@next/swc-darwin-x64@16.3.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-SOi96kSaF5T+0wW4koiM1bWzSPwjzTesC1p3df+FjdOi5LIQkBK/blxh7HdoKnNuI4PURF1OO7TZqtfnbWDSgw=="],
"@next/swc-darwin-x64": ["@next/swc-darwin-x64@16.4.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-RePEEejEj1Auf5s9qEcG0JbcDP3ceNUS/ofNX8AhxzgIjTVlZIHMatlp16YplcSMpsVo/ZMQHJTjbMYJznjGUg=="],
"@next/swc-linux-arm64-gnu": ["@next/swc-linux-arm64-gnu@16.3.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-P0gZAoPMF4dyTRzhmkV4PrqVzSOB6t4mC1oI3c4dqijJ+OVEVx5clIXAKR4/uQpsqw2KKM/0D5tVumcR2r5blg=="],
"@next/swc-linux-arm64-gnu": ["@next/swc-linux-arm64-gnu@16.4.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-HhsyCqd+NpmvDDVY/LqkAN24f+QVvXh3ie+PfcwKinWL2Mu826JymQxJXGjAIfmJ4VlHjp4Pe/nZtXtUoEMAqw=="],
"@next/swc-linux-arm64-musl": ["@next/swc-linux-arm64-musl@16.3.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-tXXGKJw0m37O0eKJARVTX/TheKPhz0QFVtVVZXmOig+9YKLQOSP6hvf2pxv5DO7CLEJyTHx3Pg043CDQkv1G4Q=="],
"@next/swc-linux-arm64-musl": ["@next/swc-linux-arm64-musl@16.4.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-sN9Pf+Zh+RpZAOmbR7d8KAA8T61CVhawtbEJ2Bk6QrRzx6Z/6haaF4UiwBzytM96GRRRWZh9/WALIEO3npMamA=="],
"@next/swc-linux-x64-gnu": ["@next/swc-linux-x64-gnu@16.3.0", "", { "os": "linux", "cpu": "x64" }, "sha512-pjGxK5EY7yWml78ALejFkWmgHsU7wbFQrISiugpH6FbUJhgEvw3xFZ/EBAtLl7QtL0WdQKiG9eWJ3mOKGTukHw=="],
"@next/swc-linux-x64-gnu": ["@next/swc-linux-x64-gnu@16.4.0", "", { "os": "linux", "cpu": "x64" }, "sha512-D5M5xLWQVd1CvR+L7BickM1weRfmM41x3L1NWcnKY/oyJJqr1qwaCgmu3dMAhLBOMdZwSuDCRV6DJRRpiUkbDQ=="],
"@next/swc-linux-x64-musl": ["@next/swc-linux-x64-musl@16.3.0", "", { "os": "linux", "cpu": "x64" }, "sha512-sjo++Xx+lomlPs3HRsHWhVDyGG6ms1kGW5EtHLERdII8AyG1i+f6aq68xHREO6AEMlhjTNEWBSmfJfqm9orf7g=="],
"@next/swc-linux-x64-musl": ["@next/swc-linux-x64-musl@16.4.0", "", { "os": "linux", "cpu": "x64" }, "sha512-8d5WLS6a9YalqpOgXdlbvonFu+sIgjA+CO6tGzetrpPVcUL56foa7B7664h41rAlbLi5fJwK4vWji3zf4QDy+w=="],
"@next/swc-win32-arm64-msvc": ["@next/swc-win32-arm64-msvc@16.3.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-C5JSgiO54wURdaxdEUIXqkz04uMqC9UmPX1gtDrV/5Tf1UowdWYI8uA5hfFbPolTlp0q4KZ60xlHePNibf0VIw=="],
"@next/swc-win32-arm64-msvc": ["@next/swc-win32-arm64-msvc@16.4.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-sQuOIiW3snb48UwrBcDMvFA/u03qtw2LeuSIxFIQ9AJuW9UG/4Ddsfo+eV73PnZwBhyncMtsKVh7PrzMol2/fA=="],
"@next/swc-win32-x64-msvc": ["@next/swc-win32-x64-msvc@16.3.0", "", { "os": "win32", "cpu": "x64" }, "sha512-fDOggsweNb5SSw0ZKVk6U+gxSyGFFlIBY/LBc1r8GUj4u/6t6oArL+Pmkg0MBnsgR+KkdsURilVH4F3GXUGepA=="],
"@orama/orama": ["@orama/orama@3.1.18", "", {}, ""],
"@next/swc-win32-x64-msvc": ["@next/swc-win32-x64-msvc@16.4.0", "", { "os": "win32", "cpu": "x64" }, "sha512-6/33lCuxpdHUy27RegyGM/5uTpF7YZd3UR4D0gpkOA/tWY5YR7msbQjqPgCZmSmxrrTLGCXYA4A8vT2H5DPGTQ=="],
"@radix-ui/number": ["@radix-ui/number@1.1.3", "", {}, "sha512-Road2bidD0uu/1BGDOWNdPI06g0lIRy6IF9GZcIrDK2KGItfor8IQwQa+yM2ERgHM1MmHxaxpTzk0/Jp42lNfA=="],
@@ -223,13 +223,13 @@
"@radix-ui/react-collection": ["@radix-ui/react-collection@1.1.15", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.5", "@radix-ui/react-context": "1.2.2", "@radix-ui/react-primitive": "2.1.10", "@radix-ui/react-slot": "1.3.3" }, "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-9W+B9NPF0NaaPh/1NJd3+KqsnlLqU9H7T2rvww+fp+T/evVXdNAyYcnfRQZFOjkR1ajQp3yORlqnI8soawLvNA=="],
"@radix-ui/react-compose-refs": ["@radix-ui/react-compose-refs@1.1.3", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" } }, "sha512-rYOP8OMnuuPMQF1uhPVlGNcCDlkokKqGFE3JcxFViIkAXP7EvFWUliJAstrapypaBLJNHbZL6jGhbVDGTwmVhA=="],
"@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@radix-ui/react-context": ["@radix-ui/react-context@1.2.2", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-RHCUGwKHDr0hDGg4X7ma4JG4/+12qxw8rkh5QKdDldlCvtja6nUx1Ef/8HVrJze81lEsgLQlqjzjGNHantgnQA=="],
"@radix-ui/react-dialog": ["@radix-ui/react-dialog@1.1.23", "", { "dependencies": { "@radix-ui/primitive": "1.1.7", "@radix-ui/react-compose-refs": "1.1.5", "@radix-ui/react-context": "1.2.2", "@radix-ui/react-dismissable-layer": "1.1.19", "@radix-ui/react-focus-guards": "1.1.6", "@radix-ui/react-focus-scope": "1.1.16", "@radix-ui/react-id": "1.1.4", "@radix-ui/react-portal": "1.1.17", "@radix-ui/react-presence": "1.1.10", "@radix-ui/react-primitive": "2.1.10", "@radix-ui/react-slot": "1.3.3", "@radix-ui/react-use-controllable-state": "1.2.6", "@radix-ui/react-use-layout-effect": "1.1.4", "aria-hidden": "^1.2.4", "react-remove-scroll": "^2.7.2" }, "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-Ksw4WeROkO4rC9k/onilX/Ao2Cr1ku1unMNH+XSCcP4jSXYu7HDsg9n4ojMjVb22XpYjAQ9qfrFlVbru1vXDUA=="],
"@radix-ui/react-direction": ["@radix-ui/react-direction@1.1.2", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" } }, "sha512-C3vFhbyi4SW3PmbAi6Awpu4OzJtd0MxGurvSsYtr7p7nM8RNB3VAF3CUmnp2j50knpkrRcB7+ycVXzgLgF6yNA=="],
"@radix-ui/react-direction": ["@radix-ui/react-direction@1.1.4", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-5pzg4FGQNpExhnhT2zlrP1wZFaYCd1K0nYWoFAdcYoYK868IEigqMX3B3f8yIoRlAhAeDWciLI6ZdCKHF9P4Vg=="],
"@radix-ui/react-dismissable-layer": ["@radix-ui/react-dismissable-layer@1.1.19", "", { "dependencies": { "@radix-ui/primitive": "1.1.7", "@radix-ui/react-compose-refs": "1.1.5", "@radix-ui/react-primitive": "2.1.10", "@radix-ui/react-use-callback-ref": "1.1.4", "@radix-ui/react-use-effect-event": "0.0.5" }, "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-8g4pfOL9HoKKLWGiypT+dphVqjFfmcXO5GBnhsG6zI+lxAx/8feQpr+1LSN8Re3hiZ+XkLNS4O9ztK11/LzQ6w=="],
@@ -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.0", "", { "dependencies": { "@radix-ui/react-compose-refs": "1.1.3" }, "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" } }, "sha512-MojKku4U/miO8Av4Dkb+ctMAQx7JmY96LmtDQlAarCRtd7rN52QCSzBF+XAvr5S6coSVj9HEPBgHAHKEJVk/WA=="],
"@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-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=="],
@@ -293,8 +293,6 @@
"@shikijs/themes": ["@shikijs/themes@4.4.3", "", { "dependencies": { "@shikijs/types": "4.4.3" } }, "sha512-w8UHjeUnIR965KMWJHUPXOc2mNJUnK3vpVLYLvw5IYU2mnTTJ89E24OrJDBNiJDQ0qzb0tc4l7mrIXx5cFeIyw=="],
"@shikijs/twoslash": ["@shikijs/twoslash@4.4.3", "", { "dependencies": { "@shikijs/core": "4.4.3", "@shikijs/types": "4.4.3", "twoslash": "^0.3.9" }, "peerDependencies": { "typescript": ">=5.5.0" } }, "sha512-m7HNzunEIHRk1jCya3ngGsO3+8pYxrPIIxtdJewg/W8ceW/+m/mSsm4jM3L9DvYYNa8Rvbu7Dabt3BOpCclz8Q=="],
"@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/vscode-textmate": ["@shikijs/vscode-textmate@10.0.2", "", {}, ""],
@@ -305,7 +303,7 @@
"@standard-schema/utils": ["@standard-schema/utils@0.3.0", "", {}, ""],
"@swc/helpers": ["@swc/helpers@0.5.15", "", { "dependencies": { "tslib": "^2.8.0" } }, ""],
"@swc/helpers": ["@swc/helpers@0.5.23", "", { "dependencies": { "tslib": "^2.8.0" } }, "sha512-5lSsMOTXURePglDfvuAQUqkGek9Hg2kksOYay2m0+XR++b2NWYL/4sWyuvVBIs8oKnJaxkdi9whaL/sqN13afw=="],
"@tailwindcss/node": ["@tailwindcss/node@4.3.3", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "enhanced-resolve": "^5.24.1", "jiti": "^2.7.0", "lightningcss": "1.32.0", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.3.3" } }, "sha512-/T8IKEsf9VTU6tLjgC7+sv2mOPtQxzE2jMw7u4Tt40Tx+QSZxpzh95/H6cMKoja9XuW7iMdLJYBB0o9G1CaAgg=="],
@@ -337,8 +335,6 @@
"@tailwindcss/postcss": ["@tailwindcss/postcss@4.3.3", "", { "dependencies": { "@alloc/quick-lru": "^5.2.0", "@tailwindcss/node": "4.3.3", "@tailwindcss/oxide": "4.3.3", "postcss": "^8.5.16", "tailwindcss": "4.3.3" } }, "sha512-JTSZZGQi1AyKirbLN3azmjVzef92tcX7h+iSqPdaeStyFpGpDlKvvpxeOE8njhbUanbRwr3z8DyzhICWnMtQeg=="],
"@ts-morph/common": ["@ts-morph/common@0.29.0", "", { "dependencies": { "minimatch": "^10.0.1", "path-browserify": "^1.0.1", "tinyglobby": "^0.2.14" } }, "sha512-35oUmphHbJvQ/+UTwFNme/t2p3FoKiGJ5auTjjpNTop2dyREspirjMy82PLSC1pnDJ8ah1GU98hwpVt64YXQsg=="],
"@turf/boolean-point-in-polygon": ["@turf/boolean-point-in-polygon@7.3.4", "", { "dependencies": { "@turf/helpers": "7.3.4", "@turf/invariant": "7.3.4", "@types/geojson": "^7946.0.10", "point-in-polygon-hao": "^1.1.0", "tslib": "^2.8.1" } }, ""],
"@turf/helpers": ["@turf/helpers@7.3.4", "", { "dependencies": { "@types/geojson": "^7946.0.10", "tslib": "^2.8.1" } }, ""],
@@ -371,7 +367,7 @@
"@types/geojson": ["@types/geojson@7946.0.16", "", {}, ""],
"@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"@types/hast": ["@types/hast@3.0.5", "", { "dependencies": { "@types/unist": "*" } }, "sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g=="],
"@types/mdast": ["@types/mdast@4.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
@@ -379,17 +375,55 @@
"@types/ms": ["@types/ms@2.1.0", "", {}, ""],
"@types/node": ["@types/node@26.2.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-5IviulTZeRNp2vAJ514cc/HUlY5nZ9fCbq9DMyC52BrhFZACo3nI0R7qBxhQmo/d27NFe96ur/b7Wwxklda+kg=="],
"@types/node": ["@types/node@26.6.4", "", { "dependencies": { "undici-types": "~8.9.0" } }, "sha512-ldVPDCzj7fsaGZrLB0NuHuTvJcsNasysBAqMolr/cgxrLd1xbqxIr3XJiPnHHJUCxj5sNF1vnRj9aWnrVh5Jcg=="],
"@types/react": ["@types/react@19.2.18", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-AnzbBERsrLKtk2XSfTbYRLjQPdy116Sty4q+T+Bp3IC4l6jNBvreVPAHmpq9qhXQM7CXZPjLVmGMw9sy+hxQ3w=="],
"@types/react": ["@types/react@19.3.0", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg=="],
"@types/react-dom": ["@types/react-dom@19.2.3", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, ""],
"@types/react-dom": ["@types/react-dom@19.3.0", "", { "peerDependencies": { "@types/react": "^19.3.0" } }, "sha512-ZI7bU42mZXXKHn/qNLEw2IrbiINU7X5+vfgdixBHkCNpYWXjKgfQ/P+uyGb5CjOLB9UcnTeg3rylQtV2hym44Q=="],
"@types/unist": ["@types/unist@3.0.3", "", {}, ""],
"@types/use-sync-external-store": ["@types/use-sync-external-store@0.0.6", "", {}, ""],
"@typescript/vfs": ["@typescript/vfs@1.6.4", "", { "dependencies": { "debug": "^4.4.3" }, "peerDependencies": { "typescript": "*" } }, ""],
"@typescript/typescript-aix-ppc64": ["@typescript/typescript-aix-ppc64@7.0.2", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="],
"@typescript/typescript-darwin-arm64": ["@typescript/typescript-darwin-arm64@7.0.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA=="],
"@typescript/typescript-darwin-x64": ["@typescript/typescript-darwin-x64@7.0.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA=="],
"@typescript/typescript-freebsd-arm64": ["@typescript/typescript-freebsd-arm64@7.0.2", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ=="],
"@typescript/typescript-freebsd-x64": ["@typescript/typescript-freebsd-x64@7.0.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw=="],
"@typescript/typescript-linux-arm": ["@typescript/typescript-linux-arm@7.0.2", "", { "os": "linux", "cpu": "arm" }, "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ=="],
"@typescript/typescript-linux-arm64": ["@typescript/typescript-linux-arm64@7.0.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ=="],
"@typescript/typescript-linux-loong64": ["@typescript/typescript-linux-loong64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ=="],
"@typescript/typescript-linux-mips64el": ["@typescript/typescript-linux-mips64el@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA=="],
"@typescript/typescript-linux-ppc64": ["@typescript/typescript-linux-ppc64@7.0.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA=="],
"@typescript/typescript-linux-riscv64": ["@typescript/typescript-linux-riscv64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ=="],
"@typescript/typescript-linux-s390x": ["@typescript/typescript-linux-s390x@7.0.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw=="],
"@typescript/typescript-linux-x64": ["@typescript/typescript-linux-x64@7.0.2", "", { "os": "linux", "cpu": "x64" }, "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A=="],
"@typescript/typescript-netbsd-arm64": ["@typescript/typescript-netbsd-arm64@7.0.2", "", { "os": "none", "cpu": "arm64" }, "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA=="],
"@typescript/typescript-netbsd-x64": ["@typescript/typescript-netbsd-x64@7.0.2", "", { "os": "none", "cpu": "x64" }, "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA=="],
"@typescript/typescript-openbsd-arm64": ["@typescript/typescript-openbsd-arm64@7.0.2", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ=="],
"@typescript/typescript-openbsd-x64": ["@typescript/typescript-openbsd-x64@7.0.2", "", { "os": "openbsd", "cpu": "x64" }, "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg=="],
"@typescript/typescript-sunos-x64": ["@typescript/typescript-sunos-x64@7.0.2", "", { "os": "sunos", "cpu": "x64" }, "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g=="],
"@typescript/typescript-win32-arm64": ["@typescript/typescript-win32-arm64@7.0.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ=="],
"@typescript/typescript-win32-x64": ["@typescript/typescript-win32-x64@7.0.2", "", { "os": "win32", "cpu": "x64" }, "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g=="],
"@ungap/structured-clone": ["@ungap/structured-clone@1.3.0", "", {}, ""],
@@ -397,35 +431,37 @@
"@workflow/serde": ["@workflow/serde@4.1.0", "", {}, "sha512-pav4F2BoirECWR7Nf1TKt+2eETcBj7jj4cBefQ8VXQCA6NPkaKeLfj/zMgi+3zYV5ZIBT4GuUiphsj0/b9hPQQ=="],
"@yuku-analyzer/binding-darwin-arm64": ["@yuku-analyzer/binding-darwin-arm64@0.6.12", "", { "os": "darwin", "cpu": "arm64" }, "sha512-9rpIP7IeybjyvWUf6WnU24h1qo+JdxIHr1o3yb06HoE8tM3S/Jh5RrUw9aw5P9BKSIvSPbLyVlItX7PcD3o5bQ=="],
"@yuku-analyzer/binding-android-arm64": ["@yuku-analyzer/binding-android-arm64@0.10.2", "", { "os": "android", "cpu": "arm64" }, "sha512-xt4Vy3RTBw1NfszBlf4A0Rr6ZjA/th2Pj9XlWFLQHW9A1qOCtxNCoIWSzn/INtnZLMB4jO2gWdEtSaHUtK73wA=="],
"@yuku-analyzer/binding-darwin-x64": ["@yuku-analyzer/binding-darwin-x64@0.6.12", "", { "os": "darwin", "cpu": "x64" }, "sha512-ELLhNT4FGnqY8yh0W3cSs9rGMSeUyhib1aYD84RupjlfsrDTrQRoDhWu01Dv6xCfYgASYaj1Abntk91A7njNag=="],
"@yuku-analyzer/binding-darwin-arm64": ["@yuku-analyzer/binding-darwin-arm64@0.10.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-ftokSqvYXZxfmA/bfIbp8c1BJ8QxNax371kUOQNFyvR5hmtKqQyTqSKtMk+WaixHM3w4tKj/JdyY+ud1bGamXA=="],
"@yuku-analyzer/binding-freebsd-x64": ["@yuku-analyzer/binding-freebsd-x64@0.6.12", "", { "os": "freebsd", "cpu": "x64" }, "sha512-s76XocUMlK9liTyipALFb2K64ku35u/wg238A0NW8U5CUDsuIe/8tu5TzdLjJAGxnd0IV+gBneDt9cJJzLeFRQ=="],
"@yuku-analyzer/binding-darwin-x64": ["@yuku-analyzer/binding-darwin-x64@0.10.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-yUrmmhmF5R4Xmbfo8gUxJKr3YbvbLcE2JvLhDLzFJkMN29/fGm6K3dZX6YpNecfgBDnQ+VywGp8K9xjRaBFZ3Q=="],
"@yuku-analyzer/binding-linux-arm-gnu": ["@yuku-analyzer/binding-linux-arm-gnu@0.6.12", "", { "os": "linux", "cpu": "arm" }, "sha512-hm8Tq0umop3RGu6dOMF61q69tYn1bDp1CeYD5ZjuGFQJclp0moVtjzY4z0bzusicKeZ9+k5LRroR0p5HWC2hDw=="],
"@yuku-analyzer/binding-freebsd-x64": ["@yuku-analyzer/binding-freebsd-x64@0.10.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-cy9+KvVoK5Xad3Vs5pLwAeZf3JC/1y0XJElgv1q6g7W7g/n52FRjedpYmQiJeMZdnhJiAshq7Vz/Xj3jC5Ns2Q=="],
"@yuku-analyzer/binding-linux-arm-musl": ["@yuku-analyzer/binding-linux-arm-musl@0.6.12", "", { "os": "linux", "cpu": "arm" }, "sha512-CxtPKLddogHAB3ZHVWaUl+U8jx0pdriTSbQ1K/orlDqU0GDhg8LuIRyUscP7r2/62fGGMzkc119fE71I4Nl1Fg=="],
"@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-analyzer/binding-linux-arm64-gnu": ["@yuku-analyzer/binding-linux-arm64-gnu@0.6.12", "", { "os": "linux", "cpu": "arm64" }, "sha512-EOyLcpAmF5qAVDKmKvV7xt8oBGeWQ92CqFI4s7h7TRlrF6TfGRrh8PwawGn92gFploNLAYj/1Z9Q1gVvwGgG9g=="],
"@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-analyzer/binding-linux-arm64-musl": ["@yuku-analyzer/binding-linux-arm64-musl@0.6.12", "", { "os": "linux", "cpu": "arm64" }, "sha512-T3eCYy6bMnVRMQEYAbDcpj08/XM93dBTtnn/DDocJN21RARe+KCzWKeL26J3yd3bOW3WVjVLq09BfdpAGB0buQ=="],
"@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-analyzer/binding-linux-x64-gnu": ["@yuku-analyzer/binding-linux-x64-gnu@0.6.12", "", { "os": "linux", "cpu": "x64" }, "sha512-1Y+noIuvnDugIVsoIr5NduZqX7KuFTzICSkvG8RW3OKK9URVeTOicKK217i44ABZSSZJ7A0E7vzifapx0c9VDw=="],
"@yuku-analyzer/binding-linux-arm64-musl": ["@yuku-analyzer/binding-linux-arm64-musl@0.10.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-TppF2j194mOQ/kBXvNr9u5TYO+eR9r8ieg4lTIEyJIVYHAR9GWeB0oFHLcJiLXVa3qUJGzE4bmzSntCW5ylA7A=="],
"@yuku-analyzer/binding-linux-x64-musl": ["@yuku-analyzer/binding-linux-x64-musl@0.6.12", "", { "os": "linux", "cpu": "x64" }, "sha512-woN/GuG95Fd6bp+ZQfmiFrZnoA2hdu3vfVSc89A8LElnYpzFaJM81sOZp8f3tVOVUJxbt7KAUiCLwSy34MJKqA=="],
"@yuku-analyzer/binding-linux-x64-gnu": ["@yuku-analyzer/binding-linux-x64-gnu@0.10.2", "", { "os": "linux", "cpu": "x64" }, "sha512-03xu6ocJuwhm1a/JKmrHiaJUO1Oj86rABsm4FAl8AvfewfW/9idIUmPiFxZfb6RfiIONegebsTGJhFx0NbBNpA=="],
"@yuku-analyzer/binding-win32-arm64": ["@yuku-analyzer/binding-win32-arm64@0.6.12", "", { "os": "win32", "cpu": "arm64" }, "sha512-8OVFnKbK+lgsL6MqILPLpzlsa00K4KiKsdbHH94hpGcrqaz1jv+k0Y7ujSaoYTWw5Bb7Lr9GJ3L1n1hT2sXoYA=="],
"@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-analyzer/binding-win32-x64": ["@yuku-analyzer/binding-win32-x64@0.6.12", "", { "os": "win32", "cpu": "x64" }, "sha512-3w8w1Xc5njwgbGTcn3JfDxWuQnFvtSll1D8gBlk4U8CI5v7ibKOMIdABucCXH8WtsRREG0ME5Vn0i422eX3zLQ=="],
"@yuku-analyzer/binding-win32-arm64": ["@yuku-analyzer/binding-win32-arm64@0.10.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-f534qNc5YaJI29e1oryxEnxPkp7WCYJ1j7ChSec8pQNlYqTm8Tao7hij7NxRF+9BuxzeZCZ+WsbaAfLlklR0Eg=="],
"@yuku-toolchain/types": ["@yuku-toolchain/types@0.6.11", "", {}, "sha512-i1JYFNJaKNCgyJ/nVoR8GK7wvlXF+ShYzFHBauWcvg8IoiXInK7pVziHcgNz/MWLPNr/Mb/CtmXccrJMkKqSHQ=="],
"@yuku-analyzer/binding-win32-x64": ["@yuku-analyzer/binding-win32-x64@0.10.2", "", { "os": "win32", "cpu": "x64" }, "sha512-sKHkmLK8BsindMfyIThoN0bWC5uqSJEVNaLRD/ifA99mtb0UDin1ZCg4WYSVQAmM4k2iOTl4UZx/p3zcBiBgYw=="],
"@yuku-toolchain/types": ["@yuku-toolchain/types@0.10.2", "", {}, "sha512-sSeo4SSSToiS+sSD+bwn/s94EEcaLJ7tG5LCp8gFYC1G5VzxzX7fqB6m9RU1yMD8KTpu6zdU/I1NlQf8hVBJ9Q=="],
"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.59", "", { "dependencies": { "@ai-sdk/gateway": "4.0.47", "@ai-sdk/provider": "4.0.7", "@ai-sdk/provider-utils": "5.0.26" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-p10cqg8KvLIZi7Gk+XsQjoYoLENoDdEYvehP0rSo6Wg15nbCmP+nwIy1rOIX+WGIDWGdI+jmhjVx5fXShBVC3w=="],
"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=="],
"aria-hidden": ["aria-hidden@1.2.6", "", { "dependencies": { "tslib": "^2.0.0" } }, ""],
@@ -433,12 +469,8 @@
"bail": ["bail@2.0.2", "", {}, ""],
"balanced-match": ["balanced-match@4.0.4", "", {}, ""],
"baseline-browser-mapping": ["baseline-browser-mapping@2.10.16", "", { "bin": "dist/cli.cjs" }, ""],
"brace-expansion": ["brace-expansion@5.0.6", "", { "dependencies": { "balanced-match": "^4.0.2" } }, "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g=="],
"caniuse-lite": ["caniuse-lite@1.0.30001786", "", {}, ""],
"ccount": ["ccount@2.0.1", "", {}, ""],
@@ -459,9 +491,7 @@
"clsx": ["clsx@2.1.1", "", {}, "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA=="],
"cnfast": ["cnfast@0.0.8", "", { "bin": { "cnfast": "bin/cli.js" } }, "sha512-EjXKMfGfdwtV4AcNSQ6AwQaVzpC1B7IxeiwA3FlhTXz+YFlMKVi4c1JX9tgD2QOlahQXjB8KUXrBaYG+3v871Q=="],
"code-block-writer": ["code-block-writer@13.0.3", "", {}, ""],
"cn": ["cn@0.2.6", "", { "bin": { "cn": "bin/cn.mjs" } }, "sha512-+i4L0zUGgRcEnhsxueVrP7iBGxBx5iD0WOTYg1MwFEu2ZyCmH5Ov2V1cul2Ht5UchRQQgftCf4be/RxspuW6QQ=="],
"collapse-white-space": ["collapse-white-space@2.1.0", "", {}, ""],
@@ -519,7 +549,7 @@
"esast-util-from-js": ["esast-util-from-js@2.0.1", "", { "dependencies": { "@types/estree-jsx": "^1.0.0", "acorn": "^8.0.0", "esast-util-from-estree": "^2.0.0", "vfile-message": "^4.0.0" } }, ""],
"esbuild": ["esbuild@0.28.1", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.28.1", "@esbuild/android-arm": "0.28.1", "@esbuild/android-arm64": "0.28.1", "@esbuild/android-x64": "0.28.1", "@esbuild/darwin-arm64": "0.28.1", "@esbuild/darwin-x64": "0.28.1", "@esbuild/freebsd-arm64": "0.28.1", "@esbuild/freebsd-x64": "0.28.1", "@esbuild/linux-arm": "0.28.1", "@esbuild/linux-arm64": "0.28.1", "@esbuild/linux-ia32": "0.28.1", "@esbuild/linux-loong64": "0.28.1", "@esbuild/linux-mips64el": "0.28.1", "@esbuild/linux-ppc64": "0.28.1", "@esbuild/linux-riscv64": "0.28.1", "@esbuild/linux-s390x": "0.28.1", "@esbuild/linux-x64": "0.28.1", "@esbuild/netbsd-arm64": "0.28.1", "@esbuild/netbsd-x64": "0.28.1", "@esbuild/openbsd-arm64": "0.28.1", "@esbuild/openbsd-x64": "0.28.1", "@esbuild/openharmony-arm64": "0.28.1", "@esbuild/sunos-x64": "0.28.1", "@esbuild/win32-arm64": "0.28.1", "@esbuild/win32-ia32": "0.28.1", "@esbuild/win32-x64": "0.28.1" }, "bin": "bin/esbuild" }, "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw=="],
"esbuild": ["esbuild@0.28.2", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.28.2", "@esbuild/android-arm": "0.28.2", "@esbuild/android-arm64": "0.28.2", "@esbuild/android-x64": "0.28.2", "@esbuild/darwin-arm64": "0.28.2", "@esbuild/darwin-x64": "0.28.2", "@esbuild/freebsd-arm64": "0.28.2", "@esbuild/freebsd-x64": "0.28.2", "@esbuild/linux-arm": "0.28.2", "@esbuild/linux-arm64": "0.28.2", "@esbuild/linux-ia32": "0.28.2", "@esbuild/linux-loong64": "0.28.2", "@esbuild/linux-mips64el": "0.28.2", "@esbuild/linux-ppc64": "0.28.2", "@esbuild/linux-riscv64": "0.28.2", "@esbuild/linux-s390x": "0.28.2", "@esbuild/linux-x64": "0.28.2", "@esbuild/netbsd-arm64": "0.28.2", "@esbuild/netbsd-x64": "0.28.2", "@esbuild/openbsd-arm64": "0.28.2", "@esbuild/openbsd-x64": "0.28.2", "@esbuild/openharmony-arm64": "0.28.2", "@esbuild/sunos-x64": "0.28.2", "@esbuild/win32-arm64": "0.28.2", "@esbuild/win32-ia32": "0.28.2", "@esbuild/win32-x64": "0.28.2" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA=="],
"escape-string-regexp": ["escape-string-regexp@5.0.0", "", {}, ""],
@@ -541,7 +571,7 @@
"eventemitter3": ["eventemitter3@5.0.4", "", {}, ""],
"eventsource-parser": ["eventsource-parser@3.0.6", "", {}, ""],
"eventsource-parser": ["eventsource-parser@3.1.1", "", {}, "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ=="],
"extend": ["extend@3.0.2", "", {}, ""],
@@ -549,17 +579,17 @@
"fdir": ["fdir@6.5.0", "", { "peerDependencies": { "picomatch": "^3 || ^4" } }, ""],
"framer-motion": ["framer-motion@12.43.0", "", { "dependencies": { "motion-dom": "^12.43.0", "motion-utils": "^12.39.0", "tslib": "^2.4.0" }, "peerDependencies": { "@emotion/is-prop-valid": "*", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@emotion/is-prop-valid", "react", "react-dom"] }, "sha512-1eaL3RvR/kAlbG7UYcpMptEyzPoENO0c6w7ZnB3/hh2vSAz/6uGAFn6fdoqTBguNstf3MsFhJHsD/0DHiclG+g=="],
"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=="],
"fumadocs-core": ["fumadocs-core@16.11.5", "", { "dependencies": { "@orama/orama": "^3.1.18", "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", "remark": "^15.0.1", "remark-gfm": "^4.0.1", "remark-rehype": "^11.1.2", "scroll-into-view-if-needed": "^3.1.0", "shiki": "^4.3.1", "tinyglobby": "^0.2.17", "unified": "^11.0.5", "unist-util-visit": "^5.1.0", "vfile": "^6.0.3", "yaml": "^2.9.0" }, "peerDependencies": { "@mdx-js/mdx": "*", "@mixedbread/sdk": "0.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", "@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-YrHjS09+QYYKOSTGyiZbxF/VDs7ciMcjurYBGfmYqtzdj14k7Ho0HX9c6VuvG54YsYHQs5mGWemT1TXm7vDBaA=="],
"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-mdx": ["fumadocs-mdx@15.2.0", "", { "dependencies": { "@mdx-js/mdx": "^3.1.1", "@standard-schema/spec": "^1.1.0", "chokidar": "^5.0.0", "esbuild": "^0.28.1", "estree-util-value-to-estree": "^3.5.0", "github-slugger": "^2.0.0", "magic-string": "^0.30.21", "mdast-util-mdx": "^3.0.0", "picocolors": "^1.1.1", "picomatch": "^4.0.5", "tinyexec": "^1.2.4", "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.0", "yuku-analyzer": "^0.6.3", "zod": "^4.4.3" }, "peerDependencies": { "@fumadocs/satteri": "0.x.x", "@types/mdast": "*", "@types/mdx": "*", "@types/react": "*", "fumadocs-core": "^16.7.0", "mdast-util-directive": "*", "next": "^15.3.0 || ^16.0.0", "react": "^19.2.0", "rolldown": "*", "satteri": "^0.9.4", "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-+yBP8QYw5wA9LF5eVdMhwbP7KT1OF4B/YfC6PZoD2jz0amZi1B+6QHTI6XoRRSTmhWrI4cL5LU1DspW0itk+NA=="],
"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-twoslash": ["fumadocs-twoslash@3.3.0", "", { "dependencies": { "@base-ui/react": "^1.6.0", "@shikijs/twoslash": "^4.3.1", "cnfast": "^0.0.8", "mdast-util-from-markdown": "^2.0.3", "mdast-util-gfm": "^3.1.0", "mdast-util-to-hast": "^13.2.1", "twoslash": "^0.3.9" }, "peerDependencies": { "@types/react": "*", "fumadocs-core": "^16.7.16", "fumadocs-ui": "^16.7.16", "react": "^19.2.0", "react-dom": "^19.2.0", "shiki": "4.x.x" }, "optionalPeers": ["@types/react"] }, "sha512-IR+oYbjsR59h/R7AvdeEdHEY48ygCHII3tUZGC3QnUVug5+qN1wlRNr30gAfOvrau/mdiRKwONuJCOKOWqEFbg=="],
"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-typescript": ["fumadocs-typescript@5.3.0", "", { "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.3.1", "ts-morph": "^28.0.0", "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-UwYug2z01/hsjgmyoPL/MCz66pyZarpxOV9hIgnyNIhopwwcReCykEnRjchY342gIhZqUjTlY/TCJRorkCHhBA=="],
"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-ui": ["fumadocs-ui@16.11.5", "", { "dependencies": { "@fuma-translate/react": "^1.0.2", "@fumadocs/tailwind": "0.1.1", "@radix-ui/react-accordion": "^1.2.16", "@radix-ui/react-collapsible": "^1.1.16", "@radix-ui/react-dialog": "^1.1.19", "@radix-ui/react-direction": "^1.1.2", "@radix-ui/react-navigation-menu": "^1.2.18", "@radix-ui/react-popover": "^1.1.19", "@radix-ui/react-presence": "^1.1.7", "@radix-ui/react-scroll-area": "^1.2.14", "@radix-ui/react-slot": "^1.3.0", "@radix-ui/react-tabs": "^1.1.17", "class-variance-authority": "^0.7.1", "cnfast": "^0.0.8", "lucide-react": "^1.24.0", "motion": "^12.42.2", "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.3.1", "unist-util-visit": "^5.1.0" }, "peerDependencies": { "@types/mdx": "*", "@types/react": "*", "fumadocs-core": "16.11.5", "next": "16.x.x", "react": "^19.2.0", "react-dom": "^19.2.0", "takumi-js": "*" }, "optionalPeers": ["@types/mdx", "@types/react", "next", "takumi-js"] }, "sha512-Eda7x2Hk7E1iIjZ4uES0xxGr25Z72efRM5kP8sbgLSLhWg8TDCyWddvKAkzXIq8bupPOuJkdZa/YVvXbCktIEA=="],
"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=="],
"get-nonce": ["get-nonce@1.0.1", "", {}, ""],
@@ -635,9 +665,9 @@
"longest-streak": ["longest-streak@3.1.0", "", {}, ""],
"lucide-react": ["lucide-react@1.20.0", "", { "peerDependencies": { "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-jhXLeC/7m0/tjL1nzMdKk6x256zWA6AtbhTVreHOiKPoeX2d6MK4FbyIQPpVq0E6iPWBisyy1TW+pEge/uMEuQ=="],
"lucide-react": ["lucide-react@1.52.0", "", { "peerDependencies": { "@types/react": "*", "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" }, "optionalPeers": ["@types/react"] }, "sha512-TUgPtl5ZI9WgxOcbu4ckaC5B3l1qxPQrCMgb6OfUB9owx/OvSJfcf93SMgUWAxRw5/1XDfh9uI5F5iNGXCcGDQ=="],
"magic-string": ["magic-string@0.30.21", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.5" } }, ""],
"magic-string": ["magic-string@1.4.3", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.6.0" } }, "sha512-z12OxmaPGE0F4xlpGdjuAUckipLpQlTAuAmyGhNoD7ODpYUzvDfvtxUbjM/jwznyP178oju/KDdyi220wNJ0RQ=="],
"markdown-extensions": ["markdown-extensions@2.0.0", "", {}, ""],
@@ -747,49 +777,47 @@
"micromark-util-types": ["micromark-util-types@2.0.2", "", {}, ""],
"minimatch": ["minimatch@10.2.5", "", { "dependencies": { "brace-expansion": "^5.0.5" } }, ""],
"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@12.43.0", "", { "dependencies": { "framer-motion": "^12.43.0", "tslib": "^2.4.0" }, "peerDependencies": { "@emotion/is-prop-valid": "*", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0" }, "optionalPeers": ["@emotion/is-prop-valid", "react", "react-dom"] }, "sha512-BQgQbSa9Hn3/mtbib0MK53y6JSANa+YKUKlaYnWzAVDH424RYQ5LVpV3pNiWH00BA2z4ojsSdMzqT7g2FQwjuQ=="],
"motion-dom": ["motion-dom@13.5.1", "", { "dependencies": { "motion-utils": "13.5.0" } }, "sha512-/7CVCD20Mz1KobktorpdgvowV0V41J7UxqE+qWS3GkSJqrRr5ft+2RloOYtEKv+wvBp3JaSFBclhxt4ja8ovHg=="],
"motion-dom": ["motion-dom@12.43.0", "", { "dependencies": { "motion-utils": "^12.39.0" } }, "sha512-azKON4d9S65PEoFUiQTMTgPheEmzf2QngdRc50AKfJp9Q9mmcBVw22c8eMq9k8kxOFHdL7+WZY7N/5F/lwiDag=="],
"motion-utils": ["motion-utils@12.39.0", "", {}, "sha512-8nadJAJjTtqRkmRF36FoJTrywK9nnFmnPwnSMyxaOCU7GDjN9RTMJIxx9De8ErM+vpPhMccr/6fo5WciyQLnMQ=="],
"motion-utils": ["motion-utils@13.5.0", "", {}, "sha512-Hqe/sqjIKliPZg8sVjWAkdySDPJNIeKH+euVkDOG8ri3DUUU7ZjndmHsGqEPz2iHpiyVaV5I22iguCMHU2he+Q=="],
"ms": ["ms@2.1.3", "", {}, ""],
"nanoid": ["nanoid@3.3.18", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w=="],
"nanoid": ["nanoid@3.3.20", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ=="],
"next": ["next@16.3.0", "", { "dependencies": { "@next/env": "16.3.0", "@swc/helpers": "0.5.15", "baseline-browser-mapping": "^2.9.19", "caniuse-lite": "^1.0.30001579", "postcss": "8.5.23", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "16.3.0", "@next/swc-darwin-x64": "16.3.0", "@next/swc-linux-arm64-gnu": "16.3.0", "@next/swc-linux-arm64-musl": "16.3.0", "@next/swc-linux-x64-gnu": "16.3.0", "@next/swc-linux-x64-musl": "16.3.0", "@next/swc-win32-arm64-msvc": "16.3.0", "@next/swc-win32-x64-msvc": "16.3.0", "sharp": "^0.35.3" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.51.1", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-NEdGOzH+08eTXMUp9UYkA99Nhi5N6Thrhc1jgFOQgfgnGK/dA2hRwBpXep+exdFQrnwlRf/3Wixyp8lLBUpE2A=="],
"next": ["next@16.4.0", "", { "dependencies": { "@next/env": "16.4.0", "@swc/helpers": "0.5.23", "baseline-browser-mapping": "^2.9.19", "caniuse-lite": "^1.0.30001579", "postcss": "8.5.23", "styled-jsx": "5.1.6" }, "optionalDependencies": { "@next/swc-darwin-arm64": "16.4.0", "@next/swc-darwin-x64": "16.4.0", "@next/swc-linux-arm64-gnu": "16.4.0", "@next/swc-linux-arm64-musl": "16.4.0", "@next/swc-linux-x64-gnu": "16.4.0", "@next/swc-linux-x64-musl": "16.4.0", "@next/swc-win32-arm64-msvc": "16.4.0", "@next/swc-win32-x64-msvc": "16.4.0", "sharp": "^0.35.4" }, "peerDependencies": { "@opentelemetry/api": "^1.1.0", "@playwright/test": "^1.51.1", "babel-plugin-react-compiler": "*", "react": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "react-dom": "^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0", "sass": "^1.3.0" }, "optionalPeers": ["@opentelemetry/api", "@playwright/test", "babel-plugin-react-compiler", "sass"], "bin": { "next": "dist/bin/next" } }, "sha512-N2C+9q89Z/oLrsepSRS4jRMtwmUZAoZuAHU0e9T6+sAB5DdhADmrnOW+zjYijlrYFmVfmQhGVGy9eMFoB7UgKg=="],
"next-themes": ["next-themes@0.4.6", "", { "peerDependencies": { "react": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc", "react-dom": "^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc" } }, ""],
"npm-to-yarn": ["npm-to-yarn@3.2.0", "", {}, "sha512-K1HmQeZT2HrjpsR6KgqbN2FAXL2NrJJmNUSD9ck7HGTVu1JKXox8n9SB+tjbU8m8JGLF4OscrroPepew/L7/Xw=="],
"oniguruma-parser": ["oniguruma-parser@0.12.2", "", {}, "sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw=="],
"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@6.49.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", "ws": "^8.18.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["@aws-sdk/credential-provider-node", "@smithy/hash-node", "@smithy/signature-v4", "ws", "zod"] }, "sha512-aYCc0C6L864eR6WSYIwQGyXriw/nIyZx0ObvhzOEVuk0zoBDpynjSbrionWI7q65B5H8jJX0DXR9snEzM6bfPg=="],
"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=="],
"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" } }, ""],
"path-browserify": ["path-browserify@1.0.1", "", {}, ""],
"picocolors": ["picocolors@1.1.1", "", {}, ""],
"picomatch": ["picomatch@4.0.5", "", {}, "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A=="],
"picomatch": ["picomatch@4.0.7", "", {}, "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA=="],
"point-in-polygon-hao": ["point-in-polygon-hao@1.2.4", "", { "dependencies": { "robust-predicates": "^3.0.2" } }, ""],
"postcss": ["postcss@8.5.26", "", { "dependencies": { "nanoid": "^3.3.17", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ=="],
"postcss": ["postcss@8.5.29", "", { "dependencies": { "nanoid": "^3.3.19", "picocolors": "^1.1.1", "source-map-js": "^1.2.2" } }, "sha512-49cGhUbXj8Qenv0iTMxA1cFBzxXoctpC9Ujd77t1WcbJIr6nF/eI7g/8MgxrYldFRuAXvja7xQRwavoW7kgrxQ=="],
"proj4": ["proj4@2.20.8", "", { "dependencies": { "mgrs": "1.0.0", "wkt-parser": "^1.5.5" } }, ""],
"property-information": ["property-information@7.1.0", "", {}, ""],
"react": ["react@19.2.8", "", {}, "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw=="],
"react": ["react@19.3.0", "", {}, "sha512-E8LUcbtBWt20bbl2YoHfx4ZDBdxVTfOKtCZn9cDSJ4l6/nuoApcpIBcj47t2wZoVX8g2ZHuMHbiShgCR1T5Sog=="],
"react-dom": ["react-dom@19.2.8", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.8" } }, "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ=="],
"react-dom": ["react-dom@19.3.0", "", { "dependencies": { "scheduler": "^0.28.0" }, "peerDependencies": { "react": "^19.3.0" } }, "sha512-JDk8dgif51OjFoDE70+OT9ICyYr+69HlmihNwp1+Nsfbna3t5sIiCa9ZJktDmQ4/1b/rn26hIAR2uYXDMr5r0Q=="],
"react-is": ["react-is@19.2.5", "", {}, ""],
@@ -843,19 +871,19 @@
"robust-predicates": ["robust-predicates@3.0.3", "", {}, ""],
"scheduler": ["scheduler@0.27.0", "", {}, ""],
"scheduler": ["scheduler@0.28.0", "", {}, "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw=="],
"scroll-into-view-if-needed": ["scroll-into-view-if-needed@3.1.0", "", { "dependencies": { "compute-scroll-into-view": "^3.0.2" } }, ""],
"semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="],
"sharp": ["sharp@0.35.3", "", { "dependencies": { "@img/colour": "^1.1.0", "detect-libc": "^2.1.2", "semver": "^7.8.5" }, "optionalDependencies": { "@img/sharp-darwin-arm64": "0.35.3", "@img/sharp-darwin-x64": "0.35.3", "@img/sharp-freebsd-wasm32": "0.35.3", "@img/sharp-libvips-darwin-arm64": "1.3.2", "@img/sharp-libvips-darwin-x64": "1.3.2", "@img/sharp-libvips-linux-arm": "1.3.2", "@img/sharp-libvips-linux-arm64": "1.3.2", "@img/sharp-libvips-linux-ppc64": "1.3.2", "@img/sharp-libvips-linux-riscv64": "1.3.2", "@img/sharp-libvips-linux-s390x": "1.3.2", "@img/sharp-libvips-linux-x64": "1.3.2", "@img/sharp-libvips-linuxmusl-arm64": "1.3.2", "@img/sharp-libvips-linuxmusl-x64": "1.3.2", "@img/sharp-linux-arm": "0.35.3", "@img/sharp-linux-arm64": "0.35.3", "@img/sharp-linux-ppc64": "0.35.3", "@img/sharp-linux-riscv64": "0.35.3", "@img/sharp-linux-s390x": "0.35.3", "@img/sharp-linux-x64": "0.35.3", "@img/sharp-linuxmusl-arm64": "0.35.3", "@img/sharp-linuxmusl-x64": "0.35.3", "@img/sharp-webcontainers-wasm32": "0.35.3", "@img/sharp-win32-arm64": "0.35.3", "@img/sharp-win32-ia32": "0.35.3", "@img/sharp-win32-x64": "0.35.3" }, "peerDependencies": { "@types/node": "*" }, "optionalPeers": ["@types/node"] }, "sha512-ej0zVHuZGHCiABXcNxeYhpRnPNPAcvbG8RMdBAhDAxLKkCRVSpK3Iyu7qbqw3JMzoj0REeM6f3tJLtVwl0023Q=="],
"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=="],
"source-map": ["source-map@0.7.6", "", {}, ""],
"source-map-js": ["source-map-js@1.2.1", "", {}, ""],
"source-map-js": ["source-map-js@1.2.2", "", {}, "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw=="],
"space-separated-tokens": ["space-separated-tokens@2.0.2", "", {}, ""],
@@ -869,7 +897,7 @@
"styled-jsx": ["styled-jsx@5.1.6", "", { "dependencies": { "client-only": "0.0.1" }, "peerDependencies": { "react": ">= 16.8.0 || 17.x.x || ^18.0.0-0 || ^19.0.0-0" } }, ""],
"tailwind-merge": ["tailwind-merge@3.6.0", "", {}, "sha512-uxL7qAVQriqRQPAyK3pj66VqskWqoZ37PW94jwOTwNfq/z9oyu1V+eqrZqtR2+fCiXdYOZe/Modt8GtvqNzu+w=="],
"tailwind-merge": ["tailwind-merge@3.7.0", "", {}, "sha512-XPPUyAc+cvspz3lHTcR/QgPfW2A0lv/xQNIjX3HGhLR+Nq2lHaLq5MtTesHn8GUr3W3DguT2KT5x3NVgRtYwmA=="],
"tailwindcss": ["tailwindcss@4.2.2", "", {}, ""],
@@ -877,7 +905,7 @@
"tiny-invariant": ["tiny-invariant@1.3.3", "", {}, ""],
"tinyexec": ["tinyexec@1.2.4", "", {}, "sha512-SHf/r48b7vOrjve9PxJo3MN5v5yuyjHvdUcrQffT3WXMUfnGmHDVbC4k3sHJaJTgZCwpUplIaAo5ANtMyp3YHg=="],
"tinyexec": ["tinyexec@1.3.1", "", {}, "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA=="],
"tinyglobby": ["tinyglobby@0.2.17", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.4" } }, "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g=="],
@@ -887,19 +915,13 @@
"ts-algebra": ["ts-algebra@2.0.0", "", {}, ""],
"ts-morph": ["ts-morph@28.0.0", "", { "dependencies": { "@ts-morph/common": "~0.29.0", "code-block-writer": "^13.0.3" } }, "sha512-Wp3tnZ2bzwxyTZMtgWVzXDfm7lB1Drz+y9DmmYH/L702PQhPyVrp3pkou3yIz4qjS14GY9kcpmLiOOMvl8oG1g=="],
"tslib": ["tslib@2.8.1", "", {}, ""],
"twoslash": ["twoslash@0.3.9", "", { "dependencies": { "@typescript/vfs": "^1.6.4", "twoslash-protocol": "0.3.9" }, "peerDependencies": { "typescript": "^5.5.0 || ^6.0.0" } }, "sha512-rDclk+OtzuTX+tnea7DYLCkqGQ3eP0IyfD+kzUJ7t46X/NzlaxwrhecmEBNuSCuEn3V+n1PhcjUUQQ7gUJzX5Q=="],
"twoslash-protocol": ["twoslash-protocol@0.3.9", "", {}, "sha512-9/iwp+CXOnjFMPQuPL5PkuRbZnDoNpBvtJCLs9t8kDYkL3YHujbvnHfZA1i5fApDftVEdBw+T/4F+dH5kIzpYQ=="],
"typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, ""],
"typescript": ["typescript@7.0.2", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="],
"undici": ["undici@7.29.0", "", {}, "sha512-IDxfleLmmbSskfWSUATiN1nfn2rDuvnMOqb5CWR92iIfojA0Ud+ulOAAEQ57LPr9rWmsreUyf5lwyao+7GNNVw=="],
"undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
"undici-types": ["undici-types@8.9.0", "", {}, "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg=="],
"unified": ["unified@11.0.5", "", { "dependencies": { "@types/unist": "^3.0.0", "bail": "^2.0.0", "devlop": "^1.0.0", "extend": "^3.0.0", "is-plain-obj": "^4.0.0", "trough": "^2.0.0", "vfile": "^6.0.0" } }, ""],
@@ -935,69 +957,39 @@
"wkt-parser": ["wkt-parser@1.5.5", "", {}, ""],
"yaml": ["yaml@2.9.0", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="],
"yaml": ["yaml@2.9.1", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw=="],
"yuku-analyzer": ["yuku-analyzer@0.6.12", "", { "dependencies": { "@yuku-toolchain/types": "0.6.11", "yuku-ast": "0.6.11" }, "optionalDependencies": { "@yuku-analyzer/binding-darwin-arm64": "0.6.12", "@yuku-analyzer/binding-darwin-x64": "0.6.12", "@yuku-analyzer/binding-freebsd-x64": "0.6.12", "@yuku-analyzer/binding-linux-arm-gnu": "0.6.12", "@yuku-analyzer/binding-linux-arm-musl": "0.6.12", "@yuku-analyzer/binding-linux-arm64-gnu": "0.6.12", "@yuku-analyzer/binding-linux-arm64-musl": "0.6.12", "@yuku-analyzer/binding-linux-x64-gnu": "0.6.12", "@yuku-analyzer/binding-linux-x64-musl": "0.6.12", "@yuku-analyzer/binding-win32-arm64": "0.6.12", "@yuku-analyzer/binding-win32-x64": "0.6.12" } }, "sha512-0zu/gwv6nKA3wm2GMjM1iczw9rbt77ijEyR5tXpPQ8AZcXIpXlll66BXOtMHgYudLn91bJx0ybhpARoJWm5/dw=="],
"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-ast": ["yuku-ast@0.6.11", "", { "dependencies": { "@yuku-toolchain/types": "0.6.8" } }, "sha512-ZfXkFYVsDewS45+kv3WiA/qNB73CRfxFDEQwfnRMUAR4AD5zRI7PRqxmI2U3Jz/oG41GneTVW6mxDOQal0lgeA=="],
"yuku-ast": ["yuku-ast@0.10.2", "", { "dependencies": { "@yuku-toolchain/types": "^0.10.2" } }, "sha512-UnG9mA6giglCvSErft2/40TVFX750Sj1xgwddPLpG7J7rlr/P1wPADg9G2RK+d/1tNLtRVoLdMMOMVBB9561TQ=="],
"zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
"zbsearch": ["zbsearch@4.0.1", "", {}, "sha512-lmnEEnb93QQcNv7qARDr7jBVPxYdZbZ9XdZ0dbZ0qaOvGne4jJMW4fjwPfVaUKQXv3FNWvGbDwRDgyaSb1pc8w=="],
"zod": ["zod@4.6.5", "", {}, "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q=="],
"zwitch": ["zwitch@2.0.4", "", {}, ""],
"@ai-sdk/gateway/@ai-sdk/provider": ["@ai-sdk/provider@4.0.7", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-6or44XprPzKbr8zkmzosowSE0pxkvJcoojBL+mCZvPUt3kvXp3XSNqeVun9golb1acEfSo6yaEBRT18h2VU+1Q=="],
"@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-utils": ["@ai-sdk/provider-utils@5.0.26", "", { "dependencies": { "@ai-sdk/provider": "4.0.7", "@standard-schema/spec": "^1.1.0", "@workflow/serde": "4.1.0", "eventsource-parser": "^3.0.8", "undici": "^7.28.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-0mqhqx+Dcv+msI84+zkbLXmnCHb/mpkYJ9DU3HBvB1px+UjFQss4lLZqRCSzJ0w3NxwQk4Ishk7cP0r8wEQD5w=="],
"@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=="],
"@radix-ui/react-accordion/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@base-ui/react/@babel/runtime": ["@babel/runtime@7.29.7", "", {}, "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw=="],
"@radix-ui/react-accordion/@radix-ui/react-direction": ["@radix-ui/react-direction@1.1.4", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-5pzg4FGQNpExhnhT2zlrP1wZFaYCd1K0nYWoFAdcYoYK868IEigqMX3B3f8yIoRlAhAeDWciLI6ZdCKHF9P4Vg=="],
"@base-ui/utils/@babel/runtime": ["@babel/runtime@7.29.7", "", {}, "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw=="],
"@radix-ui/react-collapsible/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@jridgewell/gen-mapping/@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "", {}, ""],
"@radix-ui/react-collection/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@jridgewell/trace-mapping/@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "", {}, ""],
"@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-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@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-dismissable-layer/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@radix-ui/react-focus-scope/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@radix-ui/react-navigation-menu/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@radix-ui/react-navigation-menu/@radix-ui/react-direction": ["@radix-ui/react-direction@1.1.4", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-5pzg4FGQNpExhnhT2zlrP1wZFaYCd1K0nYWoFAdcYoYK868IEigqMX3B3f8yIoRlAhAeDWciLI6ZdCKHF9P4Vg=="],
"@radix-ui/react-popover/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@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-popper/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@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=="],
"@radix-ui/react-roving-focus/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@radix-ui/react-roving-focus/@radix-ui/react-direction": ["@radix-ui/react-direction@1.1.4", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-5pzg4FGQNpExhnhT2zlrP1wZFaYCd1K0nYWoFAdcYoYK868IEigqMX3B3f8yIoRlAhAeDWciLI6ZdCKHF9P4Vg=="],
"@radix-ui/react-scroll-area/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"@radix-ui/react-scroll-area/@radix-ui/react-direction": ["@radix-ui/react-direction@1.1.4", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-5pzg4FGQNpExhnhT2zlrP1wZFaYCd1K0nYWoFAdcYoYK868IEigqMX3B3f8yIoRlAhAeDWciLI6ZdCKHF9P4Vg=="],
"@radix-ui/react-tabs/@radix-ui/react-direction": ["@radix-ui/react-direction@1.1.4", "", { "peerDependencies": { "@types/react": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" }, "optionalPeers": ["@types/react"] }, "sha512-5pzg4FGQNpExhnhT2zlrP1wZFaYCd1K0nYWoFAdcYoYK868IEigqMX3B3f8yIoRlAhAeDWciLI6ZdCKHF9P4Vg=="],
"@mdx-js/mdx/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"@reduxjs/toolkit/immer": ["immer@11.1.4", "", {}, ""],
"@reduxjs/toolkit/reselect": ["reselect@5.1.1", "", {}, ""],
"@shikijs/core/@types/hast": ["@types/hast@3.0.5", "", { "dependencies": { "@types/unist": "*" } }, "sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g=="],
"@tailwindcss/node/magic-string": ["magic-string@0.30.21", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.5" } }, ""],
"@shikijs/primitive/@types/hast": ["@types/hast@3.0.5", "", { "dependencies": { "@types/unist": "*" } }, "sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g=="],
"@shikijs/types/@types/hast": ["@types/hast@3.0.5", "", { "dependencies": { "@types/unist": "*" } }, "sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g=="],
"@tailwindcss/node/source-map-js": ["source-map-js@1.2.1", "", {}, ""],
"@tailwindcss/node/tailwindcss": ["tailwindcss@4.3.3", "", {}, "sha512-gOhV3P7ufE62QDGg1zVaTgCR+EtPv92k2nIhVcVKcLmxT1sUBsQGhnZj175j+MqRt4zLF7ic+sCYjfhxMxj7YQ=="],
@@ -1015,24 +1007,48 @@
"@tailwindcss/postcss/tailwindcss": ["tailwindcss@4.3.3", "", {}, "sha512-gOhV3P7ufE62QDGg1zVaTgCR+EtPv92k2nIhVcVKcLmxT1sUBsQGhnZj175j+MqRt4zLF7ic+sCYjfhxMxj7YQ=="],
"ai/@ai-sdk/provider": ["@ai-sdk/provider@4.0.7", "", { "dependencies": { "json-schema": "^0.4.0" } }, "sha512-6or44XprPzKbr8zkmzosowSE0pxkvJcoojBL+mCZvPUt3kvXp3XSNqeVun9golb1acEfSo6yaEBRT18h2VU+1Q=="],
"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-utils": ["@ai-sdk/provider-utils@5.0.26", "", { "dependencies": { "@ai-sdk/provider": "4.0.7", "@standard-schema/spec": "^1.1.0", "@workflow/serde": "4.1.0", "eventsource-parser": "^3.0.8", "undici": "^7.28.0" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-0mqhqx+Dcv+msI84+zkbLXmnCHb/mpkYJ9DU3HBvB1px+UjFQss4lLZqRCSzJ0w3NxwQk4Ishk7cP0r8wEQD5w=="],
"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/lucide-react": ["lucide-react@1.33.0", "", { "peerDependencies": { "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-MTRwMy0ZlL8Ur/vOAiJ9XGHE+kFPC7brq6MxAm0GiGXEBj0qy0jA/pG4N675oSzciO/UCdX8T+5yUQdmDeTLxg=="],
"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": "*" } }, ""],
"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": "*" } }, ""],
"mdast-util-mdx-expression/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"mdast-util-mdx-jsx/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"mdast-util-mdxjs-esm/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"mdast-util-to-hast/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, ""],
"shiki/@types/hast": ["@types/hast@3.0.5", "", { "dependencies": { "@types/unist": "*" } }, "sha512-rp/ezSWaD1m44dPKICGhiskI13nVr7qTloFwDa/IYkhhf5nzwP+zIQcIJh3WIFSBOy/H1PzB40jPjMDksN4F+g=="],
"rehype-raw/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"rehype-recma/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"remark-rehype/@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, ""],
"tinyglobby/picomatch": ["picomatch@4.0.4", "", {}, ""],
"yuku-ast/@yuku-toolchain/types": ["@yuku-toolchain/types@0.6.8", "", {}, "sha512-AbUd1775RVkOxJkh8hkldIWoU6kRMTCsZFSZq8Ny53q7GkbaVe5UCfleNZ3RWCoz/ZKE8qwfeB7Cj0xqhLWsKA=="],
"@ai-sdk/gateway/@ai-sdk/provider-utils/eventsource-parser": ["eventsource-parser@3.1.1", "", {}, "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ=="],
"@radix-ui/react-primitive/@radix-ui/react-slot/@radix-ui/react-compose-refs": ["@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-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA=="],
"ai/@ai-sdk/provider-utils/eventsource-parser": ["eventsource-parser@3.1.1", "", {}, "sha512-EKN1vKAMcZ8MlYMpaNuxN6R9yakzH6uajHcHVTqWJzvu5pWw9DyhbP35HH8MVBQ+dZjAfDxk+A8NiR9KWaXiyQ=="],
"@tailwindcss/node/magic-string/@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "", {}, ""],
}
}
+11
View File
@@ -72,6 +72,17 @@ Keep the stable prefix first, keep volatile content out of it, and treat CacheAl
CacheAligner surfaces prefix instability, provider caches reward byte-identical prefixes, and the caller owns the actual message layout.
Anthropic prefix trackers are retained for at least the resolved provider cache
lifetime plus a 60-second cleanup margin, or the configured session cleanup TTL,
whichever is longer. A configured cache lifetime also applies before the first
confirmed cache write and when a request omits its TTL. Retention is tracked per
conversation lineage: a one-hour session does not extend an unrelated
five-minute session. Expired trackers are discarded before lookup; a later
longer TTL cannot revive their frozen state. Cleanup and recreation retain the
live lineage index, keeping sibling conversations and tool profiles isolated.
Retaining a tracker is not a guarantee that the provider still has its cache.
## Cold-prefix recompaction (when the cache lapses)
Byte-identical forwarding only pays off while the prompt cache is warm. When a
+2
View File
@@ -480,6 +480,7 @@ Enable it with `HEADROOM_MODEL_ROUTER_ENABLED=1` and declare ordered rules in `H
| `to_model` | string (required) | Model to route to when the rule matches. |
| `max_input_tokens` | integer | Match only when the estimated input size is at or below this. |
| `min_input_tokens` | integer | Match only when the estimated input size is at or above this. |
| `max_output_tokens` | integer | Match only when the request's own `max_tokens` is at or below this. A request without `max_tokens` does not match. |
| `require_no_tools` | boolean | Match only when the request declares no tools (a proxy for low-risk work). |
| `from_models` | list of strings | Restrict the rule to these source models. Omit for any source model. |
| `name` | string | Label surfaced in the decision log. |
@@ -494,6 +495,7 @@ export HEADROOM_MODEL_ROUTES='[
Notes:
- Combine `max_input_tokens` with `max_output_tokens` to downshift only turns that are cheap on both sides: a tiny prompt that asks for a long answer (a large `max_tokens`) stays on the original model.
- Input size is a fast, tokenizer-free estimate over the messages, tools, and top-level `system` prompt, meant for tier selection rather than exact accounting.
- A malformed rule fails open: it is skipped (never silently widened), and the rest of the rules still apply.
- Routing is skipped for byte-faithful passthrough requests (`x-headroom-bypass: true` or `x-headroom-mode: passthrough`), so those are never model-rewritten.
@@ -35,10 +35,15 @@ The router auto-detects content type by analyzing structure and patterns. No man
| Diffs | Unified diff format | DiffCompressor | 60-80% (measured ~70% on a multi-file diff with default `max_context_lines`/`max_hunks_per_file` limits) |
| HTML | Tag structure | HTMLExtractor | 70-90% (module docstring; measured ~81% on a synthetic nav/ads/script-heavy page) |
| Tabular (CSV/TSV/markdown tables) | Delimited rows / table syntax | TabularCompressor | Varies with redundancy -- TabularCompressor bridges to SmartCrusher, so it inherits the same range (measured 26-28% on non-duplicate rows) |
| Human-readable Git status | Branch/detached-HEAD header plus status sections and entries | Lossless passthrough (Python and Rust) | None: staged, unstaged, and untracked paths must remain intact |
| Structured config (YAML/TOML/INI) | Config syntax | ConfigCompressor | 40-70% (measured ~50% on a commented/blank-line-heavy YAML file) |
| Plain text | Text with no stronger signal | Kompress | workload-dependent |
| Anything else | Fallback chain, then passthrough if no safe saving is found | Kompress / passthrough | varies |
Human-readable Git status is structured output, not prose: it is preserved byte-for-byte, including section labels and paths containing spaces. The router checks its structure before model classification and before selected external or lossy compressors, so CSV and wildcard plugins cannot trim status entries. This protection does not exclude all `Bash` results; ordinary prose and build logs still follow their normal routes. The recognizer covers the standard English status format (`LC_ALL=C`); localized formats are not covered.
This protection also takes precedence over mixed-content splitting when a recognized status is followed by fenced code or JSON. The combined tool result is preserved rather than splitting status entries into prose sections.
## Quick Start
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
+1
View File
@@ -6,6 +6,7 @@
"installation",
"docker-install",
"persistent-installs",
"teams",
"---Compression---",
"how-compression-works",
"smart-crusher",
+16 -10
View File
@@ -123,20 +123,22 @@ The default user scope only writes shell environment configuration. For OpenCode
## Native OpenCode Plugin
The `headroom-opencode` package exports `HeadroomPlugin` for direct OpenCode plugin registration. The plugin installs Headroom transport interception inside OpenCode, exposes the `headroom_retrieve` tool, and publishes Headroom metadata through the OpenCode plugin output env.
The `headroom-opencode` package's default export is a native OpenCode plugin that works with both OpenCode 1.x and 2.x. It installs Headroom transport interception inside OpenCode, exposes the `headroom_retrieve` tool, and adds Headroom metadata (`HEADROOM_ACTIVE`, `HEADROOM_PROXY_URL`, `HEADROOM_PROJECT`) to the environment of shell commands OpenCode runs.
Example:
Register it in `opencode.json`:
```ts
import { HeadroomPlugin } from "headroom-opencode";
export default async function plugin(input) {
return HeadroomPlugin(input, {
proxyUrl: process.env.HEADROOM_PROXY_URL ?? "http://127.0.0.1:8787",
});
```json
{
"plugin": [
["headroom-opencode", { "proxyUrl": "http://127.0.0.1:8787" }]
]
}
```
OpenCode 2.x migrates the 1.x `plugin` key automatically. To configure it the 2.x way, use `"plugins": [{ "package": "headroom-opencode", "options": { "proxyUrl": "http://127.0.0.1:8787" } }]`. Without `proxyUrl`, the plugin reads `HEADROOM_PROXY_URL` and falls back to `http://127.0.0.1:8787`.
The default export has `server` for OpenCode 1.x and `setup` for OpenCode 2.x. Each version ignores the other's field. `HeadroomPlugin` (1.x) and `headroomSetup` (2.x) are also exported by name for custom wrappers.
Use this plugin when OpenCode should intercept provider traffic in-process. Use `headroom wrap opencode` when you want the CLI to manage the proxy, config injection, MCP registration, backups, and unwrap behavior.
The plugin routes every external HTTP(S) request through the proxy. To keep a provider or gateway off the proxy while leaving the plugin loaded, pass `excludeHosts` in the plugin options or set `HEADROOM_OPENCODE_EXCLUDE_HOSTS` before launching OpenCode. An entry matches the host and all of its subdomains; excluded requests are sent as-is, with no compression or telemetry.
@@ -174,7 +176,7 @@ const retrieve = createHeadroomRetrieveTool({
1. **Config injection**. The wrapper writes a `provider.headroom` block into `opencode.json`. The provider uses `@ai-sdk/openai-compatible`, which OpenCode supports natively. Model mappings route requests through `http://127.0.0.1:<port>/v1`.
2. **Runtime config**. `OPENCODE_CONFIG_CONTENT` is set as an env var containing provider, plugin, and optional local MCP JSON. OpenCode reads it at startup and merges it with on-disk config.
3. **MCP tools**. Headroom registers `headroom_compress`, `headroom_retrieve`, and `headroom_stats` through `headroom mcp serve` unless `--no-mcp` is set.
4. **Native plugin path**. `HeadroomPlugin` installs Headroom transport interception and uses `HEADROOM_PROXY_URL` or `http://127.0.0.1:8787` to reach the proxy.
4. **Native plugin path**. `wrap` loads the transport plugin from a local directory (`plugins/opencode/dist/` in a checkout, `headroom/providers/opencode/_dist/` in the wheel), because OpenCode 2.x only accepts local plugins as directories. The plugin uses `HEADROOM_PROXY_URL` or `http://127.0.0.1:8787` to reach the proxy.
5. **Unwrap**. `headroom unwrap opencode` restores `opencode.json` from the pre-wrap backup when present, strips Headroom marker blocks when no backup exists, and unregisters Headroom MCP servers.
## Troubleshooting
@@ -183,6 +185,10 @@ const retrieve = createHeadroomRetrieveTool({
Check that `OPENCODE_CONFIG_CONTENT` is set and contains the `provider.headroom` block. The wrap command prints the env vars it sets.
**OpenCode 2.x traffic does not show up in Headroom.**
OpenCode 2.x connects to a shared background service by default. A service that was already running when you wrapped never sees Headroom's config. `headroom wrap opencode` adds `--standalone` on 2.x so OpenCode runs a private server with that config instead. If you pass `--server <url>`, that server must be started with Headroom's config too. Check what OpenCode actually loaded with `opencode api plugin.list --param directory="$PWD"`, which should list `headroom`.
**The native plugin cannot reach Headroom.**
Set `HEADROOM_PROXY_URL` to the running proxy URL, for example `http://127.0.0.1:8787`.
+31
View File
@@ -122,6 +122,37 @@ Provider scope is intentionally conservative. The current direct adapters are:
- OpenClaw → existing `wrap openclaw` / `unwrap openclaw` flow
- OpenCode → managed block in `~/.config/opencode/opencode.json`
For OpenCode provider scope, reapplying the deployment, restarting it, or
recovering a stopped proxy removes and reinjects only the managed `headroom`
provider. Later edits to themes, other providers, and MCP configuration stay
intact. JSONC input may contain comments and trailing commas.
Active configuration is serialized as JSON; original formatting and comments
are preserved in the snapshot. The original `<config filename>.headroom-backup`
is kept across these transitions for both `.json` and `.jsonc` configurations.
Final `headroom install remove` restores that original snapshot and deletes the
backup, including after a stop and manifest reload.
Existing JSONC snapshots using the older `<name>.json.headroom-backup` filename
are migrated only when the canonical backup is absent. When a sibling `.json`
config or a canonical snapshot already exists, Headroom preserves the ambiguous
legacy backup in place and creates a `<name>.json.headroom-backup.jsonc-migration-blocked`
marker. This marker survives removal and prevents later installs from claiming
the legacy backup, even after the conflicting config or snapshot disappears.
The legacy bytes remain available for manual recovery; copy them to the intended
config only after inspecting them. Keep the marker to prevent automatic migration.
If the marker cannot be created, the operation fails before changing the config
or consuming its canonical snapshot.
Backup ownership follows the config path recorded in the deployment, not a
later `OPENCODE_CONFIG` value. A successful replacement restores snapshots for
retired config paths and transfers any pending restoration to the new manifest.
If restoration fails, the replacement remains active; resolve the filesystem
error and retry `headroom install apply` to complete it.
Failed replacement cleanup consumes snapshots newly created by that attempt,
but preserves snapshots owned by the previous deployment for recovery.
For Copilot, Aider, Cursor, and broader env-driven setups, prefer `--scope user` or `--scope system`.
## Provider selection
+42 -4
View File
@@ -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 `--offline` (which also disables update checks and license reporting).
Disable it with `HEADROOM_BEACON=off`, the `DO_NOT_TRACK=1` convention, or `HEADROOM_OFFLINE=1` (which also disables update checks and license reporting).
## CLI options
@@ -328,7 +328,7 @@ Coding agents re-read the same files repeatedly; these control how stale reads a
| Flag / env | Default | Effect |
|---|---|---|
| `--no-read-lifecycle` | lifecycle on | Stop replacing stale/superseded file reads with CCR markers. |
| `--read-maturation` / `HEADROOM_READ_MATURATION` | `false` | *(Beta)* Hold freshly-read files out of the prefix cache until the file quiesces. Requires `HEADROOM_ROLLOUT_CHANNEL=beta` (or `dev`). |
| `--read-maturation` / `HEADROOM_READ_MATURATION` | `false` | *(Beta)* Keep freshly-read files verbatim while in use, then compress them once the file quiesces, unless the provider cache already holds them. Requires `HEADROOM_ROLLOUT_CHANNEL=beta` (or `dev`). |
| `--read-maturation-quiesce-turns` | `5` | Turns of no change before a held read is admitted. |
### Reliability: timeouts, retries, limits
@@ -401,7 +401,7 @@ with a privileged job.
| `HEADROOM_PROXY_TOKEN` | none | Require a token from non-loopback callers, as `X-Headroom-Proxy-Token: <token>` or `Authorization: Bearer <token>`. The token is removed from the request before it is forwarded upstream; clients that also send a provider credential should use `X-Headroom-Proxy-Token` and keep `Authorization` for the provider. Also gates the read-only operator routes (`/stats-history`, `/quota`, `/subscription-window`, `/metrics`), which otherwise answer loopback and trusted-CIDR callers only. |
| `HEADROOM_ALLOW_UNAUTHENTICATED_BIND` | `false` | Acknowledge a non-loopback bind (`--host 0.0.0.0`, `::`, a LAN address) with **no** `HEADROOM_PROXY_TOKEN`. Without a token or this flag the proxy refuses to start, because `/v1/*` would relay upstream with the operator's credentials for every peer that can reach the port. Only set it when the runtime already restricts reachability (a container published on `127.0.0.1`). |
| `HEADROOM_COMPRESS_ALLOW_REMOTE` | `false` | Allow non-loopback callers to reach [`POST /v1/compress`](#post-v1compress) and `POST /v1/usage`. Required to run Headroom as a remote gateway/sidecar; without it remote callers get `404`. |
| `--offline` / `HEADROOM_OFFLINE` | `false` | Air-gap mode: refuse every connection Headroom itself initiates — telemetry, update checks, license reporting, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP and Langfuse export, Copilot auth, the subscription pollers, the OpenAI embedders, Headroom Cloud compression and the TLS diagnostics (`headroom doctor --network` reports them as skipped). Four things still work on purpose: forwarding your own requests to the upstream you configured, operator-configured local endpoints (the Ollama embedder), loopback health probes, and paths an `is_offline()` check already disables. Refusals surface as messages, not tracebacks. See the air-gap notes in `docs/metrics-technical-guide.md`. |
| `HEADROOM_OFFLINE` | `false` | Air-gap mode: refuse every connection Headroom itself initiates — telemetry, update checks, license reporting, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP and Langfuse export, Copilot auth, the subscription pollers, the OpenAI embedders, Headroom Cloud compression and the TLS diagnostics (`headroom doctor --network` reports them as skipped). Four things still work on purpose: forwarding your own requests to the upstream you configured, operator-configured local endpoints (the Ollama embedder), loopback health probes, and paths an `is_offline()` check already disables. Refusals surface as messages, not tracebacks. See the air-gap notes in `docs/metrics-technical-guide.md`. |
| `HEADROOM_LICENSE` | unset | Licence token, read by core and every licensed extension. `HEADROOM_LICENSE_KEY` is a deprecated alias for one release and logs a warning. A licence on its own sends nothing to Headroom. |
| `HEADROOM_USAGE_REPORTING` | `false` | Set `1` to let the proxy validate the licence and post aggregate usage counts (no content) to the Headroom cloud. Off unless set; `HEADROOM_OFFLINE` still overrides it. |
| `--stateless` / `HEADROOM_STATELESS` | `false` | Keep all state in memory; no filesystem writes (disables logs, memory, TOIN). |
@@ -519,6 +519,26 @@ Google Cloud Code Assist / Antigravity compatibility endpoint used by Pi-style `
The proxy also accepts:
- `POST /v1/v1internal:streamGenerateContent`
### Antigravity IDE
Google's Antigravity IDE can route its model traffic through the proxy:
```bash
headroom wrap antigravity # Start proxy + print Antigravity setup instructions
headroom mcp install --agent antigravity # Register the Headroom MCP server in Antigravity
```
`wrap antigravity` prints a custom OpenAI-compatible model-provider base URL
to add in Antigravity's model-provider settings; Antigravity fetches the model
list from `GET /v1/models` on its own. Native Cloud Code Assist traffic
(`google-antigravity` clients) is accepted on
[`POST /v1internal:streamGenerateContent`](#post-v1internalstreamgeneratecontent)
and routed upstream like any other Cloud Code request.
MCP registration writes to Antigravity's global `mcp_config.json` under
`~/.gemini/` (preferring the install's current location when one already
exists) and refuses to overwrite a config file that does not parse as JSON.
### `POST /v1/compress`
Compression-only endpoint. Compresses messages and returns them without ever making a **completion request to an LLM provider** — no generation, no provider API key, no upstream chat call. Used by the TypeScript SDK, by LiteLLM's `headroom` guardrail, and by API gateways running Headroom as a sidecar.
@@ -866,6 +886,18 @@ headroom wrap cursor
headroom wrap grok-build
```
Wrapping can reuse an existing proxy instead of starting a new process. Its
startup-only settings do not change when you export different values in the
calling shell. `wrap` warns when an explicit `HEADROOM_MODE`,
`HEADROOM_MIN_TOKENS`, or `HEADROOM_EXCLUDE_TOOLS` disagrees with the settings
reported by that proxy. It does not restart a shared proxy or interrupt other
clients. Restart the proxy with the desired settings, or use `--port` to start
a separate instance. Tool exclusions are compared case-insensitively using the
effective router exclusions, including built-ins and tools protected by
`HEADROOM_PROTECT_TOOL_RESULTS`. Older proxies that do not report a setting
cannot be compared for that setting.
`headroom wrap codex` keeps routing scoped to the Codex process it launches: it
passes the proxy URL as a `--config` override and never writes it to
`~/.codex/config.toml`. Codex runs any session started with command-line
@@ -880,7 +912,13 @@ headroom init -g codex # ~/.codex/config.toml, for every project
```
That routing is persistent: it applies to every Codex session in that scope
until you remove it.
until you remove it. `headroom unwrap codex` removes the `-g` routing; for a
project, delete the `# --- Headroom init provider ---` block from
`.codex/config.toml`. Unwrap removes only the routing: the Headroom
`SessionStart` hook that `init` adds to Codex's `hooks.json` stays, and still
starts a proxy when a Codex session begins until you delete it. On Windows,
nothing starts the proxy for this routing, so Codex cannot connect while the
proxy is down; use `headroom install apply` if you need a supervised proxy.
Cursor reads model endpoints from its settings UI, so `headroom wrap cursor`
does not rewrite Cursor configuration or launch the app. After it starts the
+27
View File
@@ -0,0 +1,27 @@
---
title: Headroom for Teams
description: Headroom Enterprise for engineering teams — more savings, automatic model routing, attack removal, SSO and an org-wide savings dashboard. 3 months free with a 12-month plan.
---
Headroom OSS is built for one developer on one laptop. Headroom Enterprise is built
for the whole team.
| | Open source | Enterprise |
|---|---|---|
| Savings | Compression, plus tool search on Anthropic requests (on by default) | Also: tool search for every model, harness tuning, extra compressors |
| Model routing | Rule-based and opt-in: turn it on with `HEADROOM_MODEL_ROUTER_ENABLED=1` and write the rules in [`HEADROOM_MODEL_ROUTES`](/docs/configuration#cost-aware-model-routing) | Automatic: a cheaper model per request when quality allows, with a shadow mode that shows the savings before you turn it on |
| Security | — | Detect and strip prompt injection and risky tool calls |
| Rollout | Per laptop | Managed or in your VPC, SSO, central config, org-wide savings |
| Support | GitHub, Discord | Dedicated engineers, onboarding, priority response |
## 3 months free
Companies that sign a 12-month Enterprise plan get their first 3 months free. One
perk per company.
**[Claim 3 months free →](https://headroom-perks.vercel.app/?source=github&utm_source=docs&utm_medium=teams-page)**
Prefer to talk first? Email [hello@headroomlabs.ai](mailto:hello@headroomlabs.ai)
with your stack and rough monthly LLM spend.
Everything in the open-source repo stays open source under Apache 2.0.
+7
View File
@@ -6,5 +6,12 @@ export function baseOptions(): BaseLayoutProps {
title: 'Headroom',
},
githubUrl: 'https://github.com/headroomlabs-ai/headroom',
links: [
{
text: 'Headroom for Teams',
url: '/docs/teams',
active: 'nested-url',
},
],
};
}
+118 -118
View File
@@ -724,9 +724,9 @@
}
},
"node_modules/@img/sharp-darwin-arm64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.4.tgz",
"integrity": "sha512-Uhfl4V4lhP2nbUVF9+hyH1+luj86f1gUFeo8ALYxFoULoU+G87D43BfeMP8XHsk9boxAnCY/bf2EHwhA7MuGsA==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.5.tgz",
"integrity": "sha512-QRUlFQ0WxvdWyqqG/WtI3iupfD5rBzmCHXSdPsY91sAtVtTo7Q4cb6zOccZ3gqEqkr0f1As1ehLqmEpDsRf+lg==",
"cpu": [
"arm64"
],
@@ -742,13 +742,13 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-darwin-arm64": "1.3.3"
"@img/sharp-libvips-darwin-arm64": "1.3.4"
}
},
"node_modules/@img/sharp-darwin-x64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.4.tgz",
"integrity": "sha512-hWniXY3bG5qKpkKrAwPe4y+VTPmf086YQAnkxWh7uA1YrlRouWGa0M0Mxj3ZjnXFkv7/TD1bTy9lGUK26vRvWw==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.5.tgz",
"integrity": "sha512-+BR255RhDlpygUpOc/Jdt1nT6DQ3XG/ERo5wbcdOf5Q320dKtPCKPLR1LJs9VGXRaMa8l1uUa0tkCNOXiAxZUw==",
"cpu": [
"x64"
],
@@ -764,20 +764,20 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-darwin-x64": "1.3.3"
"@img/sharp-libvips-darwin-x64": "1.3.4"
}
},
"node_modules/@img/sharp-freebsd-wasm32": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.4.tgz",
"integrity": "sha512-lIsKw/BU+kjB4eZjxrYrZmwOJYi3Ajrv66iAlBmUPyKc3HpnloevB1g3wxGD9P/5BbQ1brBGl65VRRrCvQDEqA==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.5.tgz",
"integrity": "sha512-Y/z91nEZ4uIBX5X3nfTovjU9lHNKFYbL2lpHCLVNmXQK03VIZvXBBt0KxbPGp2SdGSF+2mQU4e+hQaWOt86iAw==",
"license": "Apache-2.0",
"optional": true,
"os": [
"freebsd"
],
"dependencies": {
"@img/sharp-wasm32": "0.35.4"
"@img/sharp-wasm32": "0.35.5"
},
"engines": {
"node": ">=20.9.0"
@@ -787,9 +787,9 @@
}
},
"node_modules/@img/sharp-libvips-darwin-arm64": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.3.tgz",
"integrity": "sha512-suTBPTDGrI9WodccaDdwZItTSaBYASlBk1NSfElSHrUfzu3szG6lvIF58+WiFvnfzuK8ZBFS5zE00PxqxnRiPg==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.4.tgz",
"integrity": "sha512-5R89nBYiRdUlSWJxPhO+GVtaXzXSxKnRu/xqMn3KTA3L9EB9Oy/P+Nn2f2vlhPuUdy/Zusb2DarbyTpGCfEDuw==",
"cpu": [
"arm64"
],
@@ -803,9 +803,9 @@
}
},
"node_modules/@img/sharp-libvips-darwin-x64": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.3.tgz",
"integrity": "sha512-FVJZ5mITMobmXIz/hPDTw0EintTW5H3WfrxwLqEqjiIihlu+hVRyGrFQ60xl0Lxn7Bt3zdpevPaQi0HEzqz9fw==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.4.tgz",
"integrity": "sha512-iR2OKH80yi0U+dUplyh3/xdpFvps6YkCwsXenIJxqxR1v9o+xtKTGbS9H7cps+2Vxjc8B1j96p75NmTGjIhtpQ==",
"cpu": [
"x64"
],
@@ -819,9 +819,9 @@
}
},
"node_modules/@img/sharp-libvips-linux-arm": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.3.tgz",
"integrity": "sha512-3rbU4vqXXc3hY/OiXdl52xZvT0F1yEngWfvqudtPJg/KkyiaQw2DRsFrNzpmLvfavbwOq3qXn36GP8obHRULQA==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.4.tgz",
"integrity": "sha512-LmRtTsOHuvM2+wlO2Db37dx5MiZhB0FvSunciw48YjdOkZz9KAiRbm8ujeMOA1INqmei5NapFxYEK1D1ZSidmw==",
"cpu": [
"arm"
],
@@ -838,9 +838,9 @@
}
},
"node_modules/@img/sharp-libvips-linux-arm64": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.3.tgz",
"integrity": "sha512-0DaL0A6Xu6sQSQFwe4iVCrKWU2cCTItnRsYsCdxAMm9NF6twAA9BKnoqy4hqz4+azQ0JHuA26qiUKsf1XJ/v5A==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.4.tgz",
"integrity": "sha512-Y3dgX/6lE2QhQb+Gxy0WZxfg9MEm/JBjamZpS2IklP7xIQoKN4hzAm7KcMVGtaVDt3neE9OKBC7vAfonA/Lr1A==",
"cpu": [
"arm64"
],
@@ -857,9 +857,9 @@
}
},
"node_modules/@img/sharp-libvips-linux-ppc64": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.3.tgz",
"integrity": "sha512-cdn1OvUBwsXhbC0zSzJnNzf5MZ/mTrobawDvNXBTxe8VtqKAm0sRuEY2Evzovb/w9JMk4TvRxqt1mekSuJz64w==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.4.tgz",
"integrity": "sha512-Le6boB8Tai0Nis+gIxIpKx68UDVVIqdR8Tin5Yf1z2LJJQLDJvCDRqRu+jC2qCoD+eIomonmOwB4smBRxfVpYQ==",
"cpu": [
"ppc64"
],
@@ -876,9 +876,9 @@
}
},
"node_modules/@img/sharp-libvips-linux-riscv64": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.3.tgz",
"integrity": "sha512-HjPVx7yKz+0lqdhDlTw1tt90wamBoxhiXpvl1XZpJLiHH4RCJ5yDTqH+VlYPv2fwFs89JFw4c1IexYOcQUi4IQ==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.4.tgz",
"integrity": "sha512-aHkkIEHPRdQEegJN20MLmGtxYD9R2wQr3Cwpddnu5+YKMt6Uzax7S9h5gpZTo8wyrGuZSlfQ63OevL5mTyOC7Q==",
"cpu": [
"riscv64"
],
@@ -895,9 +895,9 @@
}
},
"node_modules/@img/sharp-libvips-linux-s390x": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.3.tgz",
"integrity": "sha512-neWLh+3yCNThxnfy3c4BbVBeGgt9aftno+XbT56iK28RgeDs3UOFWviLWlUu0bArYVYJaFDK+RRohbicUNCm8Q==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.4.tgz",
"integrity": "sha512-ra/mB6MikESDUO7Yg+Mi95bFBb9GsObURuhnOv3OqknjGe9sZrG8tCe9q0xSIGrtLgvgw0gKnFWcK4blSgQOuQ==",
"cpu": [
"s390x"
],
@@ -914,9 +914,9 @@
}
},
"node_modules/@img/sharp-libvips-linux-x64": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.3.tgz",
"integrity": "sha512-4vKmvAst9nrowcqquKFAyZJUDolUaIp8uRiN0mWFguJ1IplC9/pitXtlnnlU4aa/eJw3J7i67V+pwUL+wZGdsA==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.4.tgz",
"integrity": "sha512-GJ//SSXbnwSDes02umB3nDJLFcQzw8a18V8fyhqr6tV515tOEMdImjjxj1AoafMRz56F3PHgftnj1QEKSU1zkw==",
"cpu": [
"x64"
],
@@ -933,9 +933,9 @@
}
},
"node_modules/@img/sharp-libvips-linuxmusl-arm64": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.3.tgz",
"integrity": "sha512-Y9kQaLMuNoB0bPYOOdcZMaseNrFpPodIWWMrx+CZyydf2xn68j9WYc6sWWRrDwNkzCQjKYfc68L7jKjGlHMibw==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.4.tgz",
"integrity": "sha512-hvulFwtjUcagsis6BBxHwGFwWoNZjgYmULGVrZcyfNbjA8hKILbRxGg15/7w5HDyXHXUos/j6baAWqnCyQ2DWA==",
"cpu": [
"arm64"
],
@@ -952,9 +952,9 @@
}
},
"node_modules/@img/sharp-libvips-linuxmusl-x64": {
"version": "1.3.3",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.3.tgz",
"integrity": "sha512-fj8Mv0HHfD1Rr+4I68+3agJynxDWtBFgicTbSOb9Bke6pIwzGcJ+RX/yHjmiEGFMCavY/dxvem7MyNaJF+wDiw==",
"version": "1.3.4",
"resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.4.tgz",
"integrity": "sha512-6zXKeE/p39I1AmA3cJG35eyBGNqNddLnUXjhwBnsGjFPWqf5VKkDBEqaEkPDoTEtkxwi2vv8Tcr2mDyP4So7Fg==",
"cpu": [
"x64"
],
@@ -971,9 +971,9 @@
}
},
"node_modules/@img/sharp-linux-arm": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.4.tgz",
"integrity": "sha512-7OAS8gI0EReKGVN2HssHlM6umJgxF5VI3xN0p9FA91p/YO+ou5hiNghLdZ5BEHztwaaK5+bLKRf8x/o2L2nk9A==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.5.tgz",
"integrity": "sha512-LEaXK2WdXVK5ykcw0buWyPMsmLLL2vpHLD6yrNSW+JGEL3BZPA4tpKN6iaMc4AxTTAoaX/sU1rOL51lcIz48ZQ==",
"cpu": [
"arm"
],
@@ -992,13 +992,13 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-linux-arm": "1.3.3"
"@img/sharp-libvips-linux-arm": "1.3.4"
}
},
"node_modules/@img/sharp-linux-arm64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.4.tgz",
"integrity": "sha512-De4jpEnAU8Hd5oT0j1G3uL4ZvTuipVMn7YC6vPaJhy6/7EwEae0SVAoBrUMYQbkLGDm85taVWwuPc1a44LTzCQ==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.5.tgz",
"integrity": "sha512-LYVx5JTsOM2CBzmxreh+nl64/3H6Xb09iSLknqH47z2T2DFFxDeFLP5y4dJwe6H7uGQlHPyEEtIqyo3DYsRwdQ==",
"cpu": [
"arm64"
],
@@ -1017,13 +1017,13 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-linux-arm64": "1.3.3"
"@img/sharp-libvips-linux-arm64": "1.3.4"
}
},
"node_modules/@img/sharp-linux-ppc64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.4.tgz",
"integrity": "sha512-2oYZJeIl4kCcMGk4ouZVjnkCtFrpQFlNEtJ6GbxzhHQchwH0NH/qEb9ykmOl29dqwMq+JhFdZn+1ak2FKhI9fQ==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.5.tgz",
"integrity": "sha512-QVxAAq8evVRI9ia2vqgwrmWucn5Dfv+JdWzj75pD8omHLPSP7f8p20O8jxzjCcuCEQEOtYOZUmX1hkiZ0kdevA==",
"cpu": [
"ppc64"
],
@@ -1042,13 +1042,13 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-linux-ppc64": "1.3.3"
"@img/sharp-libvips-linux-ppc64": "1.3.4"
}
},
"node_modules/@img/sharp-linux-riscv64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.4.tgz",
"integrity": "sha512-cPbNChoRURAWdebDIHSenxRpgEdy7JkPydSnUxRm9VvKD7m0/xVaR/8Fzlu81pk5nHEvHH87UZUA7cTtwnbJSA==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.5.tgz",
"integrity": "sha512-LtdreXguaavKODPIfzJ4kffx7UNt1omwtK0rch4EBbbSTXPnxWmYSayXdLJw0fJzQ97kHt1gL/yh4tvU+nCyRQ==",
"cpu": [
"riscv64"
],
@@ -1067,13 +1067,13 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-linux-riscv64": "1.3.3"
"@img/sharp-libvips-linux-riscv64": "1.3.4"
}
},
"node_modules/@img/sharp-linux-s390x": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.4.tgz",
"integrity": "sha512-RY0JFY8Fd6RonCBtHz+DvadaPkXDSI1AUn6yWL9TipqkZ1vY8w8evqdgyDFnkm4/K1ve1TvZiaePP5oSd4+WVQ==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.5.tgz",
"integrity": "sha512-UZasTOFiYzotTsGOCu42BfUzP6Tu6Do/947iRm1RsLKvlllxwGcn4RN27LibGWceix4Y+Pmw3jsnTcCQIgWjqA==",
"cpu": [
"s390x"
],
@@ -1092,13 +1092,13 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-linux-s390x": "1.3.3"
"@img/sharp-libvips-linux-s390x": "1.3.4"
}
},
"node_modules/@img/sharp-linux-x64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.4.tgz",
"integrity": "sha512-9qvvEAuk8k89TfWUoX2htWjbAMX8p+NxCppjpcg5k6xMsjhBQPTsoIh36h9Qde4WRuGpJeYnOjdosDn/cnv+OA==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.5.tgz",
"integrity": "sha512-SxFtLTeJInhAA9Q836kux2vZNeOBQEx658qvbboZScr0wIARym3IcGmW7KpVD5sbVg0Ojy+udFQdayYIZyoNog==",
"cpu": [
"x64"
],
@@ -1117,13 +1117,13 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-linux-x64": "1.3.3"
"@img/sharp-libvips-linux-x64": "1.3.4"
}
},
"node_modules/@img/sharp-linuxmusl-arm64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.4.tgz",
"integrity": "sha512-KB5jxpfWQTr0nc3xdHtWChdbifHrBGsd2SM62Eyxrl8afikm+f5qGBU75SJIZBT/S1MC8XyacdlXBMSWq6OURA==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.5.tgz",
"integrity": "sha512-9HbMclmI1zlNkFRs3z9/eBtDjfD0sGlrX1z6b1qwmiFY5ElDLh4BC0LPBdVp7z1DXFiKlIcznf+ZlsuZzLxQqg==",
"cpu": [
"arm64"
],
@@ -1142,13 +1142,13 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-linuxmusl-arm64": "1.3.3"
"@img/sharp-libvips-linuxmusl-arm64": "1.3.4"
}
},
"node_modules/@img/sharp-linuxmusl-x64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.4.tgz",
"integrity": "sha512-f+eZJZIQNEEd26RPSW+76chwOf1XtA2Y/O+5ocVyLliHkeih3e+jhLVBdNTd2rS3IbNXK8+ug93Vf5ZXtF5Lxg==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.5.tgz",
"integrity": "sha512-4KOphqB035HrVdqLZfCgMzzERrQkkzOwRhl4OAkRO1YCldbaFjySXMaK534Mo0V+LndnlJk+sbUyLeU0ULyD1A==",
"cpu": [
"x64"
],
@@ -1167,13 +1167,13 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-libvips-linuxmusl-x64": "1.3.3"
"@img/sharp-libvips-linuxmusl-x64": "1.3.4"
}
},
"node_modules/@img/sharp-wasm32": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.4.tgz",
"integrity": "sha512-zQnl4Kwp7Q6NHsENtU2T/00Zi+w3AQNwz3+UaTyVBy2FpXrzXzGjndpK61onhZjRtRpQXxCTeqw19bVyXOh7jA==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.5.tgz",
"integrity": "sha512-Ptsga1su4tQx+LLF1ECS9U6nz5kmrXKo6XVbtR48Ke3ZRxxgaWBu7IDtEe1quo8hiupwm6WFqxVlXaSf7IINGQ==",
"license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
"optional": true,
"dependencies": {
@@ -1187,16 +1187,16 @@
}
},
"node_modules/@img/sharp-webcontainers-wasm32": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.4.tgz",
"integrity": "sha512-ESfNkywmCfPNyaZjxooddJQiQ+l/nTpGEOGthxiLnIHXC/CmcBixnfwUleX9mCz9ovrUUvKMap/pm8RYbzfwaA==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.5.tgz",
"integrity": "sha512-hfhF/FmoQyTUkA0bIKFOtw536BQSeBMe6BF6QyWlrPxT754+TFLaZ7sKKTfvvM0yJgKgaYTwnFCIZ/GuDw5SUA==",
"cpu": [
"wasm32"
],
"license": "Apache-2.0",
"optional": true,
"dependencies": {
"@img/sharp-wasm32": "0.35.4"
"@img/sharp-wasm32": "0.35.5"
},
"engines": {
"node": ">=20.9.0"
@@ -1206,9 +1206,9 @@
}
},
"node_modules/@img/sharp-win32-arm64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.4.tgz",
"integrity": "sha512-iNdlBX9gLVvqe2I3uIJSIKTq6wckP/DYxZtcqxm09x5Gi24DnFBmPAWZmr60ZyYMG0xlzo6goG3670ar+RXvRw==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.5.tgz",
"integrity": "sha512-X4t7g+7ZA5DKblCBEXGjUqqemj4vczING/5viFwAL8h4N3qYeyjwdCvRLHi4EdOUI+2Z7UFlp1VM+p/AuEtm6Q==",
"cpu": [
"arm64"
],
@@ -1225,9 +1225,9 @@
}
},
"node_modules/@img/sharp-win32-ia32": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.4.tgz",
"integrity": "sha512-kqRsbaa5CS6KHlpxnN7WhE6vAAugXyZButpRdvDWetlv6Qv4N9WTcrWzF7tXfB9T7MsoadqdI8hmwLq6UlLvtw==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.5.tgz",
"integrity": "sha512-5Zm82LoBc43nhwNybZlG7Y1KO//Zhsn306fQl29ZOuStHLGTo3BWL83q3cznX0poxSAMuYL1On/BHBxkBeKr6A==",
"cpu": [
"ia32"
],
@@ -1244,9 +1244,9 @@
}
},
"node_modules/@img/sharp-win32-x64": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.4.tgz",
"integrity": "sha512-XtmnYhBcrORsJ4XJngyzr/EWP0hRZLAZRFaApdKuviyqF78+ylxh2y06ZmtULAMOnObJ3ucpN0AcwSWnMowTRg==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.5.tgz",
"integrity": "sha512-x76eH0vEiHlcMQu8Y8IenntaACtddpT6W0wmXtWrnKcnKI7ME5DdgqhAD6SEWOEl1v2zDvkZDhFA9KnURwpfqg==",
"cpu": [
"x64"
],
@@ -6594,9 +6594,9 @@
}
},
"node_modules/sharp": {
"version": "0.35.4",
"resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.4.tgz",
"integrity": "sha512-n++8XWcj+jCOr2IOl7h8LbKnGBDY4aPbmprMONBNFdn0ImXqpGVv5zliDs0V9HbmbCQLpbuo2ej9rAoOQTvMDA==",
"version": "0.35.5",
"resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.5.tgz",
"integrity": "sha512-Ywn4OnzGukp7CDMrp08RQ50YKmuwG47brZgIVPTvBaaAfQlRlygrRqSrxdCiL9M+LlzLBiJ68IR1QqvzHyjC7g==",
"license": "Apache-2.0",
"optional": true,
"dependencies": {
@@ -6611,31 +6611,31 @@
"url": "https://opencollective.com/libvips"
},
"optionalDependencies": {
"@img/sharp-darwin-arm64": "0.35.4",
"@img/sharp-darwin-x64": "0.35.4",
"@img/sharp-freebsd-wasm32": "0.35.4",
"@img/sharp-libvips-darwin-arm64": "1.3.3",
"@img/sharp-libvips-darwin-x64": "1.3.3",
"@img/sharp-libvips-linux-arm": "1.3.3",
"@img/sharp-libvips-linux-arm64": "1.3.3",
"@img/sharp-libvips-linux-ppc64": "1.3.3",
"@img/sharp-libvips-linux-riscv64": "1.3.3",
"@img/sharp-libvips-linux-s390x": "1.3.3",
"@img/sharp-libvips-linux-x64": "1.3.3",
"@img/sharp-libvips-linuxmusl-arm64": "1.3.3",
"@img/sharp-libvips-linuxmusl-x64": "1.3.3",
"@img/sharp-linux-arm": "0.35.4",
"@img/sharp-linux-arm64": "0.35.4",
"@img/sharp-linux-ppc64": "0.35.4",
"@img/sharp-linux-riscv64": "0.35.4",
"@img/sharp-linux-s390x": "0.35.4",
"@img/sharp-linux-x64": "0.35.4",
"@img/sharp-linuxmusl-arm64": "0.35.4",
"@img/sharp-linuxmusl-x64": "0.35.4",
"@img/sharp-webcontainers-wasm32": "0.35.4",
"@img/sharp-win32-arm64": "0.35.4",
"@img/sharp-win32-ia32": "0.35.4",
"@img/sharp-win32-x64": "0.35.4"
"@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"
},
"peerDependenciesMeta": {
"@types/node": {
+3 -3
View File
@@ -614,9 +614,9 @@
}
},
"node_modules/@modelcontextprotocol/sdk": {
"version": "1.30.0",
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.30.0.tgz",
"integrity": "sha512-xKd8OIzlqNzcqcNumGAa6g+PW2kjD5vrpcKOnfldAUPP3j7lnqMPwlTXQm8gF+UwH72z0lqaRbjr9hqGz0eITA==",
"version": "1.32.1",
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.32.1.tgz",
"integrity": "sha512-2DdE+SJDtzLEEWzY1ZjY7Q+VcPhcV1KisD3zI4u0XZyktsjHum1mwbMI+JaulUBi2OZk+KJAi2uPXzxichPkdw==",
"license": "MIT",
"dependencies": {
"@hono/node-server": "^1.19.9 || ^2.0.5",
+3
View File
@@ -6,5 +6,8 @@
"dependencies": {
"@openai/codex": "0.158.0",
"openclaw": "2026.9.6"
},
"overrides": {
"@modelcontextprotocol/sdk": "1.32.1"
}
}
+32 -2
View File
@@ -48,7 +48,10 @@ import urllib.request
import zipfile
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
import ssl
from headroom._subprocess import run
from headroom.offline import guard_egress
@@ -264,6 +267,25 @@ def _mirror_url(url: str) -> str:
# ---------- Download + verify --------------------------------------------- #
def _ssl_context() -> ssl.SSLContext | None:
"""Return Headroom's configured SSL context for urllib.request.urlopen, or
``None`` (urlopen's default) when the trust helper cannot be loaded.
This ensures binary downloads from GitHub releases (and any configured
mirror) trust the same roots as the proxy — including corporate
TLS-inspection roots installed in the OS store and bundles referenced via
``HEADROOM_CA_BUNDLE`` / ``SSL_CERT_FILE``. Without this, ``uv tool``
installs (where certifi may not yet be wired to the stdlib path) raise
``CERTIFICATE_VERIFY_FAILED`` even though certifi is already a dependency.
"""
try:
from headroom.proxy.ssl_context import build_urlopen_context
except ImportError:
return None
return build_urlopen_context()
def _download(url: str, dest: Path, *, progress: bool = True) -> None:
if os.environ.get("HEADROOM_BINARIES_OFFLINE"):
raise OfflineError(f"offline mode (HEADROOM_BINARIES_OFFLINE=1) but fetch required: {url}")
@@ -281,10 +303,18 @@ def _download(url: str, dest: Path, *, progress: bool = True) -> None:
if not final_url.startswith("https://"):
raise BinaryFetchError(f"refusing non-https download URL: {final_url!r}")
req = urllib.request.Request(final_url, headers={"User-Agent": "headroom-binaries/1"})
try:
ctx = _ssl_context()
except Exception as e:
raise BinaryFetchError(f"failed to configure TLS trust for binary download: {e}") from e
attempts = 3
for attempt in range(1, attempts + 1):
try:
with urllib.request.urlopen(req, timeout=60) as resp: # noqa: S310 (https)
if ctx is not None:
resp = urllib.request.urlopen(req, timeout=60, context=ctx) # noqa: S310 (https)
else:
resp = urllib.request.urlopen(req, timeout=60) # noqa: S310 (https)
with resp:
total = int(resp.headers.get("Content-Length") or 0)
_stream_to(resp, dest, total, label=dest.name, show_progress=progress)
return
+134 -29
View File
@@ -59,6 +59,10 @@ _PROVIDER_CACHE_TTL_SECONDS = {
"bedrock": 300,
}
# Keep tracker state through the same post-TTL confidence margin used by
# cold-prefix detection, but never below the configured session cleanup floor.
_CACHE_TTL_CLEANUP_MARGIN_SECONDS = 60
@dataclass
class PrefixFreezeConfig:
@@ -442,6 +446,63 @@ def _replaced_system_tail_delta(
return None
def _block_identity(block: Any) -> tuple[Any, ...]:
"""What identifies a reply block across a client's own re-serialization."""
if not isinstance(block, dict):
return ("raw", block)
kind = block.get("type")
if kind in ("tool_use", "server_tool_use"):
return (kind, block.get("id"), block.get("name"))
return (kind,)
def _client_rewrote_reply_delta(
current_messages: list[dict[str, Any]],
previous_original_messages: list[dict[str, Any]],
previous_forwarded_messages: list[dict[str, Any]],
) -> tuple[list[dict[str, Any]], list[dict[str, Any]]] | None:
"""Cache-stable split when the client re-serialized the model's last reply.
The handlers record the model's raw reply as the last message of the previous
turn, but a client may send that reply back edited: Claude Code strips a leading
``cd <cwd> &&`` from Bash commands and drops the ``caller`` annotation. Every
earlier message still matches, and the reply itself was model output, never part
of a cached prefix, so the forwarded history up to the reply is still exactly what
the provider cached. Replay it, take the client's version of the reply, and
treat what follows as the delta. Falling back to raw forwarding here instead
replaces every earlier compressed message with its original and re-writes the
whole conversation to cache.
The reply must be the same turn: an assistant message with the same block kinds
in the same order and the same tool_use ids.
"""
n = len(previous_original_messages)
if n < 2 or len(previous_forwarded_messages) != n or len(current_messages) < n:
return None
prev_reply, cur_reply = previous_original_messages[-1], current_messages[n - 1]
if not (
isinstance(prev_reply, dict)
and isinstance(cur_reply, dict)
and prev_reply.get("role") == "assistant"
and cur_reply.get("role") == "assistant"
):
return None
if _canonicalize_for_prefix_compare(
current_messages[: n - 1]
) != _canonicalize_for_prefix_compare(previous_original_messages[: n - 1]):
return None
prev_blocks = _canonicalize_for_prefix_compare(prev_reply).get("content")
cur_blocks = _canonicalize_for_prefix_compare(cur_reply).get("content")
if not isinstance(prev_blocks, list) or not isinstance(cur_blocks, list):
return None
if [_block_identity(b) for b in prev_blocks] != [_block_identity(b) for b in cur_blocks]:
return None
return (
copy.deepcopy(previous_forwarded_messages[: n - 1] + [cur_reply]),
copy.deepcopy(current_messages[n:]),
)
def classify_history_relation(
current_messages: list[dict[str, Any]],
previous_messages: list[dict[str, Any]],
@@ -513,6 +574,8 @@ def extract_cache_stable_delta(
if relation.kind == RELATION_DIVERGED:
return _replaced_system_tail_delta(
current_messages, previous_original_messages, previous_forwarded_messages
) or _client_rewrote_reply_delta(
current_messages, previous_original_messages, previous_forwarded_messages
)
if relation.kind not in (RELATION_EXACT, RELATION_MESSAGE_APPEND):
# A same-message block append needs a block-level splice in
@@ -1046,6 +1109,7 @@ class PrefixCacheTracker:
def __init__(self, provider: str, config: PrefixFreezeConfig | None = None):
self.provider = provider
self.config = config or PrefixFreezeConfig()
self._cache_ttl_seconds: int | None = None
self._cached_token_count: int = 0
self._cached_message_count: int = 0
self._turn_number: int = 0
@@ -1312,18 +1376,34 @@ class PrefixCacheTracker:
@property
def is_expired(self) -> bool:
"""Check if this tracker has been idle beyond TTL."""
return (time.time() - self._last_activity) > self.config.session_ttl_seconds
"""Check if this tracker has been idle beyond its effective retention."""
return self.is_expired_for_cache_ttl(None)
def is_expired_for_cache_ttl(self, cache_ttl_seconds: int | None) -> bool:
"""Check expiry including the longest configured or observed cache lifetime."""
observed_ttl = max(
self._cache_ttl_seconds or 0,
self.config.cache_ttl_seconds or 0,
cache_ttl_seconds or 0,
)
retention = max(
self.config.session_ttl_seconds,
observed_ttl + _CACHE_TTL_CLEANUP_MARGIN_SECONDS if observed_ttl else 0,
)
return (time.time() - self._last_activity) > retention
def observe_cache_ttl(self, cache_ttl_seconds: int | None) -> None:
"""Remember the longest provider cache lifetime observed for this lineage."""
if cache_ttl_seconds is not None:
self._cache_ttl_seconds = max(self._cache_ttl_seconds or 0, cache_ttl_seconds)
def seconds_since_activity(self) -> float:
"""Wall-clock seconds since this tracker last saw activity.
#856 P3b feeds this to the net-cost gate as an idle signal: as it
approaches the provider's prompt-cache TTL (~300s for Anthropic),
P_alive decays toward 0 and deep edits near cache lapse become free.
Distinct from :attr:`is_expired`, which uses the much longer
session-tracker *cleanup* TTL (``session_ttl_seconds``), not the cache
TTL.
approaches the provider's prompt-cache TTL, P_alive decays toward 0.
Unlike provider cache freshness, tracker cleanup uses the configured
session floor or the observed cache lifetime plus its cleanup margin.
Wiring caveat: ``SessionTrackerStore.get_or_create`` refreshes
``_last_activity`` on access, so a caller that wants the idle gap
@@ -1476,30 +1556,47 @@ class SessionTrackerStore:
return None
return tracker
def get_or_create(self, session_id: str, provider: str) -> PrefixCacheTracker:
def get_or_create(
self, session_id: str, provider: str, cache_ttl_seconds: int | None = None
) -> PrefixCacheTracker:
"""Get existing tracker or create a new one for this session."""
tracker = self._trackers.get(session_id)
if tracker is not None and tracker.is_expired:
self._discard_tracker(session_id)
tracker = None
if tracker is not None:
# Extend retention before the request-time cleanup sweep.
tracker.observe_cache_ttl(cache_ttl_seconds)
self._maybe_cleanup()
if session_id in self._trackers:
tracker = self._trackers[session_id]
# Snapshot idle-since-last-response BEFORE bumping the access clock,
# so the net-cost/TTL gate sees the true gap (see the attribute's
# docstring in PrefixCacheTracker.__init__).
if tracker is not None and session_id in self._trackers:
# Snapshot idle-since-last-response BEFORE bumping the access clock.
tracker._idle_seconds_at_fetch = max(0.0, time.time() - tracker._last_activity)
tracker._last_activity = time.time()
return tracker
tracker = PrefixCacheTracker(provider, self._default_config)
tracker._idle_seconds_at_fetch = 0.0 # cold start: nothing cached to lapse
tracker.observe_cache_ttl(cache_ttl_seconds)
tracker._idle_seconds_at_fetch = 0.0
self._trackers[session_id] = tracker
return tracker
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)
for session_id, family in list(self._lineages.items()):
family.pop(tracker_key, None)
self._lineage_affinities.pop(tracker_key, None)
if not family:
del self._lineages[session_id]
def resolve_tracker(
self,
session_id: str,
provider: str,
messages: list[dict[str, Any]] | None = None,
cache_affinity: str | None = None,
cache_ttl_seconds: int | None = None,
) -> PrefixCacheTracker:
"""Resolve the tracker for THIS conversation within a session id (#2085).
@@ -1541,20 +1638,19 @@ class SessionTrackerStore:
cache_affinity: Stable fingerprint of the provider's non-message
cache-key segments (model/tools/tool choice/thinking). Lineages
with different affinity never share a tracker.
cache_ttl_seconds: Resolved provider cache lifetime for this
request. It extends this lineage's cleanup retention before
the periodic sweep.
Returns:
The ``PrefixCacheTracker`` for this conversation's lineage.
"""
if not messages or not self._default_config.enabled:
# No lineage signal, or prefix freeze is disabled (there is no
# frozen state to protect): legacy one-tracker-per-session-id.
return self.get_or_create(session_id, provider)
# No lineage signal, or freeze disabled: use the session tracker.
return self.get_or_create(session_id, provider, cache_ttl_seconds)
# Prune expired trackers BEFORE matching, so a dead lineage cannot win
# the match. This also arms the cleanup interval: the get_or_create
# calls below cannot re-trigger a prune mid-function, so the family
# read here stays attached through the stamp at the end.
self._maybe_cleanup()
# Defer the sweep until the request has matched its lineage, allowing
# that tracker to record the provider TTL before cleanup evaluates it.
# The repo's canonical cross-turn equivalence, shared with the
# cache-stable delta path: a moved cache breakpoint, string<->block
@@ -1566,7 +1662,7 @@ class SessionTrackerStore:
if not canon:
# Degenerate: every message projected away (pure directive
# content) — no lineage signal to match on.
return self.get_or_create(session_id, provider)
return self.get_or_create(session_id, provider, cache_ttl_seconds)
snap = _lineage_snapshot(canon)
family = self._lineages.setdefault(session_id, OrderedDict())
@@ -1575,6 +1671,13 @@ class SessionTrackerStore:
# Rewritten-tail matches are deliberately last and require a unique best
# structural score; ambiguity starts a fresh lineage instead of making
# sibling sub-calls ping-pong one tracker.
expired_keys = [
key for key in family if key not in self._trackers or self._trackers[key].is_expired
]
for key in expired_keys:
family.pop(key, None)
self._lineage_affinities.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 (
@@ -1658,7 +1761,7 @@ class SessionTrackerStore:
cap,
session_id,
)
return self.get_or_create(overflow_key, provider)
return self.get_or_create(overflow_key, provider, cache_ttl_seconds)
if not family:
# First lineage rides the bare session id; this also adopts a
# tracker created earlier via plain get_or_create.
@@ -1666,11 +1769,13 @@ class SessionTrackerStore:
else:
best_key = f"{session_id}\x00{next(self._lineage_counter)}"
# get_or_create (not a private fetch) so test stubs that patch the
# instance method keep intercepting tracker creation; its internal
# cleanup is interval-gated and was armed above, so it cannot prune
# the family before the stamp below.
tracker = self.get_or_create(best_key, provider)
# Fetch through the public method so test stubs can intercept tracker
# creation. The selected lineage's TTL is applied before its cleanup
# sweep, then its snapshot is stamped after the family has been pruned.
tracker = self.get_or_create(best_key, provider, cache_ttl_seconds)
# Lookup can evict an expired bare tracker and detach an empty family.
# Stamp the replacement into the live index, not that detached mapping.
family = self._lineages.setdefault(session_id, family)
family[best_key] = snap
self._lineage_affinities[best_key] = cache_affinity
return tracker
+28 -6
View File
@@ -319,6 +319,27 @@ def _remove_marker_block(content: str, marker_start: str, marker_end: str) -> st
return content[:start].rstrip() + "\n\n" + content[end:].lstrip()
def _strip_codex_root_routing_orphans(content: str) -> str:
"""Drop Headroom loopback routing keys left at the document root.
Only the root (everything before the first table header) is Headroom's to
clean: the same keys inside ``[profiles.*]`` tables are user-owned
per-profile overrides, even when they point at Headroom.
"""
import re
first_table = re.search(r"(?m)^[ \t]*\[", content)
split = first_table.start() if first_table else len(content)
root, rest = content[:split], content[split:]
root = re.sub(r'(?m)^[ \t]*model_provider[ \t]*=[ \t]*"headroom"[ \t]*\r?\n', "", root)
root = re.sub(
r'(?m)^[ \t]*openai_base_url[ \t]*=[ \t]*"http://127\.0\.0\.1:\d+/v1"[ \t]*\r?\n',
"",
root,
)
return root + rest
def _strip_codex_init_block(content: str) -> str:
"""Remove all Headroom init-managed blocks and orphan keys from a Codex config.toml string."""
import re
@@ -338,12 +359,7 @@ def _strip_codex_init_block(content: str) -> str:
# Strip any orphan top-level keys that a crashed or partial write may have
# left outside the marker block.
content = re.sub(r'(?m)^[ \t]*model_provider[ \t]*=[ \t]*"headroom"[ \t]*\r?\n', "", content)
content = re.sub(
r'(?m)^[ \t]*openai_base_url[ \t]*=[ \t]*"http://127\.0\.0\.1:\d+/v1"[ \t]*\r?\n',
"",
content,
)
content = _strip_codex_root_routing_orphans(content)
# Strip any orphaned [model_providers.headroom] table that is recognisably ours.
orphan_headroom_table = re.compile(
@@ -921,6 +937,12 @@ def _init_codex(*, global_scope: bool, profile: str, port: int) -> None:
click.echo(
"Codex hooks are currently disabled upstream on Windows; provider routing was still installed."
)
click.echo(
"Nothing starts the Headroom proxy for Codex on Windows, so Codex cannot connect "
"while it is down. Use `headroom install apply` for a supervised proxy. To remove "
"this routing, run `headroom unwrap codex` (user scope) or delete the Headroom init "
"provider block from the project's .codex/config.toml."
)
click.echo("Restart Codex to activate Headroom configuration.")
+124 -10
View File
@@ -9,6 +9,7 @@ import sys
from collections.abc import Mapping
from copy import deepcopy
from dataclasses import dataclass
from pathlib import Path
import click
from click.core import ParameterSource
@@ -16,6 +17,7 @@ from click.core import ParameterSource
from headroom._subprocess import run
from headroom.install.health import probe_json, probe_ready
from headroom.install.models import (
ArtifactRecord,
ConfigScope,
DeploymentManifest,
InstallPreset,
@@ -23,7 +25,7 @@ from headroom.install.models import (
RuntimeKind,
SupervisorKind,
)
from headroom.install.paths import recovery_manifest_path
from headroom.install.paths import opencode_config_path, recovery_manifest_path
from headroom.install.planner import build_manifest, build_tool_envs
from headroom.install.providers import apply_mutations, revert_mutations
from headroom.install.runtime import (
@@ -53,6 +55,7 @@ from headroom.install.supervisors import (
start_supervisor,
stop_supervisor,
)
from headroom.providers.opencode.install import restore_opencode_backup
from .main import main
@@ -234,11 +237,15 @@ def _stop_deployment(manifest: DeploymentManifest) -> None:
def _deactivate_deployment_mutations(
manifest: DeploymentManifest, *, persist_manifest: bool = True
manifest: DeploymentManifest,
*,
persist_manifest: bool = True,
restore_backup: bool = False,
) -> None:
if not manifest.mutations:
return
revert_mutations(manifest)
revert_mutations(manifest, restore_backup=restore_backup)
manifest.mutations = []
if persist_manifest:
save_manifest(manifest)
@@ -312,16 +319,52 @@ def pending_tool_envs(manifest: DeploymentManifest) -> dict[str, dict[str, str]]
return pending
def _track_opencode_backup(manifest: DeploymentManifest, *, activating: bool = False) -> None:
if getattr(manifest, "scope", None) != ConfigScope.PROVIDER.value or "opencode" not in getattr(
manifest, "targets", []
):
return
artifacts = getattr(manifest, "artifacts", None)
if artifacts is None:
return
paths = {
mutation.path
for mutation in getattr(manifest, "mutations", [])
if mutation.target == "opencode" and mutation.path
}
if activating:
paths.add(str(opencode_config_path()))
changed = False
for path in sorted(paths):
if any(item.kind == "opencode-config-backup" and item.path == path for item in artifacts):
continue
config_path = Path(path)
backup_path = config_path.with_name(config_path.name + ".headroom-backup")
artifacts.append(
ArtifactRecord(
kind="opencode-config-backup",
path=path,
metadata={"backup_path": str(backup_path)},
)
)
changed = True
if changed:
# Persist ownership before provider mutation or snapshot creation.
_save_apply_manifest(manifest)
def _activate_deployment_mutations(manifest: DeploymentManifest) -> None:
for target, names in sorted(_reconcile_tool_envs(manifest).items()):
click.echo(f"Applying newer managed settings for {target}: {', '.join(names)}")
try:
_track_opencode_backup(manifest, activating=True)
manifest.mutations = apply_mutations(manifest)
_save_apply_manifest(manifest)
except Exception as exc:
if manifest.mutations:
try:
revert_mutations(manifest)
revert_mutations(manifest, restore_backup=False)
except Exception as rollback_exc:
raise RuntimeError(
f"mutation activation failed: {exc}; rollback failed: {rollback_exc}"
@@ -358,10 +401,42 @@ def _delete_recovery_snapshot(profile: str) -> None:
) from None
def _remove_deployment(manifest: DeploymentManifest) -> None:
def _restore_owned_opencode_backup(
manifest: DeploymentManifest, *, preserve_paths: set[str] | None = None
) -> None:
artifacts = getattr(manifest, "artifacts", None)
if artifacts is None:
return
for artifact in artifacts:
if artifact.kind != "opencode-config-backup" or (
preserve_paths is not None and artifact.path in preserve_paths
):
continue
backup_path = artifact.metadata.get("backup_path")
if isinstance(backup_path, str):
restore_opencode_backup(artifact.path, backup_path)
manifest.artifacts = [
artifact
for artifact in artifacts
if artifact.kind != "opencode-config-backup"
or (preserve_paths is not None and artifact.path in preserve_paths)
]
def _remove_deployment(
manifest: DeploymentManifest,
*,
restore_backup: bool = False,
preserve_opencode_paths: set[str] | None = None,
) -> None:
errors: list[tuple[str, Exception]] = []
try:
_deactivate_deployment_mutations(manifest, persist_manifest=False)
if restore_backup:
_track_opencode_backup(manifest)
if manifest.mutations:
_deactivate_deployment_mutations(manifest, persist_manifest=False, restore_backup=False)
if restore_backup:
_restore_owned_opencode_backup(manifest, preserve_paths=preserve_opencode_paths)
except Exception as exc:
errors.append(("mutation cleanup", exc))
try:
@@ -382,7 +457,9 @@ def _remove_deployment(manifest: DeploymentManifest) -> None:
def _restore_deployment(manifest: DeploymentManifest) -> None:
restored = deepcopy(manifest)
restored.artifacts = install_supervisor(restored, start=False)
restored.artifacts = [
artifact for artifact in restored.artifacts if artifact.kind == "opencode-config-backup"
] + install_supervisor(restored, start=False)
_save_apply_manifest(restored)
_start_deployment(restored)
_activate_deployment_mutations(restored)
@@ -583,6 +660,7 @@ def _apply_manifest(manifest: DeploymentManifest) -> None:
recovery_saved = False
active_persistence_failed = False
existing = None
existing_opencode_paths: set[str] = set()
try:
try:
existing = load_manifest(profile)
@@ -590,9 +668,21 @@ def _apply_manifest(manifest: DeploymentManifest) -> None:
click.echo(f"Warning: {e}; overwriting.")
if existing is not None:
click.echo(f"Updating existing deployment profile '{profile}'...")
_track_opencode_backup(existing)
existing_opencode_paths = {
artifact.path
for artifact in getattr(existing, "artifacts", [])
if artifact.kind == "opencode-config-backup"
}
manifest.artifacts.extend(
artifact
for artifact in getattr(existing, "artifacts", [])
if artifact.kind == "opencode-config-backup" and artifact not in manifest.artifacts
)
_save_recovery_snapshot(existing, profile)
recovery_saved = True
_remove_deployment(existing)
except Exception as exc:
recovery_detail = (
f" Recovery snapshot: {recovery_manifest_path(profile)} is retained; "
@@ -610,7 +700,9 @@ def _apply_manifest(manifest: DeploymentManifest) -> None:
except Exception:
active_persistence_failed = True
raise
manifest.artifacts = install_supervisor(manifest, start=False)
manifest.artifacts = [
artifact for artifact in manifest.artifacts if artifact.kind == "opencode-config-backup"
] + install_supervisor(manifest, start=False)
try:
_save_apply_manifest(manifest)
except Exception:
@@ -625,7 +717,11 @@ def _apply_manifest(manifest: DeploymentManifest) -> None:
except Exception as exc:
cleanup_errors: list[Exception] = []
try:
_remove_deployment(manifest)
_remove_deployment(
manifest,
restore_backup=True,
preserve_opencode_paths=existing_opencode_paths,
)
except Exception as cleanup_exc:
cleanup_errors.append(cleanup_exc)
if not cleanup_errors and not active_persistence_failed and existing is not None:
@@ -670,6 +766,24 @@ def _apply_manifest(manifest: DeploymentManifest) -> None:
f"{cleanup_detail}{persistence_detail}{_recovery_detail()}"
) from exc
raise click.ClickException(f"Failed to install deployment '{profile}': {exc}") from exc
active_opencode_paths = {
mutation.path
for mutation in manifest.mutations
if mutation.target == "opencode" and mutation.path
}
if any(
artifact.kind == "opencode-config-backup" and artifact.path not in active_opencode_paths
for artifact in manifest.artifacts
):
try:
_restore_owned_opencode_backup(manifest, preserve_paths=active_opencode_paths)
_save_apply_manifest(manifest)
except Exception as exc:
raise click.ClickException(
f"Deployment '{profile}' is active, but OpenCode snapshot restoration failed: "
f"{exc}. Backup ownership is retained in the deployment manifest; "
"resolve the filesystem failure and retry install apply."
) from exc
if recovery_saved:
_delete_recovery_snapshot(profile)
@@ -1120,7 +1234,7 @@ def install_remove(profile: str) -> None:
manifest = _require_manifest(profile)
try:
_remove_deployment(manifest)
_remove_deployment(manifest, restore_backup=True)
except Exception as exc:
raise click.ClickException(
f"Failed to remove deployment '{profile}': cleanup failed: {exc}. "
+26 -6
View File
@@ -139,9 +139,9 @@ def mcp_install(proxy_url: str, agents: tuple[str, ...], force: bool) -> None:
\b
By default this installs into every agent that has a registrar and is
detected on this system (Claude Code today; Cursor / Codex / Continue /
others added in subsequent releases). Pass ``--agent NAME`` one or more
times to restrict the installation.
detected on this system (Antigravity IDE, Claude Code, Codex, Grok CLI,
OpenCode today; Cursor / Continue / others added in subsequent releases).
Pass ``--agent NAME`` one or more times to restrict the installation.
\b
Examples:
@@ -188,18 +188,38 @@ def mcp_install(proxy_url: str, agents: tuple[str, ...], force: bool) -> None:
@mcp.command("uninstall")
def mcp_uninstall() -> None:
@click.option(
"--agent",
"agents",
multiple=True,
help="Restrict uninstallation to specific agents (default: every detected agent).",
)
def mcp_uninstall(agents: tuple[str, ...]) -> None:
"""Remove Headroom MCP server from detected agent configs.
\b
Removes headroom from every agent registrar known to Headroom. Other MCP
servers are preserved.
servers are preserved. Pass ``--agent NAME`` one or more times to restrict
the uninstallation.
\b
Examples:
headroom mcp uninstall # every detected agent
headroom mcp uninstall --agent antigravity # Antigravity IDE only
"""
from headroom.mcp_registry import get_all_registrars
registrars = get_all_registrars()
if agents:
wanted = {agent.strip().lower() for agent in agents if agent.strip()}
registrars = [registrar for registrar in registrars if registrar.name in wanted]
if not registrars:
click.echo("No agents matched the requested filter.")
raise SystemExit(1)
removed = False
for registrar in get_all_registrars():
for registrar in registrars:
if not registrar.detect():
continue
removed_names: list[str] = []
+3 -3
View File
@@ -770,9 +770,9 @@ def dashboard(port: int, no_open: bool) -> None:
envvar="HEADROOM_READ_MATURATION",
help=(
"EXPERIMENTAL: activity-based read maturation — hold fresh Reads "
"out of the provider prefix cache and compress them once their "
"file quiesces. Requires HEADROOM_ROLLOUT_CHANNEL=beta (or dev); "
"env: HEADROOM_READ_MATURATION=1."
"verbatim and compress them once their file quiesces, unless the "
"provider cache already holds them. Requires "
"HEADROOM_ROLLOUT_CHANNEL=beta (or dev); env: HEADROOM_READ_MATURATION=1."
),
)
@click.option(
+172 -21
View File
@@ -11,6 +11,7 @@ Usage:
headroom wrap vibe # Start proxy + Mistral Vibe
headroom wrap grok # Start proxy + Grok CLI
headroom wrap cursor # Start proxy + print Cursor config instructions
headroom wrap antigravity # Start proxy + print Antigravity config instructions
headroom wrap grok-build # Start proxy + configure Grok Build
headroom wrap openclaw # Install + configure OpenClaw plugin
headroom wrap claude --port 9999 # Custom proxy port
@@ -81,6 +82,9 @@ from headroom.copilot_auth import (
resolve_subscription_bearer_token_details,
)
from headroom.providers.aider import build_launch_env as _build_aider_launch_env
from headroom.providers.antigravity import (
render_setup_lines as _render_antigravity_setup_lines,
)
from headroom.providers.claude import (
CONTEXT_1M_SUFFIX,
DEFAULT_1M_MODEL,
@@ -191,10 +195,15 @@ from headroom.providers.opencode.config import (
_PROVIDER_MARKER_END, # noqa: F401
_PROVIDER_MARKER_START,
inject_opencode_provider_config,
migrate_legacy_opencode_jsonc_backup,
opencode_config_paths,
snapshot_opencode_config_if_unwrapped,
strip_opencode_headroom_blocks,
)
from headroom.providers.opencode.runtime import (
opencode_major_version,
with_opencode_standalone,
)
from headroom.providers.wrap_registry import WRAP_TARGETS, WrapTarget
from headroom.providers.wrap_registry import build_launch_env as _build_registry_launch_env
from headroom.providers.zcode import (
@@ -314,7 +323,15 @@ def _append_text(path: Path, content: str) -> None:
fsutil.append_text(path, content)
_AGENT_SAVINGS_TARGET_AGENTS = {"claude", "codex", "cursor", "grok", "grok_build", "opencode"}
_AGENT_SAVINGS_TARGET_AGENTS = {
"antigravity",
"claude",
"codex",
"cursor",
"grok",
"grok_build",
"opencode",
}
_WRAP_PROXY_TIMEOUT_ENV = "HEADROOM_WRAP_PROXY_TIMEOUT"
_WRAP_PROXY_TIMEOUT_DEFAULT_SECONDS = 45
_WRAP_PROXY_TIMEOUT_ML_DEFAULT_SECONDS = 90
@@ -330,7 +347,14 @@ _WRAP_PROXY_TIMEOUT_ML_MODULES = ("torch", "sentence_transformers", "spacy")
_TOOL_SEARCH_ENV = TOOL_SEARCH_ENV
_TOOL_SEARCH_DEFAULT = TOOL_SEARCH_DEFAULT
_TOOL_SEARCH_FOUNDRY_DEFAULT = TOOL_SEARCH_FOUNDRY_DEFAULT
_AGENT_SAVINGS_WRAP_AGENTS = {"claude", "codex", "cursor", "grok", "grok_build"}
_AGENT_SAVINGS_WRAP_AGENTS = {
"antigravity",
"claude",
"codex",
"cursor",
"grok",
"grok_build",
}
# 1M context window for `wrap claude` (#1158). Claude Code only sends the
# `context-1m` beta header — unlocking the 1M window for entitled subscription
@@ -3085,13 +3109,11 @@ def _strip_codex_headroom_blocks(
content = _remove_marker_span(content, _MEMORY_MCP_MARKER, _MEMORY_MCP_END)
# Strip any leftover top-level keys that older (or crashed) versions of
# `wrap codex` may have written outside the marker block.
content = re.sub(r'(?m)^[ \t]*model_provider[ \t]*=[ \t]*"headroom"[ \t]*\r?\n', "", content)
content = re.sub(
r'(?m)^[ \t]*openai_base_url[ \t]*=[ \t]*"http://127\.0\.0\.1:\d+/v1"[ \t]*\r?\n',
"",
content,
)
# `wrap codex` may have written outside the marker block. Root only:
# [profiles.*] overrides are the user's.
from headroom.cli.init import _strip_codex_root_routing_orphans
content = _strip_codex_root_routing_orphans(content)
# Remove an orphaned local-proxy provider structurally. Text-level table
# matching cannot safely distinguish comments, multiline strings, and
@@ -3610,7 +3632,8 @@ def _inject_codex_provider_config(port: int) -> str | None:
def _restore_codex_provider_config() -> tuple[str, Path]:
"""Undo ``_inject_codex_provider_config`` for the active Codex config file.
"""Undo ``_inject_codex_provider_config`` (and ``headroom init codex``
routing) for the active Codex config file.
Returns a tuple of ``(status, config_file)`` where status is one of:
@@ -3619,21 +3642,37 @@ def _restore_codex_provider_config() -> tuple[str, Path]:
* ``"cleaned"`` — no backup existed, but the Headroom-managed block was
found and stripped out (preserving surrounding user content).
* ``"removed"`` — the config file only contained Headroom-managed
content (created by wrap) and has been deleted.
content (created by wrap or init) and has been deleted.
* ``"noop"`` — nothing to undo; no Headroom marker and no backup.
"""
from headroom.cli.init import _CODEX_PROVIDER_MARKER_START, _strip_codex_init_block
config_file, backup_file = _codex_config_paths()
# Case 1: pre-wrap snapshot exists — restore it exactly.
if backup_file.exists():
shutil.copy2(backup_file, config_file)
# A snapshot taken after `headroom init codex` still carries init's
# routing block; restoring it verbatim would leave Codex pinned to the
# proxy while unwrap reports success (#3749). The snapshot is deleted
# only once the config is written, so a failed write can be retried.
snapshot = _read_text(backup_file)
if _CODEX_PROVIDER_MARKER_START in snapshot:
cleaned = _strip_codex_init_block(snapshot)
if not cleaned.strip():
config_file.unlink(missing_ok=True)
backup_file.unlink()
return "removed", config_file
_write_text(config_file, cleaned)
else:
shutil.copy2(backup_file, config_file)
backup_file.unlink()
return "restored", config_file
# Case 2: no backup, but config file exists and has markers — strip them.
if config_file.exists():
original = _read_text(config_file)
if _codex_config_has_headroom_markers(original):
has_init_block = _CODEX_PROVIDER_MARKER_START in original
if has_init_block or _codex_config_has_headroom_markers(original):
# Without a backup, only remove named MCP blocks when this file
# also carries wrap-owned provider markers from a full wrap.
remove_named_mcp = any(
@@ -3645,8 +3684,11 @@ def _restore_codex_provider_config() -> tuple[str, Path]:
_CODEX_MCP_END,
)
)
# `headroom init codex` writes its own routing block, and nothing else
# removes it (#3749). Strip it first so its markers go with its keys.
content = _strip_codex_init_block(original) if has_init_block else original
cleaned = _strip_codex_headroom_blocks(
original,
content,
remove_mcp=True,
remove_named_mcp=remove_named_mcp,
)
@@ -5112,7 +5154,13 @@ def _ensure_proxy_unlocked(
_warn_proxy_mode_mismatch(running_config)
elif not helpers._check_proxy(port):
click.echo(f" Warning: No proxy detected on port {port}")
elif vertex_api_url or clear_vertex_api_url or os.environ.get("HEADROOM_MODE"):
elif (
vertex_api_url
or clear_vertex_api_url
or os.environ.get("HEADROOM_MODE")
or os.environ.get("HEADROOM_MIN_TOKENS") is not None
or os.environ.get("HEADROOM_EXCLUDE_TOOLS") is not None
):
health_payload = helpers._query_proxy_health(port)
running_config = helpers._proxy_health_config(health_payload)
if running_config is None:
@@ -5634,6 +5682,7 @@ def wrap(ctx: click.Context) -> None:
headroom wrap vibe # Mistral Vibe
headroom wrap grok # Grok CLI (xAI)
headroom wrap cursor # Cursor (prints config instructions)
headroom wrap antigravity # Antigravity IDE (prints config instructions)
headroom wrap grok-build # Grok Build (updates ~/.grok/config.toml)
headroom wrap cline # Cline (VS Code; prints config instructions)
headroom wrap continue # Continue (VS Code/JetBrains; injects systemMessage)
@@ -7662,6 +7711,62 @@ def cursor(
)
# =============================================================================
# Antigravity IDE
# =============================================================================
@wrap.command(context_settings={"ignore_unknown_options": True})
@_retired_context_tool_option
@proxy_port_option()
@click.option("--no-proxy", is_flag=True, help="Skip proxy startup (use existing proxy)")
@click.option("--learn", is_flag=True, help="Enable live traffic learning")
@click.option("--memory", is_flag=True, help="Enable persistent cross-session memory")
@click.option("--verbose", "-v", is_flag=True, help="Verbose output")
@click.option("--prepare-only", is_flag=True, hidden=True)
def antigravity(
port: int,
no_proxy: bool,
learn: bool,
memory: bool,
verbose: bool,
prepare_only: bool,
) -> None:
"""Start Headroom proxy for use with Antigravity IDE.
\b
Antigravity reads its model endpoints from its model-provider settings,
not from environment variables. This command starts the proxy and prints
the settings to add as a custom OpenAI-compatible model provider.
\b
After running this command, open Antigravity and add a custom model
provider with the printed base URL. Antigravity fetches the model list
from GET /v1/models automatically.
\b
Example:
headroom wrap antigravity # Start proxy + Antigravity settings
headroom wrap antigravity --port 9999 # Custom proxy port
"""
if prepare_only:
return
def _print_antigravity_setup(actual_port: int) -> None:
for line in _render_antigravity_setup_lines(actual_port, project=_project_name_from_cwd()):
click.echo(line)
_run_proxy_only_watcher(
agent_label="antigravity",
port=port,
no_proxy=no_proxy,
learn=learn,
memory=memory,
agent_type="antigravity",
print_setup_lines=_print_antigravity_setup,
)
# =============================================================================
# Grok Build
# =============================================================================
@@ -8262,6 +8367,8 @@ def opencode(
Sets OPENCODE_CONFIG_CONTENT to route all OpenCode API calls through
Headroom. Configures a headroom provider via @ai-sdk/openai-compatible.
Also sets OPENAI_BASE_URL and ANTHROPIC_BASE_URL as fallbacks.
On OpenCode 2.x, adds --standalone (unless --server is given) so a private
server loads that config instead of a running background service.
\b
Examples:
@@ -8430,13 +8537,19 @@ def opencode(
os.environ.get("USER", os.environ.get("USERNAME", "default")),
)
# OpenCode 2.x otherwise attaches to an already-running background
# service that never sees this launch's OPENCODE_CONFIG_CONTENT.
launch_args = with_opencode_standalone(opencode_args, opencode_major_version(opencode_bin))
if verbose and launch_args != tuple(opencode_args):
click.echo(" OpenCode 2.x: adding --standalone so it loads Headroom's config")
# Proxy already started by _ensure_proxy above; tell _launch_tool to
# skip duplicate startup.
launch_started = True
try:
_launch_tool(
binary=opencode_bin,
args=opencode_args,
args=launch_args,
env=env,
port=actual_port,
no_proxy=True,
@@ -8510,6 +8623,7 @@ def unwrap_opencode(port: int, no_stop_proxy: bool) -> None:
click.echo()
config_file, backup_file = opencode_config_paths()
migrate_legacy_opencode_jsonc_backup(config_file, backup_file)
if backup_file.exists():
try:
@@ -8689,7 +8803,7 @@ def unwrap_grok_build(port: int, no_stop_proxy: bool) -> None:
)
@click.option("--no-stop-proxy", is_flag=True, help="Do not stop the local Headroom proxy")
def unwrap_codex(port: int, no_stop_proxy: bool) -> None:
"""Undo ``headroom wrap codex`` edits to the active Codex config file.
"""Undo ``headroom wrap codex`` and ``headroom init codex`` routing in the Codex config.
Behaviour:
@@ -8965,12 +9079,49 @@ def unwrap_zcode(port: int, no_stop_proxy: bool) -> None:
def _warn_proxy_mode_mismatch(running_config: dict[str, Any] | None) -> None:
"""Warn when a reused proxy runs a different mode than this session asked for.
"""Warn when reuse ignores this session's startup-only settings.
Mode is fixed at proxy startup, so a requested HEADROOM_MODE (explicit, or
a wrap target's default_mode) is silently ignored on reuse. Warning-only:
other clients may be attached to the running proxy.
Do not restart a shared proxy: other clients may be attached to it.
"""
config = running_config or {}
mismatches: list[str] = []
requested_min = os.environ.get("HEADROOM_MIN_TOKENS")
running_min = config.get("min_tokens_to_crush")
if requested_min is not None and isinstance(running_min, int):
try:
requested_min_value = int(requested_min)
except ValueError:
requested_min_value = None
if requested_min_value is not None and requested_min_value != running_min:
mismatches.append(f"HEADROOM_MIN_TOKENS={requested_min_value} (running: {running_min})")
requested_excludes = os.environ.get("HEADROOM_EXCLUDE_TOOLS")
running_excludes = config.get("exclude_tools")
if (
requested_excludes is not None
and isinstance(running_excludes, list)
and all(isinstance(name, str) for name in running_excludes)
):
from headroom.config import DEFAULT_EXCLUDE_TOOLS
defaults = {name.lower() for name in DEFAULT_EXCLUDE_TOOLS}
requested_names = {
name.strip().lower() for name in requested_excludes.split(",") if name.strip()
}
running_names = {name.lower() for name in running_excludes}
if requested_names | defaults != running_names | defaults:
mismatches.append(
f"HEADROOM_EXCLUDE_TOOLS={sorted(requested_names)!r} "
f"(running: {sorted(running_names)!r})"
)
if mismatches:
click.echo(
" Warning: this session requested "
+ "; ".join(mismatches)
+ ", but those settings are fixed at proxy startup. "
"Restart the proxy, or use --port for a separate one."
)
requested = os.environ.get("HEADROOM_MODE")
running = (running_config or {}).get("mode")
if not requested or not isinstance(running, str):
+15 -7
View File
@@ -229,6 +229,10 @@ DEFAULT_EXCLUDE_TOOLS: frozenset[str] = frozenset(
"WebSearch",
"WebFetch",
"headroom_retrieve",
# Caveman's recovery tool: like headroom_retrieve, it returns the stored
# original of something Caveman compressed upstream of us. Compressing it
# again hands the model a lossy copy of the "complete original" (#4010).
"caveman_retrieve",
# Copilot CLI's file-read tool (its `Read` equivalent): raw file bytes
# the model byte-patches against.
"view",
@@ -282,6 +286,9 @@ DEFAULT_VERBATIM_EXCLUDE_TOOLS: frozenset[str] = frozenset(
"web_search",
"web_fetch",
"headroom_retrieve",
# A recovery tool's output must reach the model exactly as stored; even
# the lossless fold (e.g. JSON minify) changes it (#4010).
"caveman_retrieve",
# `view` (Copilot CLI file read) must stay BYTE-EXACT: the model produces
# line/byte-precise edits against it, and even "lossless" JSON rewrites
# or cross-turn dedup folds break old_str matching and force re-reads.
@@ -652,13 +659,14 @@ class ReadMaturationConfig:
roughly 13x its size. The only cache-safe moment to shrink it is
BEFORE it is ever cache-written.
Mechanics: a fresh large Read is held out of the provider prefix
cache (the trailing cache breakpoint is relocated to just before it)
while its file is ACTIVE, stays verbatim the whole time the model is
working with it, and matures into a CCR-backed marker once the file
has been quiet for `quiesce_turns`. Only that final compressed form
ever enters the cache. No cached byte is ever mutated — there is
nothing to bust.
Mechanics: a fresh large Read is held verbatim while its file is
ACTIVE, so the model sees the full text the whole time it is working
with it, and matures into a CCR-backed marker once the file has been
quiet for `quiesce_turns`, if it is still outside the provider-cached
prefix. The held Read is cached with its turn (the client's
breakpoints stay in place), so in a warm session it usually stays
verbatim: re-writing everything after a cached Read costs more than
the Read saves.
Activity-based (not a fixed hold window) because the audit-reads
simulation showed touch gaps are fat-tailed: next-touch p50 is 4
+21 -3
View File
@@ -1,6 +1,7 @@
"""Headroom Dashboard - Real-time proxy monitoring UI."""
import mimetypes
import re
from pathlib import Path
DASHBOARD_DIR = Path(__file__).parent
@@ -49,10 +50,27 @@ def register_static_mime_types() -> None:
mimetypes.add_type(mime_type, extension)
def get_dashboard_html() -> str:
"""Load the dashboard HTML template."""
_TEAMS_PERK = re.compile(r"[ \t]*<!-- teams-perk:start.*?<!-- teams-perk:end -->\n?", re.DOTALL)
def get_dashboard_html(*, licensed: bool | None = None) -> str:
"""Load the dashboard HTML template.
The Headroom for Teams offer is stripped on a licensed install: it is
already a customer. ``licensed`` is the running proxy's effective licence
state (``create_app`` passes it, covering ``ProxyConfig.license_key``).
When omitted it is resolved from the environment the same way the CLI
does: ``HEADROOM_LICENSE``, or the deprecated ``HEADROOM_LICENSE_KEY``.
"""
template_path = TEMPLATES_DIR / "dashboard.html"
return template_path.read_text(encoding="utf-8")
html = template_path.read_text(encoding="utf-8")
if licensed is None:
from headroom.license_env import resolve_license_token
licensed = bool(resolve_license_token())
if licensed:
html = _TEAMS_PERK.sub("", html)
return html
def get_settings_html() -> str:
@@ -209,6 +209,26 @@
</header>
<main class="p-6 max-w-7xl mx-auto">
<!-- teams-perk:start — removed server-side when HEADROOM_LICENSE is set
(see headroom.dashboard.get_dashboard_html). A plain link: nothing
is fetched or reported, and dismissal stays in this browser. -->
<aside data-testid="teams-perk" x-show="!teamsPerkDismissed"
class="mb-6 flex flex-col gap-3 rounded-lg border border-accent/40 bg-surface p-4 md:flex-row md:items-center md:justify-between">
<p class="text-sm text-gray-300">
<span class="font-medium text-accent">Headroom for Teams</span>
<span x-text="(stats.summary?.cost?.total_saved_usd || 0) >= 1
? ' · You have saved $' + formatCurrency(stats.summary.cost.total_saved_usd) + ' on this machine. Get the same savings across your team, with 3 months free on a 12-month plan.'
: ' · Bring these savings to your whole team, with 3 months free on a 12-month plan.'"></span>
</p>
<div class="flex items-center gap-3 shrink-0">
<a href="https://headroom-perks.vercel.app/?source=github&utm_source=headroom&utm_medium=dashboard&utm_content=banner"
target="_blank" rel="noopener noreferrer"
class="px-3 py-1.5 text-sm font-medium rounded-md bg-accent text-black hover:opacity-90">Claim 3 months free →</a>
<button type="button" @click="dismissTeamsPerk()" aria-label="Dismiss Headroom for Teams offer"
class="text-sm text-gray-500 hover:text-gray-200">✕</button>
</div>
</aside>
<!-- teams-perk:end -->
<template x-if="viewMode === 'session'">
<div data-testid="session-view">
<p class="mb-4 text-xs text-gray-500">Current proxy process · runtime counters reset on restart</p>
@@ -2033,6 +2053,14 @@
function dashboard() {
return {
stats: {},
teamsPerkDismissed: (() => {
try { return localStorage.getItem('headroom-teams-perk-dismissed') === '1'; }
catch (e) { return false; }
})(),
dismissTeamsPerk() {
this.teamsPerkDismissed = true;
try { localStorage.setItem('headroom-teams-perk-dismissed', '1'); } catch (e) {}
},
lifetimeStats: {},
historyStats: {},
healthy: true,
+1
View File
@@ -59,6 +59,7 @@ class ToolTarget(str, Enum):
GROK = "grok"
OPENCLAW = "openclaw"
OPENCODE = "opencode"
ANTIGRAVITY = "antigravity"
def iso_utc_now() -> str:
+23
View File
@@ -9,6 +9,7 @@ from collections.abc import Iterable
import click
from headroom import paths as _paths
from headroom.mcp_registry.antigravity import AntigravityRegistrar
from headroom.providers.grok.runtime import DEFAULT_API_URL as _GROK_DEFAULT_API_URL
from headroom.providers.install_registry import build_install_target_envs
from headroom.rollout import RolloutChannel
@@ -34,6 +35,7 @@ SUPPORTED_TARGETS = [
ToolTarget.GROK,
ToolTarget.OPENCLAW,
ToolTarget.OPENCODE,
ToolTarget.ANTIGRAVITY,
]
PROVIDER_SCOPE_TARGETS = [
ToolTarget.CLAUDE,
@@ -63,9 +65,26 @@ def detect_targets() -> list[str]:
continue
if target == ToolTarget.GROK_BUILD and shutil.which("grok"):
detected.append(target.value)
if target == ToolTarget.ANTIGRAVITY and _antigravity_detected():
detected.append(target.value)
return detected
def _antigravity_detected() -> bool:
"""Detect an Antigravity IDE install via its own markers.
The bare ``~/.gemini`` home is not enough: Gemini CLI keeps its session
data there too, so a Gemini-CLI-only host must not count as Antigravity
(a false positive suppresses the auto-install defaults in
``resolve_targets``). The MCP registrar owns the authoritative gate —
the ``~/.gemini/antigravity`` or ``~/.gemini/config`` directories, or an
existing MCP config file — so reuse it here instead of re-implementing
the check.
"""
return AntigravityRegistrar().detect()
def resolve_targets(
provider_mode: str, requested_targets: Iterable[str], *, scope: str = ConfigScope.USER.value
) -> list[str]:
@@ -190,11 +209,15 @@ def build_manifest(
# Grok / Grok Build need proxy upstream = xAI. Only auto-set when no other
# OpenAI-compatible tools share this proxy (those may need api.openai.com /
# Copilot). Explicit OPENAI_TARGET_API_URL in extra_env still wins below.
# Antigravity speaks the OpenAI protocol (custom OpenAI-compatible model
# provider), so it belongs in the exclusion set too: a Grok + Antigravity
# deployment must not send Antigravity's traffic to xAI.
_openai_native = {
ToolTarget.CODEX.value,
ToolTarget.COPILOT.value,
ToolTarget.AIDER.value,
ToolTarget.OPENCODE.value,
ToolTarget.ANTIGRAVITY.value,
}
_grok_targets = {ToolTarget.GROK.value, ToolTarget.GROK_BUILD.value}
target_set = set(resolved_targets)
+8 -3
View File
@@ -192,7 +192,8 @@ def apply_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
except Exception as exc:
if mutations:
try:
revert_mutations(manifest)
revert_mutations(manifest, restore_backup=False)
except Exception as rollback_exc:
raise RuntimeError(
f"mutation application failed: {exc}; rollback failed: {rollback_exc}"
@@ -202,7 +203,11 @@ def apply_mutations(manifest: DeploymentManifest) -> list[ManagedMutation]:
raise
def revert_mutations(manifest: DeploymentManifest) -> None:
def revert_mutations(
manifest: DeploymentManifest,
*,
restore_backup: bool = True,
) -> None:
"""Undo the stored mutations for a deployment."""
if manifest.scope in {ConfigScope.USER.value, ConfigScope.SYSTEM.value}:
@@ -213,4 +218,4 @@ def revert_mutations(manifest: DeploymentManifest) -> None:
_remove_unix_env_scope(shell_mutations)
for mutation in manifest.mutations:
revert_provider_scope_mutation(manifest, mutation)
revert_provider_scope_mutation(manifest, mutation, restore_backup=restore_backup)
+17 -5
View File
@@ -6,6 +6,7 @@ injection mechanism for each agent system (CLAUDE.md, .cursorrules, etc.).
from __future__ import annotations
import html
import re
import subprocess
from abc import ABC, abstractmethod
@@ -124,6 +125,18 @@ _PATTERN_ID_PATTERN = re.compile(
)
def _tagged_pattern_id(line: str) -> str | None:
"""Return the id inside a bullet's pattern-id comment, if any.
``_build_section`` sanitizes block content, so on disk the comment reads
``&lt;!-- ... --&gt;``; match against the decoded line so carried-forward
sections are still recognized as lifecycle-tracked. Callers keep the
original (still-sanitized) line when the bullet survives.
"""
match = _PATTERN_ID_PATTERN.search(html.unescape(line))
return match.group(1) if match else None
def _merge_markdown_items(
new_content: str,
prior_content: str,
@@ -152,8 +165,7 @@ def _merge_markdown_items(
return None
items: list[tuple[str | None, str, str]] = []
for line in lines:
id_match = _PATTERN_ID_PATTERN.search(line)
pattern_id = id_match.group(1) if id_match else None
pattern_id = _tagged_pattern_id(line)
visible = _PATTERN_ID_PATTERN.sub("", line).strip().casefold()
items.append((pattern_id, visible, line))
return items
@@ -227,12 +239,12 @@ def _prune_carried_section(
kept: list[str] = []
saw_tracked_item = False
for line in lines:
id_match = _PATTERN_ID_PATTERN.search(line)
if id_match is None:
pattern_id = _tagged_pattern_id(line)
if pattern_id is None:
kept.append(line)
continue
saw_tracked_item = True
if id_match.group(1) in active_item_ids:
if pattern_id in active_item_ids:
kept.append(line)
if not saw_tracked_item:
return None
+2
View File
@@ -13,6 +13,7 @@ without changing the calling code.
from __future__ import annotations
from .antigravity import AntigravityRegistrar
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
from .claude import ClaudeConfigMutationError, ClaudeRegistrar
from .codex import CodexRegistrar
@@ -32,6 +33,7 @@ from .server_json import build_server_json, render_server_json
__all__ = [
"DEFAULT_PROXY_URL",
"CLAUDE_SERENA_CONTEXT",
"AntigravityRegistrar",
"ClaudeConfigMutationError",
"ClaudeRegistrar",
"CodexRegistrar",
+248
View File
@@ -0,0 +1,248 @@
"""Antigravity IDE MCP registrar.
Antigravity (Google's AI-first IDE) stores MCP server configuration in a
JSON file holding a top-level ``mcpServers`` object::
{
"mcpServers": {
"headroom": {
"command": "/path/to/headroom",
"args": ["mcp", "serve"],
"env": {"HEADROOM_PROXY_URL": "http://127.0.0.1:8787"}
}
}
}
The on-disk location has moved between Antigravity releases — Google's
current Antigravity codelab identifies ``~/.gemini/config/mcp_config.json``
as the active Desktop config, while older guides cite
``~/.gemini/antigravity/mcp_config.json`` — so this registrar treats the
former as authoritative: it probes the known candidates in order and uses
the first one that exists, falling back to the current location when none
does yet. Uninstall removes the entry from every candidate that still holds
it, so a stale duplicate in the legacy location can never survive.
Only global configuration is supported: Antigravity does not read
per-project MCP files.
"""
from __future__ import annotations
import json
import logging
import shutil
from pathlib import Path
from typing import Any
from headroom import fsutil
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
logger = logging.getLogger(__name__)
def _config_candidates(home: Path) -> list[Path]:
"""Known Antigravity MCP config locations, current first."""
gemini_dir = home / ".gemini"
return [
gemini_dir / "config" / "mcp_config.json",
gemini_dir / "antigravity" / "mcp_config.json",
]
def _mcp_cache_dirs(home: Path, server_name: str) -> list[Path]:
"""Local MCP server caches Antigravity keeps per install surface."""
gemini_dir = home / ".gemini"
return [
gemini_dir / "antigravity-ide" / "mcp" / server_name,
gemini_dir / "antigravity" / "mcp" / server_name,
gemini_dir / "antigravity-cli" / "mcp" / server_name,
]
class AntigravityRegistrar(MCPRegistrar):
"""Register MCP servers with Antigravity IDE."""
name = "antigravity"
display_name = "Antigravity IDE"
def __init__(self, *, home_dir: Path | None = None) -> None:
"""Allow ``home_dir`` override for testing."""
self._home = home_dir if home_dir is not None else Path.home()
def _resolve_config(self) -> Path:
"""Return the config file to use.
The current Desktop location (``~/.gemini/config/mcp_config.json``)
is authoritative: when its parent directory exists the IDE reads
that location, so a stale legacy file must not capture the
registration. Otherwise use the first existing candidate, falling
back to the current location when none does yet.
"""
candidates = _config_candidates(self._home)
if candidates[0].parent.is_dir():
return candidates[0]
for candidate in candidates:
if candidate.exists():
return candidate
return candidates[0]
def detect(self) -> bool:
home = self._home
gemini_dir = home / ".gemini"
if (gemini_dir / "antigravity").is_dir():
return True
# The current Desktop config lives directly under ~/.gemini/config;
# an install that has not created its MCP file yet still counts.
if (gemini_dir / "config").is_dir():
return True
return any(candidate.exists() for candidate in _config_candidates(home))
def get_server(self, server_name: str) -> ServerSpec | None:
data = self._load_config()
if data is None:
return None
servers = data.get("mcpServers", {})
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:
return RegisterResult(RegisterStatus.MISMATCH, _diff_specs(existing, spec))
config_path = self._resolve_config()
data = self._load_config()
if data is None and config_path.exists():
# The file exists but would not parse: refuse to overwrite it and
# turn a hand-edited typo into total loss of the user's MCP setup.
return RegisterResult(
RegisterStatus.FAILED,
f"{config_path} is not valid JSON. Fix or move it, then re-run — "
"refusing to overwrite it and lose your MCP servers.",
)
payload: dict[str, Any] = data if isinstance(data, dict) else {}
servers = payload.get("mcpServers")
if not isinstance(servers, dict):
servers = {}
payload["mcpServers"] = servers
servers[spec.name] = _spec_to_entry(spec)
try:
config_path.parent.mkdir(parents=True, exist_ok=True)
fsutil.write_text(config_path, json.dumps(payload, indent=2) + "\n")
except OSError as exc:
return RegisterResult(RegisterStatus.FAILED, f"could not write {config_path}: {exc}")
verb = "updated" if existing is not None else "wrote"
return RegisterResult(RegisterStatus.REGISTERED, f"{verb} {spec.name} in {config_path}")
def unregister_server(self, server_name: str) -> bool:
removed = False
remaining: list[Path] = []
for config_path in _config_candidates(self._home):
if not config_path.exists():
continue
data = self._load_config(config_path)
if not isinstance(data, dict):
# Refuse to touch a file that does not parse — the same rule
# register_server follows — and keep checking the rest.
continue
servers = data.get("mcpServers")
if not isinstance(servers, dict) or server_name not in servers:
continue
del servers[server_name]
try:
fsutil.write_text(config_path, json.dumps(data, indent=2) + "\n")
except OSError:
# The write failed, so this config still registers the
# server. Record it and report failure instead of claiming a
# removal that the untouched file contradicts.
remaining.append(config_path)
continue
removed = True
if not removed:
return False
# Antigravity caches each MCP server under ~/.gemini/<surface>/mcp/;
# a removed entry keeps loading from cache until that directory goes.
# Clear it whenever at least one config entry was removed, even if a
# failed write means this still reports False below.
for cache_dir in _mcp_cache_dirs(self._home, server_name):
try:
shutil.rmtree(cache_dir)
except OSError:
pass
if remaining:
logger.warning(
"could not remove %r from %s; the server stays registered there",
server_name,
", ".join(str(path) for path in remaining),
)
return False
return True
def _load_config(self, config_path: Path | None = None) -> dict[str, Any] | None:
"""Load a config file, defaulting to the resolved one.
Returns ``None`` when the file does not exist or does not parse;
callers distinguish those cases via :meth:`_resolve_config` + exists.
"""
path = config_path if config_path is not None else self._resolve_config()
if not path.exists():
return None
try:
data = json.loads(fsutil.read_text(path))
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)
+8 -1
View File
@@ -6,6 +6,7 @@ from collections.abc import Iterable
from headroom.install.runtime import resolve_headroom_command
from .antigravity import AntigravityRegistrar
from .base import MCPRegistrar, RegisterResult, RegisterStatus, ServerSpec
from .claude import ClaudeRegistrar
from .codex import CodexRegistrar
@@ -22,7 +23,13 @@ def get_all_registrars() -> list[MCPRegistrar]:
The list grows as we add adapters for Cursor, Continue, Cline, etc.
"""
return [ClaudeRegistrar(), CodexRegistrar(), GrokRegistrar(), OpencodeRegistrar()]
return [
AntigravityRegistrar(),
ClaudeRegistrar(),
CodexRegistrar(),
GrokRegistrar(),
OpencodeRegistrar(),
]
def build_headroom_spec(proxy_url: str = DEFAULT_PROXY_URL) -> ServerSpec:
@@ -0,0 +1,11 @@
"""Antigravity IDE-specific provider helpers."""
from .install import build_install_env
from .runtime import AntigravityProxyTargets, build_proxy_targets, render_setup_lines
__all__ = [
"AntigravityProxyTargets",
"build_install_env",
"build_proxy_targets",
"render_setup_lines",
]
+15
View File
@@ -0,0 +1,15 @@
"""Antigravity IDE install-time helpers."""
from __future__ import annotations
from .runtime import build_proxy_targets
def build_install_env(*, port: int, backend: str) -> dict[str, str]:
"""Build the persistent install environment for Antigravity IDE."""
del backend
targets = build_proxy_targets(port)
return {
"OPENAI_BASE_URL": targets.openai_base_url,
"ANTHROPIC_BASE_URL": targets.anthropic_base_url,
}
+57
View File
@@ -0,0 +1,57 @@
"""Runtime helpers for Antigravity IDE integrations."""
from __future__ import annotations
from dataclasses import dataclass
from headroom.providers.claude import proxy_base_url as claude_proxy_base_url
from headroom.providers.codex import proxy_base_url as codex_proxy_base_url
from headroom.proxy.project_context import with_project_prefix
@dataclass(frozen=True)
class AntigravityProxyTargets:
"""Resolved local proxy targets shown in Antigravity setup instructions."""
openai_base_url: str
anthropic_base_url: str
def build_proxy_targets(port: int, project: str | None = None) -> AntigravityProxyTargets:
"""Build the local proxy URLs shown to Antigravity users.
``project`` (the wrap launch directory) is encoded as a ``/p/<name>``
base-URL prefix because Antigravity's custom model-provider settings
cannot send custom headers; the proxy strips it and attributes savings
per project.
"""
return AntigravityProxyTargets(
openai_base_url=with_project_prefix(codex_proxy_base_url(port), project),
anthropic_base_url=with_project_prefix(claude_proxy_base_url(port), project),
)
def render_setup_lines(port: int, project: str | None = None) -> list[str]:
"""Render the Antigravity setup instructions for the local proxy."""
targets = build_proxy_targets(port, project)
lines = [
" Headroom proxy is running. Configure Antigravity:",
"",
" Antigravity reads model endpoints from its model-provider settings,",
" not from environment variables. Add a custom OpenAI-compatible",
" model provider pointing at the proxy:",
"",
f" Base URL: {targets.openai_base_url}",
" API Key: your-openai-api-key",
"",
" Antigravity fetches the model list from GET /v1/models automatically,",
" so there is nothing else to register.",
]
if project:
lines += [
"",
f" Dashboard savings will be attributed to project '{project}'",
" (the directory this command was run from). Re-run from another",
" project directory to get that project's URL.",
]
return lines
+1 -1
View File
@@ -24,7 +24,7 @@ def default_api_url(environ: Mapping[str, str] | None = None) -> str:
if host:
if host.startswith("https://"):
return host
if ".snowflakecomputing.com" in host:
if host.endswith(".snowflakecomputing.com"):
return f"https://{host}"
return f"https://{host}.snowflakecomputing.com"
return _FALLBACK_API_URL
+10 -7
View File
@@ -15,9 +15,11 @@ PROXY_ENV_KEY = "GROK_MODELS_BASE_URL"
# process-wide OPENAI target is still api.openai.com (Claude/Codex-started).
_XAI_TOKEN_AUTH_HEADER = "x-xai-token-auth"
_XAI_TOKEN_AUTH_VALUE = "xai-grok-cli"
# UA product tokens emitted by Grok CLI 0.2.x. Matched against whitespace-split
# tokens so unrelated clients ("litellm-grok/1.0") cannot collide.
_GROK_UA_PREFIXES = ("grok-pager/", "grok-shell/")
# UA product tokens emitted by Grok clients. Matched against whitespace-split
# tokens so unrelated clients ("litellm-grok/1.0") cannot collide: "grok/" is
# how Grok Build (xAI's IDE) identifies itself, and the codebase's own client
# classification (auth_policy CLIENT_UA_MAP) already reads it that way.
_GROK_UA_PREFIXES = ("grok-pager/", "grok-shell/", "grok/")
def _header_value(headers: Mapping[str, str], name: str) -> str | None:
@@ -30,13 +32,14 @@ def _header_value(headers: Mapping[str, str], name: str) -> str | None:
def is_grok_cli_request(headers: Mapping[str, str]) -> bool:
"""Return True when inbound headers identify the official Grok CLI.
"""Return True when inbound headers identify a Grok client (CLI or Build).
Grok cannot stamp ``x-headroom-base-url`` (no custom attribution headers),
so shared-proxy routing must recognize the CLI from wire signals instead.
so shared-proxy routing must recognize it from wire signals instead.
Detection is intentionally narrow: only the official token-auth marker and
known Grok UA product tokens (prefix match on whitespace-split tokens) —
never model-id heuristics.
known Grok UA product tokens — ``grok-pager/`` / ``grok-shell/`` for the
CLI, ``grok/`` for Grok Build — prefix-matched against whitespace-split
tokens, never model-id heuristics.
"""
token_auth = _header_value(headers, _XAI_TOKEN_AUTH_HEADER)
if token_auth is not None and token_auth.strip().lower() == _XAI_TOKEN_AUTH_VALUE:
+17 -4
View File
@@ -6,6 +6,9 @@ from collections.abc import Callable
from headroom.install.models import DeploymentManifest, ManagedMutation
from headroom.providers.aider.install import build_install_env as _build_aider_install_env
from headroom.providers.antigravity.install import (
build_install_env as _build_antigravity_install_env,
)
from headroom.providers.claude.install import (
apply_provider_scope as _apply_claude_provider_scope,
)
@@ -47,9 +50,10 @@ from headroom.providers.opencode.install import (
_InstallEnvBuilder = Callable[..., dict[str, str]]
_ProviderScopeApplier = Callable[[DeploymentManifest], ManagedMutation | None]
_ProviderScopeReverter = Callable[[ManagedMutation, DeploymentManifest], None]
_ProviderScopeReverter = Callable[..., None]
_ENV_BUILDERS: dict[str, _InstallEnvBuilder] = {
"antigravity": _build_antigravity_install_env,
"claude": _build_claude_install_env,
"copilot": _build_copilot_install_env,
"codex": _build_codex_install_env,
@@ -100,7 +104,8 @@ def apply_provider_scope_mutations(manifest: DeploymentManifest) -> list[Managed
rollback_errors: list[Exception] = []
for mutation in reversed(mutations):
try:
revert_provider_scope_mutation(manifest, mutation)
revert_provider_scope_mutation(manifest, mutation, restore_backup=False)
except Exception as rollback_exc:
rollback_errors.append(rollback_exc)
else:
@@ -115,9 +120,17 @@ def apply_provider_scope_mutations(manifest: DeploymentManifest) -> list[Managed
return mutations
def revert_provider_scope_mutation(manifest: DeploymentManifest, mutation: ManagedMutation) -> None:
def revert_provider_scope_mutation(
manifest: DeploymentManifest,
mutation: ManagedMutation,
*,
restore_backup: bool = True,
) -> None:
"""Revert a provider-scope mutation via the owning provider slice."""
handlers = _PROVIDER_SCOPE_HANDLERS.get(mutation.target)
if handlers is None:
return
handlers[1](mutation, manifest)
if mutation.target == "opencode":
handlers[1](mutation, manifest, restore_backup=restore_backup)
else:
handlers[1](mutation, manifest)
@@ -12431,8 +12431,13 @@ var _proxyUrlCache = null;
function getDefaultProxyUrl() {
return _proxyUrlCache ?? process.env.HEADROOM_BASE_URL ?? "http://localhost:8787";
}
function trimTrailingSlashes(value) {
let end = value.length;
while (end > 0 && value.charCodeAt(end - 1) === 47) end--;
return value.slice(0, end);
}
function createHeadroomRetrieveTool(config2) {
const origin = config2.proxyBaseUrl.replace(/\/+$/, "");
const origin = trimTrailingSlashes(config2.proxyBaseUrl);
return {
name: "headroom_retrieve",
description: "Retrieve original uncompressed content from Headroom's compression store. Use when compressed context mentions a hash and you need the full details. Pass the hash from the compression marker (24 hex characters). Retrieval is by hash and always returns the full original content.",
@@ -12620,7 +12625,7 @@ function isExcludedHost(hostname3, excludeHosts) {
function isLlmEndpointPath(pathname) {
return pathname.endsWith("/chat/completions") || pathname.endsWith("/responses") || pathname.endsWith("/messages") || pathname.endsWith(":generateContent") || pathname.endsWith(":streamGenerateContent");
}
function shouldRoute(url2, proxy, excludeHosts) {
function isRoutableUpstream(url2, proxy, excludeHosts) {
if (url2.protocol !== "http:" && url2.protocol !== "https:") {
return false;
}
@@ -12633,7 +12638,17 @@ function shouldRoute(url2, proxy, excludeHosts) {
if (isExcludedHost(url2.hostname, excludeHosts)) {
return false;
}
return isLlmEndpointPath(url2.pathname);
return true;
}
function shouldRoute(url2, proxy, excludeHosts) {
return isRoutableUpstream(url2, proxy, excludeHosts) && isLlmEndpointPath(url2.pathname);
}
function modelBaseRoutesThroughProxy(baseUrl, proxyUrl, excludeHosts = []) {
try {
return isRoutableUpstream(new URL(baseUrl), normalizeProxyUrl(proxyUrl), excludeHosts);
} catch {
return false;
}
}
function routedUrl(upstream, proxy) {
return new URL(`${upstream.pathname}${upstream.search}`, proxy.origin);
@@ -12895,14 +12910,55 @@ function uninstallHeadroomTransport() {
}
// src/plugin.ts
var HEADROOM_PLUGIN_ID = "headroom";
function normalizeProxyUrl2(url2) {
return url2.replace(/\/+$/, "");
return trimTrailingSlashes(url2);
}
function resolveProxyUrl(options) {
return normalizeProxyUrl2(
options?.proxyUrl ?? process.env.HEADROOM_PROXY_URL ?? process.env.HEADROOM_BASE_URL ?? getDefaultProxyUrl()
);
}
function resolveExcludeHosts(options) {
return normalizeExcludeHosts(options?.excludeHosts ?? process.env[EXCLUDE_HOSTS_ENV] ?? "");
}
function headroomShellEnv(proxyUrl, project, options) {
return {
HEADROOM_ACTIVE: "1",
HEADROOM_PROXY_URL: proxyUrl,
HEADROOM_PROJECT: project,
...options.backend ? { HEADROOM_BACKEND: options.backend } : {}
};
}
function openAiWireSuffix(pkg) {
if (!pkg?.startsWith("@opencode/ai/providers/")) return void 0;
if (pkg === "@opencode/ai/providers/openai-compatible" || pkg.endsWith("/chat")) {
return "/chat/completions";
}
if (pkg.endsWith("-responses") || pkg.endsWith("/responses")) return "/responses";
return void 0;
}
function routeModelsThroughProxy(models, proxyUrl, project, excludeHosts) {
for (const model of models.list()) {
const providerID = String(model.providerID);
const modelID = String(model.id);
const provider = models.provider.get(providerID)?.provider;
const suffix = openAiWireSuffix(model.package ?? provider?.package);
const baseURL = model.settings?.baseURL ?? provider?.settings?.baseURL;
if (!suffix || typeof baseURL !== "string") continue;
if (!modelBaseRoutesThroughProxy(baseURL, proxyUrl, excludeHosts)) continue;
const upstream = new URL(baseURL);
models.update(providerID, modelID, (draft) => {
draft.settings = { ...draft.settings, baseURL: `${proxyUrl}/v1` };
draft.headers = {
...draft.headers,
[BASE_URL_HEADER]: upstream.origin,
[ORIGINAL_PATH_HEADER]: `${trimTrailingSlashes(upstream.pathname)}${suffix}`,
[PROJECT_HEADER]: project
};
});
}
}
var HeadroomPlugin = async (input, options = {}) => {
const pluginOptions = options;
const proxyUrl = resolveProxyUrl(pluginOptions);
@@ -12930,15 +12986,56 @@ var HeadroomPlugin = async (input, options = {}) => {
})
},
"shell.env": async (_input, output) => {
output.env.HEADROOM_ACTIVE = "1";
output.env.HEADROOM_PROXY_URL = proxyUrl;
output.env.HEADROOM_PROJECT = project;
if (pluginOptions.backend) {
output.env.HEADROOM_BACKEND = pluginOptions.backend;
}
Object.assign(output.env, headroomShellEnv(proxyUrl, project, pluginOptions));
}
};
};
var headroomSetup = async (ctx) => {
const pluginOptions = ctx.options;
const proxyUrl = resolveProxyUrl(pluginOptions);
const project = pluginOptions.project ?? ctx.location.project.id ?? ctx.location.directory;
const retrieveTool = createHeadroomRetrieveTool({ proxyBaseUrl: proxyUrl });
const excludeHosts = resolveExcludeHosts(pluginOptions);
const uninstallTransport = installHeadroomTransport({
proxyUrl,
project,
excludeHosts,
debug: pluginOptions.debug
});
try {
await ctx.model.transform((models) => {
routeModelsThroughProxy(models, proxyUrl, project, excludeHosts);
});
await ctx.tool.transform((editor) => {
editor.add({
name: retrieveTool.name,
description: retrieveTool.description,
input: retrieveTool.parameters,
// Offer the tool directly, like OpenCode's built-ins, rather than only
// through the code-mode `execute` tool.
options: { codemode: false },
async execute(args) {
return { content: await retrieveTool.execute(args) };
}
});
});
await ctx.shell.hook("create.before", (shell) => {
Object.assign(shell.env, headroomShellEnv(proxyUrl, project, pluginOptions));
});
} catch (error45) {
uninstallTransport();
throw error45;
}
return () => {
uninstallTransport();
};
};
var HeadroomOpenCodePlugin = {
id: HEADROOM_PLUGIN_ID,
server: HeadroomPlugin,
setup: headroomSetup
};
var plugin_default = HeadroomOpenCodePlugin;
export {
HeadroomPlugin as default
plugin_default as default
};
+101 -13
View File
@@ -73,10 +73,31 @@ def _opencode_home_dir() -> Path:
def opencode_config_paths() -> tuple[Path, Path]:
"""Return ``(config_file, backup_file)`` for OpenCode."""
"""Return the selected config and its canonical Headroom backup path."""
config_file = opencode_config_path()
backup_file = config_file.with_name(config_file.name + ".headroom-backup")
return config_file, backup_file
return config_file, config_file.with_name(config_file.name + ".headroom-backup")
def migrate_legacy_opencode_jsonc_backup(config_file: Path, backup_file: Path) -> None:
"""Migrate only legacy JSONC snapshots whose ownership is unambiguous.
Remember ambiguity on disk before a canonical snapshot can be consumed.
Otherwise a later install/remove cycle could claim an unrelated legacy
backup after the canonical backup or sibling JSON config disappears.
"""
if config_file.suffix.lower() != ".jsonc":
return
legacy_backup = config_file.with_suffix(".json.headroom-backup")
migration_block = legacy_backup.with_name(legacy_backup.name + ".jsonc-migration-blocked")
if os.path.lexists(migration_block) or not legacy_backup.exists():
return
if os.path.lexists(backup_file) or os.path.lexists(config_file.with_suffix(".json")):
# Keep the legacy bytes in place for their owner or manual recovery.
# Fail closed if this marker cannot be persisted, before any restore.
migration_block.touch(exist_ok=True)
return
backup_file.parent.mkdir(parents=True, exist_ok=True)
legacy_backup.replace(backup_file)
def snapshot_opencode_config_if_unwrapped(config_file: Path, backup_file: Path) -> None:
@@ -85,6 +106,7 @@ def snapshot_opencode_config_if_unwrapped(config_file: Path, backup_file: Path)
Guarantees that ``headroom unwrap opencode`` can restore the user's
original file byte-for-byte.
"""
migrate_legacy_opencode_jsonc_backup(config_file, backup_file)
if backup_file.exists():
return
if not config_file.exists():
@@ -123,23 +145,88 @@ def _render_provider_block(port: int) -> str:
return "\n".join(lines)
def _parse_json_loose(text: str) -> dict[str, Any]:
"""Parse JSON text, stripping line comments (// ...) when needed.
def _strip_jsonc_comments(text: str) -> str:
"""Remove JSONC line and block comments while preserving quoted strings."""
output: list[str] = []
in_string = False
escaped = False
index = 0
while index < len(text):
char = text[index]
if in_string:
output.append(char)
if escaped:
escaped = False
elif char == "\\":
escaped = True
elif char == '"':
in_string = False
elif char == '"':
in_string = True
output.append(char)
elif text.startswith("//", index):
newline = text.find("\n", index + 2)
if newline < 0:
break
output.append("\n")
index = newline
elif text.startswith("/*", index):
end = text.find("*/", index + 2)
if end < 0:
break
output.extend("\n" for char in text[index : end + 2] if char == "\n")
index = end + 1
else:
output.append(char)
index += 1
return "".join(output)
Tries standard JSON first to avoid corrupting URLs that contain ``//``.
Falls back to stripping ``//`` comments when standard parsing fails.
Two-pass: (1) remove comment-only lines, (2) strip inline trailing
comments that follow a comma.
def _strip_jsonc_trailing_commas(text: str) -> str:
"""Remove commas before JSONC closing delimiters without touching strings."""
output: list[str] = []
in_string = False
escaped = False
index = 0
while index < len(text):
char = text[index]
if in_string:
output.append(char)
if escaped:
escaped = False
elif char == "\\":
escaped = True
elif char == '"':
in_string = False
elif char == '"':
in_string = True
output.append(char)
elif char == ",":
next_index = index + 1
while next_index < len(text) and text[next_index].isspace():
next_index += 1
if next_index < len(text) and text[next_index] in "}]":
index += 1
continue
output.append(char)
else:
output.append(char)
index += 1
return "".join(output)
def _parse_json_loose(text: str) -> dict[str, Any]:
"""Parse JSON text and JSONC comments/trailing commas.
Standard JSON is tried first so URLs containing ``//`` remain untouched.
"""
try:
parsed = json.loads(text)
return parsed if isinstance(parsed, dict) else {}
except json.JSONDecodeError:
pass
# Pass 1: remove lines that are ONLY a comment.
cleaned = re.sub(r"^\s*//[^\n]*\n", "", text, flags=re.MULTILINE)
# Pass 2: remove inline trailing comments (", // comment").
cleaned = re.sub(r",\s*//[^\n]*", ",", cleaned)
cleaned = _strip_jsonc_comments(text)
cleaned = _strip_jsonc_trailing_commas(cleaned)
try:
parsed = json.loads(cleaned)
return parsed if isinstance(parsed, dict) else {}
@@ -195,6 +282,7 @@ def inject_opencode_provider_config(port: int, *, keep_user_entries: bool = Fals
try:
config_dir.mkdir(parents=True, exist_ok=True)
migrate_legacy_opencode_jsonc_backup(config_file, backup_file)
snapshot_opencode_config_if_unwrapped(config_file, backup_file)
if config_file.exists():
@@ -141,7 +141,7 @@ function isExcludedHost(hostname, excludeHosts) {
function isLlmEndpointPath(pathname) {
return pathname.endsWith("/chat/completions") || pathname.endsWith("/responses") || pathname.endsWith("/messages") || pathname.endsWith(":generateContent") || pathname.endsWith(":streamGenerateContent");
}
function shouldRoute(url, proxy, excludeHosts) {
function isRoutableUpstream(url, proxy, excludeHosts) {
if (url.protocol !== "http:" && url.protocol !== "https:") {
return false;
}
@@ -154,7 +154,10 @@ function shouldRoute(url, proxy, excludeHosts) {
if (isExcludedHost(url.hostname, excludeHosts)) {
return false;
}
return isLlmEndpointPath(url.pathname);
return true;
}
function shouldRoute(url, proxy, excludeHosts) {
return isRoutableUpstream(url, proxy, excludeHosts) && isLlmEndpointPath(url.pathname);
}
function routedUrl(upstream, proxy) {
return new URL(`${upstream.pathname}${upstream.search}`, proxy.origin);
+39 -16
View File
@@ -13,6 +13,7 @@ from headroom.install.paths import opencode_config_path
from .config import (
_inject_key_into_json,
_parse_json_loose,
migrate_legacy_opencode_jsonc_backup,
snapshot_opencode_config_if_unwrapped,
strip_opencode_headroom_blocks,
)
@@ -33,10 +34,9 @@ def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None
config_file = opencode_config_path()
config_file.parent.mkdir(parents=True, exist_ok=True)
snapshot_opencode_config_if_unwrapped(
config_file, config_file.with_suffix(".json.headroom-backup")
)
backup_file = config_file.with_name(config_file.name + ".headroom-backup")
migrate_legacy_opencode_jsonc_backup(config_file, backup_file)
snapshot_opencode_config_if_unwrapped(config_file, backup_file)
if config_file.exists():
content = fsutil.read_text(config_file)
@@ -53,7 +53,7 @@ def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None
}
data = _inject_key_into_json(data, "provider", provider)
config_file.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
config_file.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8", newline="\n")
return ManagedMutation(
target=ToolTarget.OPENCODE.value,
kind="json-block",
@@ -61,29 +61,52 @@ def apply_provider_scope(manifest: DeploymentManifest) -> ManagedMutation | None
)
def revert_provider_scope(mutation: ManagedMutation, manifest: DeploymentManifest) -> None:
"""Revert OpenCode provider-scope configuration.
def restore_opencode_backup(config_path: str, backup_path: str) -> None:
"""Restore the owned OpenCode snapshot, if it still exists."""
path = Path(config_path)
backup_file = Path(backup_path)
migrate_legacy_opencode_jsonc_backup(path, backup_file)
if backup_file.exists():
shutil.copy2(backup_file, path)
backup_file.unlink()
Restores from pre-wrap backup when available, otherwise strips the
headroom provider from the config file.
def revert_provider_scope(
mutation: ManagedMutation,
manifest: DeploymentManifest,
*,
restore_backup: bool = True,
) -> None:
"""Undo OpenCode provider-scope configuration.
Final removal restores the pre-install snapshot when available. Temporary
deactivation removes only the managed provider and retains that snapshot.
"""
del manifest
if not mutation.path:
return
path = Path(mutation.path)
backup_file = path.with_suffix(".json.headroom-backup")
if backup_file.exists():
backup_file = path.with_name(path.name + ".headroom-backup")
migrate_legacy_opencode_jsonc_backup(path, backup_file)
if restore_backup and backup_file.exists():
try:
shutil.copy2(backup_file, path)
backup_file.unlink()
restore_opencode_backup(str(path), str(backup_file))
return
except OSError:
pass
if not path.exists():
return
content = fsutil.read_text(path)
data = _parse_json_loose(content)
providers = data.get("provider")
if isinstance(providers, dict) and "headroom" in providers:
providers.pop("headroom")
if not providers:
data.pop("provider", None)
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8", newline="\n")
return
cleaned = strip_opencode_headroom_blocks(content)
if cleaned:
path.write_text(cleaned + "\n", encoding="utf-8")
else:
if cleaned != content.strip():
path.write_text(cleaned + "\n", encoding="utf-8", newline="\n")
elif not data and not content.strip():
path.unlink(missing_ok=True)
+118 -19
View File
@@ -4,9 +4,12 @@ from __future__ import annotations
import json
import os
from collections.abc import Mapping
import re
import subprocess
from collections.abc import Mapping, Sequence
from pathlib import Path
from headroom._subprocess import run
from headroom.mcp_registry.install import DEFAULT_PROXY_URL
from .config import HEADROOM_OPENCODE_PLUGIN, headroom_provider_entry
@@ -17,24 +20,122 @@ def proxy_base_url(port: int) -> str:
return f"http://127.0.0.1:{port}/v1"
def headroom_opencode_plugin_path() -> str | None:
"""Return the absolute path to the built OpenCode transport plugin, or None.
# OpenCode 2.x subcommands. Of these only the interactive ones (the root TUI,
# ``run`` and ``mini``) get ``--standalone``; the rest are management commands.
_OPENCODE_SUBCOMMANDS = frozenset(
{
"acp",
"api",
"auth",
"debug",
"mcp",
"mini",
"models",
"plugin",
"run",
"serve",
"service",
"session",
"stats",
"uninstall",
"update",
"upgrade",
}
)
_OPENCODE_STANDALONE_SUBCOMMANDS = frozenset({"run", "mini"})
OpenCode loads a plugin from an absolute file path (verified against
opencode 1.17). The plugin's loader entry exports ONLY the plugin function
(``plugins/opencode/dist/entry.opencode.js``) — the library barrel cannot
be loaded directly ("Plugin export is not a function").
# Root OpenCode 2.x options that consume the following argument. Their values
# must not be mistaken for the command position when they happen to match a
# subcommand name (e.g. `--session models`).
_OPENCODE_ROOT_VALUE_FLAGS = frozenset({"--session", "-s", "--prompt"})
def opencode_major_version(binary: str) -> int | None:
"""Return the major version of the ``opencode`` binary, or ``None``.
Parses ``opencode --version`` (1.x prints ``1.18.32``, 2.x prints
``opencode v2.0.12``). Returns ``None`` on any failure — missing binary,
non-zero exit, timeout, unparseable output — so callers treat the version
as unknown and change nothing. Never raises.
"""
try:
proc = run([binary, "--version"], capture_output=True, text=True, timeout=10)
except (OSError, subprocess.SubprocessError):
return None
if getattr(proc, "returncode", 0) != 0:
return None
output = f"{getattr(proc, 'stdout', '') or ''} {getattr(proc, 'stderr', '') or ''}"
# Not `\b`: in "v2.0.12" the "v" and "2" are both word characters.
match = re.search(r"(?<!\d)(\d+)\.\d+\.\d+", output)
major = int(match.group(1)) if match else None
if major == 0:
# Dev builds report `0.0.0-v2-<stamp>`; the channel marker carries the
# real major. Take the highest `vN` token, skipping the "v0" prefix.
channels = re.findall(r"(?<![A-Za-z0-9])v(\d+)(?![0-9])", output)
if channels:
major = max(int(channel) for channel in channels)
return major
def with_opencode_standalone(args: Sequence[str], major_version: int | None) -> tuple[str, ...]:
"""Add ``--standalone`` to an interactive OpenCode 2.x launch.
OpenCode 2.x attaches to a shared background service by default. When one
is already running, it was started with its own environment, so the
``OPENCODE_CONFIG_CONTENT`` wrap sets (Headroom provider routing and the
transport plugin) never reaches it. ``--standalone`` runs a private server
that reads this launch's environment.
Leaves ``args`` alone for OpenCode 1.x or an unknown version, when the user
already chose ``--standalone`` or ``--server``, and for management
subcommands (``models``, ``auth``, ...). The flag goes right after ``run``
or ``mini``, and first for the root TUI.
"""
args = tuple(args)
if major_version is None or major_version < 2:
return args
if any(arg in ("--standalone", "--server") or arg.startswith("--server=") for arg in args):
return args
skip_next = False
for index, arg in enumerate(args):
if skip_next:
skip_next = False
continue
if arg in _OPENCODE_ROOT_VALUE_FLAGS:
skip_next = True
continue
if arg.startswith("-"):
continue
# First positional token: the subcommand, or the root TUI's directory
# argument. Only this position decides whether to add the flag.
if arg in _OPENCODE_STANDALONE_SUBCOMMANDS:
return (*args[: index + 1], "--standalone", *args[index + 1 :])
if arg in _OPENCODE_SUBCOMMANDS:
return args
break
return ("--standalone", *args)
def headroom_opencode_plugin_path() -> str | None:
"""Return the absolute path to the built OpenCode transport plugin directory, or None.
OpenCode 2.x only loads a configured local plugin from a directory — a file
path is dropped with "configured plugin path must be a directory" — and
resolves ``<dir>/server.*`` then ``<dir>/index.*``. OpenCode 1.x resolves a
directory without ``package.json`` to its ``index.*`` as well. The
``index.js`` in each candidate directory default-exports a plugin object
carrying both the 1.x ``server`` and the 2.x ``setup`` entry points.
Resolution order:
1. ``HEADROOM_OPENCODE_PLUGIN_PATH`` env override.
2. A repo-checkout build (``plugins/opencode/dist/entry.opencode.js``) —
external-deps build, resolvable because the checkout has node_modules.
1. ``HEADROOM_OPENCODE_PLUGIN_PATH`` env override (a directory for 2.x).
2. A repo-checkout build (``plugins/opencode/dist/``) — external-deps
build, resolvable because the checkout has node_modules.
3. The self-contained bundle shipped inside the wheel
(``headroom/providers/opencode/_dist/entry.opencode.js``, built by
(``headroom/providers/opencode/_dist/``, built by
``npm run build:standalone``) — every dependency inlined, so it loads
from site-packages where no node_modules exists (verified against
opencode 1.18.5).
opencode 1.18.32 and 2.0.12).
Returns ``None`` only when none of the three exist, in which case wrap
falls back to the native-provider baseURL override, which already covers
@@ -42,15 +143,13 @@ def headroom_opencode_plugin_path() -> str | None:
"""
override = os.environ.get("HEADROOM_OPENCODE_PLUGIN_PATH", "").strip()
if override:
return override if Path(override).is_file() else None
return override if Path(override).exists() else None
# runtime.py → opencode → providers → headroom → <repo root>
repo_candidate = (
Path(__file__).resolve().parents[3] / "plugins" / "opencode" / "dist" / "entry.opencode.js"
)
if repo_candidate.is_file():
repo_candidate = Path(__file__).resolve().parents[3] / "plugins" / "opencode" / "dist"
if (repo_candidate / "index.js").is_file():
return str(repo_candidate)
packaged = Path(__file__).resolve().parent / "_dist" / "entry.opencode.js"
return str(packaged) if packaged.is_file() else None
packaged = Path(__file__).resolve().parent / "_dist"
return str(packaged) if (packaged / "index.js").is_file() else None
def build_opencode_config_content(
+4 -4
View File
@@ -43,10 +43,10 @@ logger = logging.getLogger("headroom.proxy")
def route_grok_to_xai(headers: Mapping[str, str], openai_target: str) -> bool:
"""Return True when Grok CLI traffic should be redirected to ``api.x.ai``.
"""Return True when Grok CLI / Grok Build traffic should be redirected to ``api.x.ai``.
Grok CLI cannot set ``x-headroom-base-url``, so a shared proxy started for
Claude/Codex has to recognize it from wire signals or it forwards xAI
Neither Grok client can set ``x-headroom-base-url``, so a shared proxy started for
Claude/Codex has to recognize them from wire signals or it forwards xAI
session tokens to ``api.openai.com``.
Only applies while the OpenAI target is still the default. An operator who
@@ -70,7 +70,7 @@ def route_grok_to_xai(headers: Mapping[str, str], openai_target: str) -> bool:
def openai_compatible_base_url(proxy: Any, headers: Mapping[str, str]) -> str:
"""Resolve upstream for OpenAI-compatible metadata/passthrough traffic.
Routes official Grok CLI to ``api.x.ai`` so ``GET /v1/models`` and catch-all
Routes official Grok CLI / Grok Build to ``api.x.ai`` so ``GET /v1/models`` and catch-all
passthrough succeed on a shared proxy whose OpenAI target is the default.
"""
target = api_target(proxy, "openai")
+55 -15
View File
@@ -20,11 +20,11 @@ from collections.abc import Callable, Mapping
from dataclasses import dataclass
from pathlib import Path
from typing import Literal
from urllib.parse import urlsplit
from urllib.parse import unquote, urlsplit
from headroom.providers.claude import proxy_base_url as claude_proxy_base_url
from headroom.providers.codex import proxy_base_url as codex_proxy_base_url
from headroom.proxy.project_context import with_project_prefix
from headroom.proxy.project_context import split_project_path, with_project_prefix
# How an EnvVar's URL is shaped: ``openai_v1`` ends in ``/v1`` (OpenAI-style
# clients append ``/chat/completions``); ``anthropic`` is a bare origin
@@ -114,10 +114,39 @@ def build_launch_env(
return env, display
def _origin_key(url: str) -> tuple[str, str, int | None]:
parts = urlsplit(url.strip())
host = (parts.hostname or "").lower()
return parts.scheme, "127.0.0.1" if host == "localhost" else host, parts.port
def _origin(url: str) -> tuple[str, str, int | None] | None:
"""(scheme, host, port) of ``url``; None when it cannot be an HTTP origin.
None for an unparsable URL (a non-numeric port makes ``urlsplit(...).port``
raise) or a missing scheme or host.
"""
try:
parts = urlsplit(url)
port = parts.port
except ValueError:
return None
if not parts.scheme or not parts.hostname:
return None
host = parts.hostname # urlsplit lowercases it
return parts.scheme, "127.0.0.1" if host == "localhost" else host, port
def _routable_proxy_path(url: str) -> bool:
"""True when Bob's gateway paths appended to ``url`` reach the proxy router.
Only a bare origin or one ``/p/<project>`` prefix qualifies; anything else
leaves Bob's paths under a prefix the router never sees. A ``?`` or ``#``
anywhere fails, even bare: Bob appends to the string, so the paths would
land in the query or fragment. The path is checked decoded, as the ASGI
server hands it to the router, so an encoded slash in the project segment
is the extra segment it becomes, while the ``%20`` that
``with_project_prefix`` itself emits is fine. A trailing slash is fine too:
bobshell's ``AJ()`` (verified in 2.0.5) collapses repeated slashes and
strips a trailing one before appending.
"""
if "?" in url or "#" in url:
return False
return split_project_path(unquote(urlsplit(url).path))[1] in ("", "/")
def bob_preflight(env: Mapping[str, str], settings_path: Path | None = None) -> str | None:
@@ -136,16 +165,27 @@ def bob_preflight(env: Mapping[str, str], settings_path: Path | None = None) ->
return None
if not isinstance(saved, str) or not saved.strip():
return None
# Same proxy if scheme, host and port agree; a different /p/<project>
# prefix only changes attribution, and the error below tells users to
# point gatewayUrl at the proxy, so that must not then be rejected.
if _origin_key(saved) == _origin_key(env.get("BOB_GATEWAY_URL", "")):
return None
saved = saved.strip()
saved_origin = _origin(saved)
proxy_origin = _origin(env.get("BOB_GATEWAY_URL", ""))
if saved_origin is None:
reason = "could not be parsed as an HTTP origin"
elif proxy_origin is not None and saved_origin == proxy_origin:
# Same proxy. A different /p/<project> prefix only changes attribution,
# and the message below tells users to point gatewayUrl at the proxy,
# so that must not then be rejected; an extra path segment must be.
if _routable_proxy_path(saved):
return None
reason = (
"is not a URL the proxy can route (use the bare proxy origin, optionally "
"with one /p/<project> prefix, and no query or fragment)"
)
else:
reason = "overrides BOB_GATEWAY_URL, so Bob would bypass the Headroom proxy"
return (
f"Bob's saved gatewayUrl ({saved.strip()}) overrides BOB_GATEWAY_URL, so Bob "
f"would bypass the Headroom proxy. Remove the gatewayUrl entry from {path} "
"(or set it to the proxy URL shown by this wrap) and retry. If your "
"organisation enforces a GatewayUrl policy, Bob cannot be wrapped."
f"Bob's saved gatewayUrl ({saved}) {reason}. Remove the gatewayUrl "
f"entry from {path} (or set it to the proxy URL shown by this wrap) and retry. "
"If your organisation enforces a GatewayUrl policy, Bob cannot be wrapped."
)
+516
View File
@@ -0,0 +1,516 @@
"""Context-limit guard: keep client auto-compaction working under compression.
Compression makes the usage reported back to the client reflect the
*forwarded* (compressed) request, not the client's raw transcript. Clients
whose auto-compaction keys off reported usage (Claude Code) therefore defer
compaction — the selling point — but with no floor: the raw transcript can
grow until even the compressed request exceeds the model's real context
window. From that point every turn fails with a 400 ``prompt is too long``,
the client force-compacts on each error, and the session degrades into a
compact-every-other-prompt loop (field report 2026-08-12).
Three cooperating pieces, all passthrough until the danger zone:
1. ``effective_context_limit`` — the window the forwarded request is really
subject to: the model's registry limit, raised to 1M when the client sent
a ``context-1m`` beta token, capped by any limit *learned* from an actual
``prompt is too long`` error (piece 2). Also used for compression
pressure, so 1M sessions stop being treated as 5x over budget.
2. ``note_prompt_too_long`` — parses ``prompt is too long: N tokens > M
maximum`` from upstream 400 bodies and records M per (model, 1m-beta)
key. This is how a client that *believes* 1M but whose account is capped
at 200k stops looping after exactly one error.
3. ``StreamUsageGuard`` — an SSE transformer for the streamed bytes only:
when the ``message_start`` usage total reaches ``TRIGGER_FRACTION`` of
the effective limit, it inflates the reported ``input_tokens`` — in both
``message_start`` and the final cumulative-usage ``message_delta``, which
clients merge over the former — so the client's gauge reads
``REPORT_FRACTION`` of the window the client believes in, which trips
the client's own graceful compaction before the 400 wall. Savings
metrics and telemetry parse the original upstream bytes, never the
nudged ones.
The nudged number is deliberately unmarked on the wire. It exists to be read
by the client's own compaction gauge, which is a third-party parser we do not
control, so anything added beside it is either ignored or a wire-shape change
against a client we cannot test. Nothing inside headroom needs the marker:
savings, telemetry and billing all read the original upstream bytes, never the
client-bound ones, and each rewrite emits ``event=context_guard_nudge`` with
the forwarded and reported totals for reconciliation.
Kill switch: ``HEADROOM_CONTEXT_GUARD=0``.
"""
from __future__ import annotations
import hashlib
import json
import logging
import re
import time
from typing import Any
from headroom.proxy.sse_byte_buffer_policy import find_sse_event_terminator
logger = logging.getLogger("headroom.proxy")
# Forwarded-usage fraction of the *effective* (real) limit at which the nudge
# arms. 0.90 leaves one normal turn of headroom before the hard wall.
TRIGGER_FRACTION = 0.90
# Reported-usage fraction of the *believed* limit the nudge inflates to.
# Claude Code auto-compacts around 92%; 0.95 clears that with margin.
REPORT_FRACTION = 0.95
_CONTEXT_1M_PREFIX = "context-1m"
_PROMPT_TOO_LONG_RE = re.compile(
r"prompt is too long:\s*(\d+)\s*tokens?\s*>\s*(\d+)\s*maximum", re.IGNORECASE
)
# A learned maximum is believed only inside this band. Below the floor it is
# not a context window: gateways return the same "prompt is too long: N > M"
# shape for per-request quota and per-key throttles, and one such number would
# clamp every later request on that model for the life of the process. Above
# the ceiling it cannot cap anything anyway.
_MIN_LEARNED_LIMIT = 8_000
_MAX_LEARNED_LIMIT = 10_000_000
# A learned limit is evidence about one account at one moment, not a fact about
# the model: entitlements get provisioned, gateways get repointed. It expires so
# a stale cap cannot hold a budget down forever -- the cost of expiry is at most
# one more prompt-too-long error, which is what taught it the first time.
_LEARNED_LIMIT_TTL_SECONDS = 3600.0
# (model, has_1m_beta, credential scope) -> (maximum, learned-at monotonic time).
#
# The 1m-beta dimension matters: an account with real 1M access must not inherit
# a 200k limit learned from a request that never sent the beta. The credential
# scope matters for the same reason one step out -- this dict is process-global,
# and on a shared proxy one tenant's capped key would otherwise clamp the budget
# of every other tenant on that model.
_learned_limits: dict[tuple[str, bool, str], tuple[int, float]] = {}
# Give up scanning for message_start beyond this many buffered bytes.
_MAX_GUARD_BUFFER = 256 * 1024
def context_guard_enabled() -> bool:
"""True unless explicitly disabled via HEADROOM_CONTEXT_GUARD=0."""
from headroom.proxy import runtime_env
return (runtime_env.getenv("HEADROOM_CONTEXT_GUARD", "1") or "1").strip().lower() not in (
"0",
"false",
"no",
"off",
)
def has_context_1m_beta(beta_header: str | None) -> bool:
"""True when the anthropic-beta header carries a context-1m token."""
if not beta_header:
return False
return any(
token.strip().lower().startswith(_CONTEXT_1M_PREFIX) for token in beta_header.split(",")
)
def believed_context_limit(model_limit: int, beta_header: str | None) -> int:
"""The context window the *client* thinks it has."""
if has_context_1m_beta(beta_header):
return max(model_limit, 1_000_000)
return model_limit
def credential_scope(credential: str | None) -> str:
"""A stable, non-reversible tag for the upstream credential.
Only ever a truncated digest: the credential itself is never stored, never
logged, and never compared outside this function.
"""
if not credential:
return ""
return hashlib.sha256(credential.strip().encode("utf-8", "ignore")).hexdigest()[:16]
def credential_scope_from_headers(headers: Any) -> str:
"""Credential scope for an outbound header mapping, best effort.
Never raises: an unusable header mapping just means the unscoped bucket,
which is the behaviour of a single-tenant proxy anyway.
"""
try:
for name in ("x-api-key", "authorization"):
value = headers.get(name) or headers.get(name.title())
if isinstance(value, str) and value:
return credential_scope(value)
except Exception:
return ""
return ""
def _learned_key(model: str, beta_header: str | None, scope: str) -> tuple[str, bool, str]:
return (model, has_context_1m_beta(beta_header), scope)
def _learned_limit(key: tuple[str, bool, str]) -> int | None:
"""The unexpired learned maximum for ``key``, dropping it once stale."""
entry = _learned_limits.get(key)
if entry is None:
return None
maximum, learned_at = entry
if time.monotonic() - learned_at >= _LEARNED_LIMIT_TTL_SECONDS:
_learned_limits.pop(key, None)
return None
return maximum
def effective_context_limit(
model: str,
model_limit: int,
beta_header: str | None,
*,
scope: str = "",
) -> int:
"""The window the forwarded request is actually subject to.
Optimistically the believed limit; capped by a limit learned from a real
``prompt is too long`` error for the same (model, beta, credential) shape,
and only while that lesson is still fresh.
"""
believed = believed_context_limit(model_limit, beta_header)
learned = _learned_limit(_learned_key(model, beta_header, scope))
if learned is not None:
return min(believed, learned)
return believed
def note_prompt_too_long(
model: str,
beta_header: str | None,
error_text: Any,
*,
scope: str = "",
) -> int | None:
"""Learn the real context limit from an upstream prompt-too-long error.
Returns the learned maximum, or None when there is nothing to learn.
This runs on the error path, where the client is still waiting for the real
upstream body, so it accepts whatever the body turned out to be: upstreams
and gateways send ``"message": null``, nested objects, and lists in the
slot this reads, and a diagnostic helper must not turn one of those into an
exception that replaces the error the caller was about to forward.
"""
if isinstance(error_text, bytes | bytearray):
error_text = bytes(error_text).decode("utf-8", errors="replace")
if not isinstance(error_text, str):
return None
match = _PROMPT_TOO_LONG_RE.search(error_text)
if not match:
return None
maximum = int(match.group(2))
if not _MIN_LEARNED_LIMIT <= maximum <= _MAX_LEARNED_LIMIT:
# Not a context window. Learning it would clamp the budget on a number
# that never described one.
logger.debug(
"event=context_guard_limit_out_of_band model=%s limit=%d (ignored)",
model,
maximum,
)
return None
key = _learned_key(model, beta_header, scope)
previous = _learned_limit(key)
_learned_limits[key] = (maximum, time.monotonic())
if previous != maximum:
logger.warning(
"event=context_guard_learned_limit model=%s context_1m=%s limit=%d "
"attempted=%s (client compaction gauge will be nudged near this limit)",
model,
key[1],
maximum,
match.group(1),
)
return maximum
def reset_learned_limits() -> None:
"""Test hook: clear limits learned from prompt-too-long errors."""
_learned_limits.clear()
def _data_line(payload: dict[str, Any], original: bytes) -> bytes:
"""A rewritten ``data:`` line keeping the original's CRLF ending."""
eol = b"\r" if original.endswith(b"\r") else b""
return b"data: " + json.dumps(payload, separators=(",", ":")).encode() + eol
def _sse_event_type(event: bytes) -> bytes | None:
"""The event type of one SSE frame, or ``None`` when it carries none.
Read from the ``event:`` line, not matched as a substring of the frame: a
substring match reads the *payload* too, so an assistant that writes the
words ``message_delta`` into its own reply ended the scan and lost the
final nudge.
``None`` means the frame is not part of the message protocol at all --
an SSE comment, a ``retry:`` field, the keepalives an intermediary shim
injects. Those pass through without arming or disarming anything; treating
one as an unknown event disabled the guard for the whole stream.
"""
saw_data = False
for line in event.split(b"\n"):
if line.startswith(b"event:"):
return line[len(b"event:") :].strip()
if line.startswith(b"data:"):
saw_data = True
if not saw_data:
return None
# A data frame with no event: line defaults to the type inside the payload.
for line in event.split(b"\n"):
if not line.startswith(b"data:"):
continue
try:
payload = json.loads(line[len(b"data:") :].strip())
except Exception:
return b""
value = payload.get("type") if isinstance(payload, dict) else None
return value.encode() if isinstance(value, str) else b""
return b""
def nudged_input_tokens(
usage: dict[str, Any],
*,
believed_limit: int,
effective_limit: int,
) -> int | None:
"""The inflated ``input_tokens`` for this usage, or ``None`` to leave it be.
One implementation for every client-bound surface -- ``message_start``, the
final ``message_delta``, and the non-streaming JSON body -- so a request
cannot get the raised compression budget on one path and the un-nudged
gauge on another.
"""
if believed_limit <= 0 or effective_limit <= 0:
return None
input_tokens = int(usage.get("input_tokens") or 0)
cache_read = int(usage.get("cache_read_input_tokens") or 0)
cache_creation = int(usage.get("cache_creation_input_tokens") or 0)
total = input_tokens + cache_read + cache_creation
if total < TRIGGER_FRACTION * effective_limit:
return None
target_total = int(believed_limit * REPORT_FRACTION)
if total >= target_total:
# Already reads as full to the client -- never deflate.
return None
return target_total - cache_read - cache_creation
def nudge_response_usage(
resp_json: Any,
*,
believed_limit: int,
effective_limit: int,
request_id: str = "",
) -> bool:
"""Nudge the usage of a non-streaming Anthropic message body, in place.
The buffered path raises the compression budget exactly like the streaming
one, so it has to move the client's gauge exactly like the streaming one
too; otherwise a non-streaming client gets the larger forwarded request and
none of the warning that it is near the wall.
Returns True when the body was modified.
"""
if not isinstance(resp_json, dict):
return False
usage = resp_json.get("usage")
if not isinstance(usage, dict):
return False
new_input = nudged_input_tokens(
usage, believed_limit=believed_limit, effective_limit=effective_limit
)
if new_input is None:
return False
cache_read = int(usage.get("cache_read_input_tokens") or 0)
cache_creation = int(usage.get("cache_creation_input_tokens") or 0)
forwarded_total = int(usage.get("input_tokens") or 0) + cache_read + cache_creation
usage["input_tokens"] = new_input
logger.warning(
"[%s] event=context_guard_nudge path=non_streaming forwarded_total=%d "
"effective_limit=%d reported_total=%d believed_limit=%d (nudging client to "
"compact before the prompt-too-long wall)",
request_id,
forwarded_total,
effective_limit,
new_input + cache_read + cache_creation,
believed_limit,
)
return True
class StreamUsageGuard:
"""Rewrites near-the-wall usage in the client-bound SSE bytes.
Feed every chunk headed to the client through :meth:`feed`; call
:meth:`flush` when the stream ends. The first ``message_start`` decides
whether the nudge is active. When it is not (the common case), the guard
goes inert immediately and chunks pass through untouched — steady-state
overhead is one ``if``. When it is, the guard rewrites the
``message_start`` usage AND stays armed for the final ``message_delta``:
since mid-2025 that event carries cumulative input/cache usage and
clients (verified live with Claude Code 2026-08-12) let it override the
``message_start`` values, so nudging only the first event loses the
merge. Events are released as soon as their ``\\n\\n`` terminator
arrives, so no latency is added beyond SSE's own event framing.
"""
def __init__(
self,
*,
believed_limit: int,
effective_limit: int,
request_id: str = "",
) -> None:
self._believed_limit = believed_limit
self._effective_limit = effective_limit
self._request_id = request_id
self._buf = bytearray()
self._seen_message_start = False
self._target_total: int | None = None
self._start_cache_read = 0
self._start_cache_creation = 0
# Inert immediately when limits are unusable.
self._done = believed_limit <= 0 or effective_limit <= 0
def feed(self, chunk: bytes) -> bytes:
if self._done:
return chunk
self._buf.extend(chunk)
out = bytearray()
while not self._done:
# LF or CRLF framing: a CRLF stream never contains ``\n\n`` and
# was held until the buffer cap, so it stopped streaming.
terminator = find_sse_event_terminator(self._buf)
if terminator is None:
break
end = terminator[0] + terminator[1]
event = bytes(self._buf[:end])
del self._buf[:end]
out += self._process_event(event)
# Capped on what is still unframed, so one large chunk carrying
# message_start is read before the cap can disarm the guard.
if self._done or len(self._buf) > _MAX_GUARD_BUFFER:
out += self._finish()
return bytes(out)
def flush(self) -> bytes:
"""Return any held-back bytes; the guard goes inert."""
return self._finish()
def _finish(self) -> bytes:
self._done = True
remaining = bytes(self._buf)
self._buf = bytearray()
return remaining
def _process_event(self, event: bytes) -> bytes:
event_type = _sse_event_type(event)
# Pings, comments, retry fields, keepalives: not part of the message
# protocol, so they neither arm nor disarm the guard.
if event_type is None or event_type == b"ping":
return event
if not self._seen_message_start:
# Anything data-bearing that isn't message_start (error events,
# protocol changes) ends the scan.
self._seen_message_start = True
if event_type != b"message_start":
self._done = True
return event
try:
rewritten = self._rewrite_message_start(event)
except Exception:
logger.debug("context_guard: message_start rewrite skipped", exc_info=True)
self._done = True
return event
if self._target_total is None:
# Below trigger (or already reads full): nothing to nudge.
self._done = True
return rewritten
# Armed: pass content deltas through, rewrite the final usage delta.
if event_type != b"message_delta":
return event
self._done = True
try:
return self._rewrite_message_delta(event)
except Exception:
logger.debug("context_guard: message_delta rewrite skipped", exc_info=True)
return event
def _rewrite_message_start(self, event: bytes) -> bytes:
lines = event.split(b"\n")
for i, line in enumerate(lines):
if not line.startswith(b"data:"):
continue
payload = json.loads(line[len(b"data:") :].strip())
if payload.get("type") != "message_start":
return event
usage = payload.get("message", {}).get("usage")
if not isinstance(usage, dict):
return event
cache_read = int(usage.get("cache_read_input_tokens") or 0)
cache_creation = int(usage.get("cache_creation_input_tokens") or 0)
total = int(usage.get("input_tokens") or 0) + cache_read + cache_creation
new_input = nudged_input_tokens(
usage,
believed_limit=self._believed_limit,
effective_limit=self._effective_limit,
)
if new_input is None:
return event
target_total = new_input + cache_read + cache_creation
self._target_total = target_total
self._start_cache_read = cache_read
self._start_cache_creation = cache_creation
usage["input_tokens"] = new_input
logger.warning(
"[%s] event=context_guard_nudge forwarded_total=%d effective_limit=%d "
"reported_total=%d believed_limit=%d (nudging client to compact "
"before the prompt-too-long wall)",
self._request_id,
total,
self._effective_limit,
target_total,
self._believed_limit,
)
lines[i] = _data_line(payload, line)
return b"\n".join(lines)
return event
def _rewrite_message_delta(self, event: bytes) -> bytes:
assert self._target_total is not None
lines = event.split(b"\n")
for i, line in enumerate(lines):
if not line.startswith(b"data:"):
continue
payload = json.loads(line[len(b"data:") :].strip())
if payload.get("type") != "message_delta":
return event
usage = payload.get("usage")
# A delta without cumulative input usage can't override the
# message_start values we already rewrote — leave it alone.
if not isinstance(usage, dict) or "input_tokens" not in usage:
return event
cache_read = int(usage.get("cache_read_input_tokens", self._start_cache_read) or 0)
cache_creation = int(
usage.get("cache_creation_input_tokens", self._start_cache_creation) or 0
)
new_input = self._target_total - cache_read - cache_creation
if int(usage.get("input_tokens") or 0) >= new_input:
# Never deflate.
return event
usage["input_tokens"] = new_input
lines[i] = _data_line(payload, line)
return b"\n".join(lines)
return event
+304 -29
View File
@@ -15,6 +15,7 @@ import uuid
from collections.abc import Callable
from datetime import datetime
from functools import lru_cache
from pathlib import Path
from typing import TYPE_CHECKING, Any
from urllib.parse import urlsplit
@@ -61,7 +62,7 @@ from headroom.proxy.identity import resolve_memory_identity
from headroom.proxy.image_isolation import run_image_compression_isolated
from headroom.proxy.memory_decision import MemoryDecision
from headroom.proxy.memory_query import MemoryQuery
from headroom.proxy.model_router import estimate_input_tokens
from headroom.proxy.model_router import estimate_input_tokens, request_max_tokens
from headroom.proxy.nonstream_sse_policy import should_recover_sse_reply
from headroom.proxy.outcome import RequestOutcome
from headroom.proxy.output_shaper import shaper_enabled_for, steering_allowed_for
@@ -287,6 +288,57 @@ def _looks_like_sse_response(response: httpx.Response) -> bool:
return head.startswith(b"event:") or head.startswith(b"data:")
def _dump_prefix_mismatch(request_id: str, current: list, previous: list) -> None:
"""Debug aid (HEADROOM_DEBUG_PREFIX_MISMATCH=<dir>): log where the client's
history stopped matching the last turn, and dump both sides for diffing.
The dump holds the full conversation, user content included. It is for local
debugging only: never set this on a shared or production proxy.
"""
from headroom.cache.prefix_tracker import (
_canonicalize_for_prefix_compare,
classify_history_relation,
)
rel = classify_history_relation(current, previous)
first = next(
(
i
for i in range(min(len(current), len(previous)))
if _canonicalize_for_prefix_compare(current[i])
!= _canonicalize_for_prefix_compare(previous[i])
),
None,
)
logger.info(
"[%s] prefix_mismatch_debug relation=%s first_diff_index=%s current_len=%d previous_len=%d",
request_id,
rel.kind,
first,
len(current),
len(previous),
)
try:
out = Path(os.environ["HEADROOM_DEBUG_PREFIX_MISMATCH"]) / f"{request_id}.json"
out.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
# Owner-only: the dump holds the full conversation. The mode passed to
# os.open applies only when the file is created, so tighten an existing
# file too before writing into it.
fd = os.open(out, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
# The context manager owns the descriptor from here, so it is closed
# even if tightening the mode fails.
with os.fdopen(fd, "w") as fh:
if hasattr(os, "fchmod"): # POSIX; Windows has no POSIX modes to fix
os.fchmod(fh.fileno(), 0o600)
json.dump(
{"first_diff_index": first, "current": current, "previous": previous},
fh,
default=str,
)
except Exception: # noqa: BLE001 - debug aid only
pass
class AnthropicHandlerMixin:
"""Mixin providing Anthropic API handler methods for HeadroomProxy."""
@@ -910,6 +962,7 @@ class AnthropicHandlerMixin:
model=model,
input_tokens=estimate_input_tokens(messages, body.get("tools"), body.get("system")),
has_tools=bool(body.get("tools")),
max_tokens=request_max_tokens(body),
)
logger.info("model routing decision: %s", decision.reason)
if not decision.changed:
@@ -1651,6 +1704,11 @@ class AnthropicHandlerMixin:
"output_config": body.get("output_config"),
}
)
# Resolve the request's actual provider TTL before tracker lookup:
# get_or_create may sweep expired sessions on this request.
from headroom.transforms.cold_prefix import anthropic_cache_ttl_seconds
_cc_ttl = anthropic_cache_ttl_seconds(model, original_client_messages, system_prompt)
# Resolve the tracker by conversation lineage within the session id
# (#2085): one model + system prompt spans a Claude Code session and
# all its parallel subagents, so concurrent conversations share this
@@ -1662,6 +1720,7 @@ class AnthropicHandlerMixin:
"anthropic",
messages=session_messages,
cache_affinity=cache_affinity,
cache_ttl_seconds=_cc_ttl,
)
# Snapshot lineage state once. Reusing the same pair for delta
# extraction, byte-stable replay, and breakpoint placement keeps
@@ -1695,14 +1754,8 @@ class AnthropicHandlerMixin:
# lossless whole-prefix recompaction instead of the byte-identical splice
# (the splice preserves a dead cache) and skips the overlay replay. Both are
# deterministic → the recompacted prefix re-caches byte-stable on warm turns.
from headroom.transforms.cold_prefix import (
anthropic_cache_ttl_seconds,
is_cold_prefix,
)
from headroom.transforms.cold_prefix import is_cold_prefix
# Resolve the authoritative request-level prompt-cache tier once.
# The same value drives cold-prefix handling and net-cost pricing.
_cc_ttl = anthropic_cache_ttl_seconds(model, original_client_messages, system_prompt)
_cold_recompact_active = False
if os.environ.get("HEADROOM_COLD_RECOMPACT", "").strip().lower() in (
"1",
@@ -1857,6 +1910,24 @@ class AnthropicHandlerMixin:
from headroom.proxy.helpers import COMPRESSION_TIMEOUT_SECONDS
context_limit = self.anthropic_provider.get_context_limit(model)
# Context pressure must be computed against the window the
# request is really subject to: raised to 1M when the
# client sent a context-1m beta (a 1M session is NOT 5x
# over budget), capped by a limit learned from an actual
# prompt-too-long error. See headroom/proxy/context_guard.py.
from headroom.proxy.context_guard import (
context_guard_enabled,
credential_scope_from_headers,
effective_context_limit,
)
if context_guard_enabled():
context_limit = effective_context_limit(
model,
context_limit,
headers.get("anthropic-beta"),
scope=credential_scope_from_headers(headers),
)
result = None
biases = (
self.config.hooks.compute_biases(messages, _hook_ctx)
@@ -2257,6 +2328,10 @@ class AnthropicHandlerMixin:
"[%s] Compression skipped: reason=cache_mode_prefix_mismatch",
request_id,
)
if os.environ.get("HEADROOM_DEBUG_PREFIX_MISMATCH"):
_dump_prefix_mismatch(
request_id, original_client_messages, previous_original_messages
)
optimized_messages = messages
optimized_tokens = original_tokens
elif tracker_frozen_count > 0:
@@ -2430,11 +2505,11 @@ class AnthropicHandlerMixin:
# Mechanism B: activity-based read maturation (flag-gated,
# default off). Runs after compression so read_lifecycle
# markers are respected, and before body assembly so the
# held-Read breakpoint relocation lands in the forwarded
# request. Session state (matured markers) rides on the
# prefix tracker — same affinity and TTL cleanup as the
# freeze state. Advisory: must never fail the request.
# markers are respected, and before body assembly so a
# matured marker lands in the forwarded request. Session
# state (matured markers) rides on the prefix tracker — same
# affinity and TTL cleanup as the freeze state. Advisory:
# must never fail the request.
# Bound when maturation runs, so the final accounting step below
# can charge this request's replayed-marker debt. Every earlier
# `tokens_saved` assignment is overwritten by that recount, so the
@@ -2443,10 +2518,7 @@ class AnthropicHandlerMixin:
if self.config.read_maturation and not _bypass:
try:
from headroom.config import ReadMaturationConfig
from headroom.transforms.read_maturation import (
ReadMaturationManager,
relocate_cache_breakpoint,
)
from headroom.transforms.read_maturation import ReadMaturationManager
maturation_mgr = prefix_tracker.read_maturation_manager
if maturation_mgr is None:
@@ -2466,10 +2538,7 @@ class AnthropicHandlerMixin:
frozen_message_count=frozen_message_count,
)
if maturation.replacements_applied or maturation.holding_msg_indices:
optimized_messages = relocate_cache_breakpoint(
maturation.messages,
maturation.holding_msg_indices,
)
optimized_messages = maturation.messages
optimized_tokens = tokenizer.count_messages(optimized_messages)
tokens_saved = max(0, original_tokens - optimized_tokens)
if maturation.newly_matured:
@@ -4122,6 +4191,7 @@ class AnthropicHandlerMixin:
outcome_provider=provider_name,
session_key=session_key,
server_memory_tool_names=server_memory_tool_names,
client_beta=client_anthropic_beta or "",
)
else:
# Whatever set it — the client's own ``stream: false`` or
@@ -4251,6 +4321,30 @@ class AnthropicHandlerMixin:
)
err_type = "parse_error"
if response.status_code == 400:
# Diagnostic only, and outside the parse above:
# `err_msg` is whatever upstream put in that slot
# (null, an object, a list have all been seen), and
# the client is still waiting for the real error
# body below.
try:
from headroom.proxy.context_guard import (
credential_scope_from_headers,
note_prompt_too_long,
)
note_prompt_too_long(
model,
headers.get("anthropic-beta"),
err_msg,
scope=credential_scope_from_headers(headers),
)
except Exception:
logger.debug(
f"[{request_id}] context_guard: limit learning skipped",
exc_info=True,
)
logger.warning(
f"[{request_id}] UPSTREAM_ERROR "
f"status={response.status_code} "
@@ -4631,18 +4725,62 @@ class AnthropicHandlerMixin:
request_context=memory_request_ctx,
)
if tool_results:
turn_content = resp_json.get("content") or []
answered = {result.get("tool_use_id") for result in tool_results}
unanswered = [
block
for block in turn_content
if isinstance(block, dict)
and block.get("type") == "tool_use"
and block.get("id") not in answered
]
if tool_results and unanswered:
# The continuation replays this whole turn, and
# Anthropic rejects any tool_use without a result
# (#4009). Only the client can answer its own
# tools, so the turn goes back to it, minus the
# memory calls it never declared and that already
# ran here (same rule as the streaming path, #3947).
logger.info(
f"[{request_id}] Memory: Turn also called a client "
"tool; returning the turn to the client"
)
resp_json = {
**resp_json,
"content": [
block
for block in turn_content
if not (
isinstance(block, dict)
and block.get("type") == "tool_use"
and block.get("name") in server_memory_tool_names
)
],
}
response = httpx.Response(
status_code=200,
content=json.dumps(resp_json).encode(),
headers={
key: value
for key, value in response.headers.items()
if key.lower()
not in ("content-encoding", "content-length")
},
)
elif tool_results:
# Create continuation messages
assistant_msg = {
"role": "assistant",
"content": resp_json.get("content", []),
"content": turn_content,
}
user_msg = {
"role": "user",
"content": tool_results,
}
continuation_messages = optimized_messages + [
# body["messages"], not optimized_messages: it is
# what this turn actually sent upstream.
continuation_messages = body["messages"] + [
assistant_msg,
user_msg,
]
@@ -4663,9 +4801,16 @@ class AnthropicHandlerMixin:
# Update response with continuation
resp_json = cont_response.json()
response = cont_response
logger.info(
f"[{request_id}] Memory: Tool calls handled, continuation complete"
)
if cont_response.status_code >= 400:
logger.warning(
f"[{request_id}] Memory: Continuation failed with "
f"upstream status {cont_response.status_code}"
)
else:
logger.info(
f"[{request_id}] Memory: Tool calls handled, "
"continuation complete"
)
except Exception as e:
logger.warning(
@@ -5022,7 +5167,14 @@ class AnthropicHandlerMixin:
)
if not buffered_stream_ccr:
return Response(
content=response.content,
content=self._context_guard_nudge_body(
response.content,
status_code=response.status_code,
model=model,
headers=headers,
request_id=request_id,
client_beta=client_anthropic_beta or "",
),
status_code=response.status_code,
headers=response_headers,
)
@@ -5144,6 +5296,15 @@ class AnthropicHandlerMixin:
status_code=502,
)
# This stream is resynthesized from the parsed message,
# so the streaming guard never sees it: nudge here.
self._context_guard_nudge_message(
resp_json,
model=model,
headers=headers,
request_id=request_id,
client_beta=client_anthropic_beta or "",
)
try:
sse_events = self._response_to_sse(resp_json, "anthropic")
except ValueError as sse_err:
@@ -5175,7 +5336,14 @@ class AnthropicHandlerMixin:
)
return Response(
content=response.content,
content=self._context_guard_nudge_body(
response.content,
status_code=response.status_code,
model=model,
headers=headers,
request_id=request_id,
client_beta=client_anthropic_beta or "",
),
status_code=response.status_code,
headers=response_headers,
)
@@ -5306,6 +5474,96 @@ class AnthropicHandlerMixin:
# permanently. The emit function is idempotent.
await _finalize_pre_upstream()
def _context_guard_nudge_body(
self,
content: bytes,
*,
status_code: int,
model: str,
headers: dict[str, str],
request_id: str,
client_beta: str | None = None,
) -> bytes:
"""Apply the context guard to a buffered (non-streaming) message body.
The buffered path raises the compression budget through
``effective_context_limit`` exactly like the streaming path, so it has
to move the client's gauge exactly like the streaming path too. Without
this, a non-streaming client got the larger forwarded request and none
of the warning, and walked into the prompt-too-long wall the guard
exists to keep it away from.
Returns ``content`` unchanged unless the usage genuinely needed
nudging, so byte-faithful forwarding still holds for every response
that is not near the wall.
"""
if status_code != 200 or not content:
return content
try:
payload = json.loads(content)
except Exception:
return content
if not self._context_guard_nudge_message(
payload,
model=model,
headers=headers,
request_id=request_id,
client_beta=client_beta,
):
return content
return json.dumps(payload).encode()
def _context_guard_nudge_message(
self,
payload: Any,
*,
model: str,
headers: dict[str, str],
request_id: str,
client_beta: str | None = None,
) -> bool:
"""Nudge a parsed message's usage in place; True when it changed.
Shared by the buffered body above and the buffered-CCR stream, which
resynthesizes SSE from the parsed message and so never passes through
the streaming guard. ``client_beta`` is the beta the client itself
sent (its gauge follows it; session-sticky merging can add context-1m
to the outbound header); None falls back to the outbound header.
"""
try:
from headroom.proxy.context_guard import (
believed_context_limit,
context_guard_enabled,
credential_scope_from_headers,
effective_context_limit,
nudge_response_usage,
)
if not context_guard_enabled():
return False
if not isinstance(payload, dict) or payload.get("type") != "message":
return False
model_limit = self.anthropic_provider.get_context_limit(model)
beta_header = headers.get("anthropic-beta")
return bool(
nudge_response_usage(
payload,
believed_limit=believed_context_limit(
model_limit, beta_header if client_beta is None else client_beta
),
effective_limit=effective_context_limit(
model,
model_limit,
beta_header,
scope=credential_scope_from_headers(headers),
),
request_id=request_id,
)
)
except Exception:
logger.debug(f"[{request_id}] context_guard: buffered nudge skipped", exc_info=True)
return False
def _anthropic_batch_capability_error(self) -> Response | None:
"""Return the stable client error for a Copilot batch target."""
if not is_copilot_upstream_url(self.ANTHROPIC_API_URL):
@@ -5478,6 +5736,23 @@ class AnthropicHandlerMixin:
original_tokens = 0 # Initialize before try to prevent UnboundLocalError
try:
context_limit = self.anthropic_provider.get_context_limit(model)
# Same window the streaming path computes: a batch item for a
# 1M-beta model was otherwise compressed against the registry
# limit, so identical requests got two different budgets
# depending on which endpoint they arrived through.
from headroom.proxy.context_guard import (
context_guard_enabled,
credential_scope_from_headers,
effective_context_limit,
)
if context_guard_enabled():
context_limit = effective_context_limit(
model,
context_limit,
headers.get("anthropic-beta"),
scope=credential_scope_from_headers(headers),
)
frozen_message_count = (
self._strict_previous_turn_frozen_count(original_messages, 0)
if is_cache_mode(self.config.mode)
+125 -8
View File
@@ -18,6 +18,7 @@ from headroom.proxy.handlers._debug_dump import write_upstream_error_dump
from headroom.proxy.helpers import (
RETRYABLE_OVERLOAD_STATUSES,
jitter_delay_ms,
overload_retry_is_futile,
retry_after_ms,
)
from headroom.proxy.token_counting import gemini_output_tokens
@@ -1029,6 +1030,7 @@ class StreamingMixin:
conversation_key: str | None = None,
conversation_tokens_saved: int | None = None,
server_memory_tool_names: frozenset[str] | None = None,
client_beta: str | None = None,
) -> Response | StreamingResponse:
"""Stream response with metrics tracking and memory tool handling.
@@ -1075,6 +1077,7 @@ class StreamingMixin:
conversation_key=conversation_key,
conversation_tokens_saved=conversation_tokens_saved,
server_memory_tool_names=server_memory_tool_names,
client_beta=client_beta,
)
except (Exception, asyncio.CancelledError):
self._cleanup_mid_turn_stream(session_key)
@@ -1108,6 +1111,7 @@ class StreamingMixin:
conversation_key: str | None = None,
conversation_tokens_saved: int | None = None,
server_memory_tool_names: frozenset[str] | None = None,
client_beta: str | None = None,
) -> Response | StreamingResponse:
"""Actual streaming implementation, guarded by _stream_response's cleanup wrapper."""
from fastapi.responses import Response, StreamingResponse
@@ -1128,7 +1132,63 @@ class StreamingMixin:
# of being swallowed. (#1608)
if supports_mid_turn_coalescing(client):
self._active_streams.add(session_key)
# Before the guard: its learned-limit lookup is keyed on the credential
# actually sent, the same one the 400 learning below keys on.
headers = await apply_copilot_api_auth(headers, url=url)
# Context-limit guard (see headroom/proxy/context_guard.py): rewrites
# only the client-bound message_start bytes when the forwarded request
# is near the model's real window, so clients whose auto-compaction
# keys off reported usage compact gracefully instead of looping on
# prompt-too-long 400s. Metrics below parse the original upstream
# bytes and are unaffected.
context_guard = None
if provider == "anthropic":
from headroom.proxy.context_guard import (
StreamUsageGuard,
believed_context_limit,
context_guard_enabled,
credential_scope_from_headers,
effective_context_limit,
)
try:
if context_guard_enabled():
_guard_model_limit = self.anthropic_provider.get_context_limit(model)
_guard_beta = headers.get("anthropic-beta")
_guard_scope = credential_scope_from_headers(headers)
context_guard = StreamUsageGuard(
# The client's gauge follows the beta the client
# sent; session-sticky merging can add context-1m to
# the outbound header after the client dropped it.
# None: the caller did not say, use the outbound one.
believed_limit=believed_context_limit(
_guard_model_limit,
_guard_beta if client_beta is None else client_beta,
),
effective_limit=effective_context_limit(
model, _guard_model_limit, _guard_beta, scope=_guard_scope
),
request_id=request_id,
)
except Exception:
logger.debug("context_guard setup skipped", exc_info=True)
def _guard_client_bytes(data: bytes) -> bytes:
"""Client-bound bytes through the context guard, when there is one."""
return context_guard.feed(data) if context_guard is not None else data
def _drain_context_guard() -> bytes:
"""Held-back guard bytes, once. Safe to call on any exit path."""
if context_guard is None:
return b""
try:
return context_guard.flush()
except Exception:
logger.debug("context_guard flush skipped", exc_info=True)
return b""
start_time = time.time()
# Byte-faithful forwarding (PR-A3, fixes P0-2). Resolve outbound
@@ -1248,6 +1308,11 @@ class StreamingMixin:
upstream_response.status_code in RETRYABLE_OVERLOAD_STATUSES
and self.config.retry_enabled
and attempt < retry_attempts - 1
and not overload_retry_is_futile(
upstream_response,
self.config.retry_max_delay_ms,
retries_left=retry_attempts - attempt - 1,
)
):
delay_with_jitter = retry_after_ms(
upstream_response, self.config.retry_max_delay_ms
@@ -1403,6 +1468,24 @@ class StreamingMixin:
finally:
await upstream_response.aclose()
if provider == "anthropic" and upstream_response.status_code == 400:
# Diagnostic only: whatever it makes of the body, the client
# still gets the upstream error below.
try:
from headroom.proxy.context_guard import (
credential_scope_from_headers,
note_prompt_too_long,
)
note_prompt_too_long(
model,
headers.get("anthropic-beta"),
error_content,
scope=credential_scope_from_headers(headers),
)
except Exception:
logger.debug("context_guard: limit learning skipped", exc_info=True)
if _codex_wire_debug:
_error_text: str | None = None
_error_body: Any = None
@@ -1542,11 +1625,16 @@ class StreamingMixin:
# Always stream immediately — buffering breaks
# real-time clients (LangGraph, LangChain, etc.)
if memory_filter is None:
yield chunk
else:
for frame in memory_filter.feed(chunk):
yield frame
# The context guard runs last, on exactly what the
# client receives (after the memory filter), and may
# hold back bytes only until the first complete event.
client_frames = (
[chunk] if memory_filter is None else memory_filter.feed(chunk)
)
for frame in client_frames:
guarded_frame = _guard_client_bytes(frame)
if guarded_frame:
yield guarded_frame
if _codex_wire_debug:
capture_codex_wire_debug(
@@ -1625,7 +1713,12 @@ class StreamingMixin:
)
if memory_filter is not None:
for frame in memory_filter.closing_frames():
yield frame
guarded_frame = _guard_client_bytes(frame)
if guarded_frame:
yield guarded_frame
guarded_tail = _drain_context_guard()
if guarded_tail:
yield guarded_tail
return
# Parse SSE to get response JSON
@@ -1644,7 +1737,9 @@ class StreamingMixin:
stream_state=stream_state,
request_id=request_id,
):
yield frame
guarded_frame = _guard_client_bytes(frame)
if guarded_frame:
yield guarded_frame
memory_filter = None
parsed_response = (
stream_state.pop("memory_client_message", None) or parsed_response
@@ -1687,7 +1782,20 @@ class StreamingMixin:
stream_state=stream_state,
request_id=request_id,
):
yield frame
guarded_frame = _guard_client_bytes(frame)
if guarded_frame:
yield guarded_frame
# A stream that ended before its first complete event may
# leave held-back bytes in the context guard; release them,
# after the memory filter's held tail so the final
# message_delta is still nudged. Every exit does this,
# including the error paths below: bytes the guard is holding
# are bytes the upstream already sent, and dropping them
# silently truncates the client's stream.
guarded_tail = _drain_context_guard()
if guarded_tail:
yield guarded_tail
# CCR Feedback: Record headroom_retrieve tool calls for TOIN learning.
# In streaming mode, the client handles actual retrieval, but we
@@ -1725,6 +1833,9 @@ class StreamingMixin:
except (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) as e:
logger.error(f"[{request_id}] Connection error to upstream API: {e}")
guarded_tail = _drain_context_guard()
if guarded_tail:
yield guarded_tail
error_event = public_errors.anthropic_error_body(
public_errors.classify_or_internal(e),
request_id=request_id,
@@ -1733,6 +1844,9 @@ class StreamingMixin:
yield f"event: error\ndata: {json.dumps(error_event)}\n\n".encode()
except httpx.HTTPStatusError as e:
logger.error(f"[{request_id}] HTTP error from upstream API: {e}")
guarded_tail = _drain_context_guard()
if guarded_tail:
yield guarded_tail
# Forward the upstream error response
yield e.response.content
except MemoryToolStreamOverflowError as e:
@@ -1745,6 +1859,9 @@ class StreamingMixin:
yield f"event: error\ndata: {json.dumps(error_event)}\n\n".encode()
except Exception as e:
logger.error(f"[{request_id}] Unexpected streaming error: {e}")
guarded_tail = _drain_context_guard()
if guarded_tail:
yield guarded_tail
error_event = public_errors.anthropic_error_body(
public_errors.classify_or_internal(e),
request_id=request_id,
+52 -4
View File
@@ -24,6 +24,7 @@ from dataclasses import dataclass
from logging.handlers import RotatingFileHandler
from pathlib import Path
from typing import TYPE_CHECKING, Any, Literal, cast
from urllib.parse import urlsplit, urlunsplit
from headroom import fileperms as _fileperms
from headroom import paths as _paths
@@ -368,6 +369,27 @@ def sanitize_forwarded_response_headers(
return {key: value for key, value in dict(headers).items() if key.lower() not in drop}
def _path_for_log(path: str) -> str:
"""Drop the query string, fragment and userinfo from an outbound URL.
Callers pass the full upstream URL, and Google routes put the API key in
the query (``?key=...``), so logging it verbatim writes the key to disk.
Scheme, host and path are enough to tell forwarder calls apart.
"""
try:
parts = urlsplit(path)
port = parts.port
except ValueError:
return "<unparseable>"
host = parts.hostname or ""
# ``hostname`` drops the brackets around an IPv6 literal; put them back
# so the logged URL still names the upstream that was contacted.
netloc = f"[{host}]" if ":" in host else host
if port:
netloc = f"{netloc}:{port}"
return urlunsplit((parts.scheme, netloc, parts.path, "", ""))
def log_outbound_request(
*,
forwarder: str,
@@ -383,8 +405,8 @@ def log_outbound_request(
"""Structured log line for every outbound forwarder call.
Per realignment build constraints: every cache-affecting decision is
logged. Never includes ``Authorization``/``x-api-key`` content or full
body bytes.
logged. Never includes ``Authorization``/``x-api-key`` content, the URL
query string (where Google puts ``key=``) or full body bytes.
``dropped_mutation_reasons`` records edits that byte-faithful passthrough
discarded before the wire. That is a WARNING, not a detail: the line above
@@ -396,7 +418,7 @@ def log_outbound_request(
"body_mutated=%s mutation_reasons=%s source=%s request_id=%s",
forwarder,
method,
path,
_path_for_log(path),
body_bytes_count,
"true" if body_mutated else "false",
",".join(mutation_reasons) if mutation_reasons else "",
@@ -1621,6 +1643,14 @@ def retry_after_ms(response: httpx.Response, max_ms: int) -> float | None:
exponential backoff. Anthropic sends integer seconds; the HTTP-date branch
covers other upstreams. Fails open on any parse error.
"""
seconds = _retry_after_seconds(response)
if seconds is None:
return None
return min(seconds * 1000.0, float(max_ms))
def _retry_after_seconds(response: httpx.Response) -> float | None:
"""Uncapped, non-negative ``Retry-After`` in seconds, or ``None`` if absent/unparseable."""
value = response.headers.get("retry-after")
if not value:
return None
@@ -1635,7 +1665,25 @@ def retry_after_ms(response: httpx.Response, max_ms: int) -> float | None:
seconds = (retry_at - datetime.now(retry_at.tzinfo)).total_seconds()
except (TypeError, ValueError):
return None
return min(max(seconds, 0.0) * 1000.0, float(max_ms))
return max(seconds, 0.0)
def overload_retry_is_futile(response: httpx.Response, max_ms: int, retries_left: int = 1) -> bool:
"""True when retrying a 429/529 cannot succeed within the proxy's backoff.
Upstream says so explicitly with ``x-should-retry: false``, or implicitly with a
``Retry-After`` beyond every wait still available: each of the ``retries_left``
retries sleeps at most ``max_ms``, so a reset further out than
``retries_left * max_ms`` is never reached and the retries only delay the same
error (an exhausted subscription window answers with a reset hours away).
Forwarding it at once lets the client, or a credential-rotating proxy in front,
act on it. A reset within that window stays retryable: later 429s carry a
shorter Retry-After as the reset approaches.
"""
if response.headers.get("x-should-retry", "").strip().lower() == "false":
return True
seconds = _retry_after_seconds(response)
return seconds is not None and seconds * 1000.0 > max(retries_left, 0) * max_ms
# Transient upstream statuses worth retrying with backoff: 429 (rate limit) and
+52 -5
View File
@@ -61,7 +61,25 @@ class ModelRoute:
name: str = ""
"""Human-readable label surfaced in decision logs."""
def matches(self, *, model: str, input_tokens: int, has_tools: bool) -> bool:
# Appended after the original fields so existing positional
# ``ModelRoute(...)`` calls keep their meaning.
max_output_tokens: int | None = None
"""Match only when the request's own ``max_tokens`` is <= this.
The caller's declared output budget is the best "this turn is trivial"
signal at routing time: a tiny prompt asking for 4000 output tokens may
want a long answer from the strong model. A request that declares no
``max_tokens`` does NOT match (an unbounded response is not a trivial
turn), so the rule can never widen to unbounded requests."""
def matches(
self,
*,
model: str,
input_tokens: int,
has_tools: bool,
max_tokens: int | None = None,
) -> bool:
"""True when every set condition is satisfied for this request."""
if self.from_models and model not in self.from_models:
return False
@@ -73,6 +91,10 @@ class ModelRoute:
return False
if self.min_input_tokens is not None and input_tokens < self.min_input_tokens:
return False
if self.max_output_tokens is not None and (
max_tokens is None or max_tokens > self.max_output_tokens
):
return False
# A rule whose ``to_model`` equals the current model still MATCHES (strict
# first-match-wins): it is a no-op (``changed`` is False) that short-circuits
# later rules, which lets an operator write an explicit exemption rule.
@@ -132,7 +154,14 @@ class ModelRouter:
def enabled(self) -> bool:
return self._config.enabled and bool(self._config.routes)
def select(self, *, model: str, input_tokens: int, has_tools: bool) -> ModelDecision:
def select(
self,
*,
model: str,
input_tokens: int,
has_tools: bool,
max_tokens: int | None = None,
) -> ModelDecision:
"""Return the routing decision for a request.
Never raises: on a disabled router or no matching rule, returns a
@@ -144,11 +173,14 @@ class ModelRouter:
return ModelDecision(model, model, matched=False, reason="no source model")
for route in self._config.routes:
if route.matches(model=model, input_tokens=input_tokens, has_tools=has_tools):
if route.matches(
model=model, input_tokens=input_tokens, has_tools=has_tools, max_tokens=max_tokens
):
reason = (
f"matched rule {route.name or route.to_model!r}: "
f"{model} -> {route.to_model} "
f"(input_tokens={input_tokens}, has_tools={has_tools})"
f"(input_tokens={input_tokens}, has_tools={has_tools}, "
f"max_tokens={max_tokens})"
)
return ModelDecision(
original_model=model,
@@ -187,6 +219,18 @@ def estimate_input_tokens(messages: object, tools: object = None, system: object
return 0
def request_max_tokens(body: object) -> int | None:
"""Return the request's ``max_tokens``, or ``None`` if absent or not an integer.
Booleans and non-integers are treated as absent so a malformed client value
can never satisfy a ``max_output_tokens`` bound. It never raises.
"""
value = body.get("max_tokens") if isinstance(body, dict) else None
if isinstance(value, int) and not isinstance(value, bool):
return value
return None
def _truthy(value: str | None) -> bool:
return (value or "").strip().lower() in {"1", "true", "yes", "on", "enable", "enabled"}
@@ -219,6 +263,7 @@ _ALLOWED_ROUTE_KEYS = frozenset(
"to_model",
"max_input_tokens",
"min_input_tokens",
"max_output_tokens",
"require_no_tools",
"require_tools",
"from_models",
@@ -252,7 +297,8 @@ def _route_from_entry(entry: object, index: int) -> ModelRoute | None:
max_tokens = _strict_opt_int(entry, "max_input_tokens", index)
min_tokens = _strict_opt_int(entry, "min_input_tokens", index)
if max_tokens is _INVALID or min_tokens is _INVALID:
max_output = _strict_opt_int(entry, "max_output_tokens", index)
if max_tokens is _INVALID or min_tokens is _INVALID or max_output is _INVALID:
return None
require_no_tools = entry.get("require_no_tools", False)
@@ -280,6 +326,7 @@ def _route_from_entry(entry: object, index: int) -> ModelRoute | None:
to_model=to_model,
max_input_tokens=max_tokens, # type: ignore[arg-type]
min_input_tokens=min_tokens, # type: ignore[arg-type]
max_output_tokens=max_output, # type: ignore[arg-type]
require_no_tools=require_no_tools,
require_tools=require_tools,
from_models=tuple(from_models_raw),
+2 -2
View File
@@ -312,8 +312,8 @@ class ProxyConfig:
# Read lifecycle management
read_lifecycle: bool = True
# Mechanism B: activity-based read maturation (hold fresh Reads out of
# the provider prefix cache; compress once their file quiesces).
# Mechanism B: activity-based read maturation (hold fresh Reads
# verbatim; compress once their file quiesces, unless already cached).
# Experimental — default off. CLI: --read-maturation;
# env: HEADROOM_READ_MATURATION=1
read_maturation: bool = False
+49 -25
View File
@@ -150,6 +150,7 @@ from headroom.proxy.helpers import (
_setup_file_logging, # noqa: F401
is_anthropic_auth, # noqa: F401
jitter_delay_ms,
overload_retry_is_futile,
resolve_display_provider,
retry_after_ms,
)
@@ -2658,6 +2659,11 @@ class HeadroomProxy(
if (
not self.config.retry_enabled
or attempt >= self.config.retry_max_attempts - 1
or overload_retry_is_futile(
response,
self.config.retry_max_delay_ms,
retries_left=self.config.retry_max_attempts - attempt - 1,
)
):
return response
delay_ms = retry_after_ms(
@@ -3841,6 +3847,13 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
"min_tokens_to_compress",
config.min_tokens_to_crush,
),
"exclude_tools": sorted(
{
*DEFAULT_EXCLUDE_TOOLS,
*(config.exclude_tools or ()),
*(config.protect_tool_results or ()),
}
),
"max_items_after_crush": profile_kwargs.get(
"max_items_after_crush",
config.max_items_after_crush,
@@ -4531,11 +4544,17 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
# published on host loopback, whose peer is the bridge gateway, still loads.
_dashboard_gate = [Depends(_require_operator_read_client)]
# Effective licence state of THIS proxy, resolved once: an explicit
# ProxyConfig.license_key, else HEADROOM_LICENSE or its deprecated alias.
from headroom.license_env import resolve_license_token
_dashboard_licensed = bool(config.license_key) or bool(resolve_license_token())
@app.get("/dashboard", response_class=HTMLResponse)
@app.get("/dashboard/", response_class=HTMLResponse, include_in_schema=False)
async def dashboard():
"""Serve the Headroom dashboard UI."""
return get_dashboard_html()
return get_dashboard_html(licensed=_dashboard_licensed)
# --- Dashboard settings API (loopback-gated, registry-validated) ---------
# Read/write the curated HEADROOM_* knobs the settings GUI manages. Writes
@@ -5923,7 +5942,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
limit: Maximum number of patterns to return (default 20)
Response includes for each pattern:
- hash: Truncated tool signature hash (12 chars)
- hash: Full aggregation key identifying one scoped tool pattern
- compressions: Total compression events
- retrievals: Total retrieval events
- retrieval_rate: Percentage of compressions that triggered retrieval
@@ -5947,7 +5966,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
patterns_list.append(
{
"hash": sig_hash[:12],
"hash": sig_hash,
"compressions": total_compressions,
"retrievals": total_retrievals,
"retrieval_rate": f"{retrieval_rate:.1%}",
@@ -5967,36 +5986,41 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
return patterns_list[:limit]
@app.get("/v1/toin/pattern/{hash_prefix}", dependencies=[Depends(_require_loopback)])
@app.get("/v1/toin/pattern/{hash_prefix:path}", dependencies=[Depends(_require_loopback)])
async def toin_pattern_detail(hash_prefix: str):
"""Get detailed TOIN pattern info by hash prefix.
"""Get detailed TOIN pattern info by the listed identifier or a unique prefix.
Searches for a pattern where the tool signature hash starts with
the provided prefix. Returns full pattern details if found.
Pass the ``hash`` returned by ``/v1/toin/patterns`` for an exact
lookup. A shorter aggregation-key prefix is accepted only when it
identifies one pattern; ambiguous prefixes return 409.
Path params:
hash_prefix: Beginning of the tool signature hash (min 4 chars recommended)
Response: Full pattern.to_dict() with all learned statistics and recommendations.
Response: Learned statistics without query text or field semantics.
"""
toin = get_toin()
exported = toin.export_patterns()
patterns_data = exported.get("patterns", {})
# Search for pattern with matching hash prefix
for sig_hash, pattern_dict in patterns_data.items():
if sig_hash.startswith(hash_prefix):
# Keep this response aligned with /v1/toin/patterns while
# excluding query text, field semantics, and other internal
# learning state from the detail endpoint.
return {
"compressions": pattern_dict.get("total_compressions", 0),
"retrievals": pattern_dict.get("total_retrievals", 0),
"retrieval_rate": pattern_dict.get("retrieval_rate", 0.0),
"confidence": pattern_dict.get("confidence", 0.0),
"skip_recommended": pattern_dict.get("skip_compression_recommended", False),
"optimal_max_items": pattern_dict.get("optimal_max_items", 20),
}
pattern_dict = patterns_data.get(hash_prefix)
if pattern_dict is None:
matches = (
pattern for key, pattern in patterns_data.items() if key.startswith(hash_prefix)
)
pattern_dict = next(matches, None)
if next(matches, None) is not None:
raise HTTPException(
status_code=409,
detail="Ambiguous TOIN pattern prefix; use a full hash from /v1/toin/patterns",
)
if pattern_dict is not None:
# Keep query text, field semantics, and internal learning state private.
return {
"compressions": pattern_dict.get("total_compressions", 0),
"retrievals": pattern_dict.get("total_retrievals", 0),
"retrieval_rate": pattern_dict.get("retrieval_rate", 0.0),
"confidence": pattern_dict.get("confidence", 0.0),
"skip_recommended": pattern_dict.get("skip_compression_recommended", False),
"optimal_max_items": pattern_dict.get("optimal_max_items", 20),
}
raise HTTPException(
status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}"
+3 -1
View File
@@ -18,7 +18,9 @@ def _get_jinja2_template(template_str: str):
try:
from jinja2 import Template
return Template(template_str)
# Request fields such as ``model`` come from clients; escape them so a
# crafted value cannot inject script into the report.
return Template(template_str, autoescape=True)
except ImportError as e:
raise ImportError(
"jinja2 is required for report generation. Install with: pip install headroom[reports]"
+1 -1
View File
@@ -117,7 +117,7 @@ FEATURES: dict[str, FeatureSpec] = {
name="read_maturation",
available_in=RolloutChannel.BETA,
legacy_env=("HEADROOM_READ_MATURATION",),
description="Hold-back Read maturation before provider cache entry.",
description="Hold-back Read maturation: compress a Read once its file quiesces.",
),
"bedrock_openai_prompt_caching": FeatureSpec(
name="bedrock_openai_prompt_caching",
+61 -8
View File
@@ -215,17 +215,23 @@ def detect_content_type(content: str) -> DetectionResult:
if html_result and html_result.confidence >= 0.7:
return html_result
# 4. Check for search results (file:line: format)
# Git's human-readable status is structured state, not prose. Recognize it
# before the lossy search/log/plain-text routes.
git_status_result = _try_detect_git_status(content)
if git_status_result:
return git_status_result
# 5. Check for search results (file:line: format)
search_result = _try_detect_search(content)
if search_result and search_result.confidence >= 0.6:
return search_result
# 5. Check for build/log output
# 6. Check for build/log output
log_result = _try_detect_log(content)
if log_result and log_result.confidence >= 0.5:
return log_result
# 6. Check for tabular data (CSV/TSV, markdown tables). Runs after
# 7. Check for tabular data (CSV/TSV, markdown tables). Runs after
# search/log so colon-delimited search output and freeform logs claim
# their content first; tabular requires a consistent multi-column
# delimiter or a markdown header+separator pair.
@@ -233,28 +239,75 @@ def detect_content_type(content: str) -> DetectionResult:
if tabular_result and tabular_result.confidence >= 0.6:
return tabular_result
# 7. Check for structured config (YAML/TOML/INI). Runs after tabular so
# 8. Check for structured config (YAML/TOML/INI). Runs after tabular so
# delimited data keeps its claim, and before code so config files with
# code-ish lines route to the structure-aware config compressor.
config_result = _try_detect_structured_config(content)
if config_result and config_result.confidence >= 0.6:
return config_result
# 8. Check for source code
# 9. Check for source code
code_result = _try_detect_code(content)
if code_result and code_result.confidence >= 0.5:
return code_result
# 9. Space-aligned command output (`ls -l`, `ps aux`, `docker ps`). Last,
# so it only claims content that would otherwise be plain text.
# 10. Space-aligned command output is last, only claims what would
# otherwise be plain text.
fixed_width_result = _try_detect_fixed_width(content)
if fixed_width_result:
return fixed_width_result
# 10. Fallback to plain text
# 11. Fallback to plain text
return DetectionResult(ContentType.PLAIN_TEXT, 0.5, {})
_GIT_STATUS_HEADERS = frozenset(
{
"Changes to be committed:",
"Changes not staged for commit:",
"Untracked files:",
"Unmerged paths:",
}
)
_GIT_STATUS_ENTRY_RE = re.compile(
r"^\s+(?:new file|modified|deleted|renamed|copied|typechange|"
r"both modified|both added|both deleted|added by us|deleted by us|"
r"added by them|deleted by them):\s+\S"
)
def _try_detect_git_status(content: str) -> DetectionResult | None:
"""Recognize standard ``git status`` headings and path entries narrowly."""
first = content.partition("\n")[0]
if not first.startswith(("On branch ", "HEAD detached at ", "HEAD detached from ")):
return None
lines = content.splitlines()
has_heading = False
has_path = False
section: str | None = None
for line in lines[1:]:
if line in _GIT_STATUS_HEADERS:
has_heading = True
section = line
elif line in {"", "Changes not staged for commit:", "nothing to commit"}:
continue
elif line.startswith("Your branch ") or line.startswith(" (use "):
continue
elif section == "Untracked files:" and line.startswith("\t") and line[1:].strip():
has_path = True
elif section in {
"Changes to be committed:",
"Changes not staged for commit:",
"Unmerged paths:",
} and _GIT_STATUS_ENTRY_RE.match(line):
has_path = True
if not (has_heading and has_path):
return None
return DetectionResult(ContentType.TABULAR, 1.0, {"format": "git_status"})
_JSON_DECODER = json.JSONDecoder()
# The decoded JSON value must be at least this fraction of the content for a
# WRAPPED payload to still count as JSON: a small structural wrapper (a harness

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