Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
docs(telemetry): document headroom_stack and install_mode beacon fields
Garmd81b677f8025
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 33b09f290..4e75a837b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- **Telemetry stack & install-mode identity fields** — anonymous beacon now+ reports `headroom_stack` (how Headroom is invoked: `proxy`, `wrap_claude`,+ `adapter_ts_openai`, ...) and `install_mode` (`wrapped` / `persistent` /+ `on_demand`), plus `requests_by_stack` for proxies that serve multiple+ integrations. Proxy exposes a `by_stack` bucket alongside `by_provider` /+ `by_model` on `/stats`, a matching `headroom_requests_by_stack` Prometheus+ counter, and an `X-Headroom-Stack` header honored by the FastAPI middleware.+ `headroom wrap <tool>` sets `HEADROOM_STACK=wrap_<agent>`; the TS SDK and+ all four adapters (`openai`, `anthropic`, `gemini`, `vercel-ai`) tag their+ compress calls. Schema migration:+ [`sql/upgrade_telemetry_stack_context.sql`](sql/upgrade_telemetry_stack_context.sql).- **Canonical filesystem contract** (issue #175) — new `HEADROOM_CONFIG_DIR`(default `~/.headroom/config`, read-mostly) and `HEADROOM_WORKSPACE_DIR`(default `~/.headroom`, read-write state) env vars recognized by the Pythondiff --git a/wiki/metrics.md b/wiki/metrics.mdindex 608ee9036..2b85e4ce2 100644--- a/wiki/metrics.md+++ b/wiki/metrics.md@@ -162,6 +162,10 @@ headroom_tokens_saved_total 5678900headroom_requests_by_provider{provider="anthropic"} 800headroom_requests_by_provider{provider="openai"} 434+# HELP headroom_requests_by_stack Requests by Headroom integration stack+headroom_requests_by_stack{stack="wrap_claude"} 612+headroom_requests_by_stack{stack="adapter_ts_openai"} 48+# HELP headroom_transform_timing_ms_sum Sum of transform timing in millisecondsheadroom_transform_timing_ms_sum{transform="router"} 5123.7@@ -237,6 +241,27 @@ Headroom has two separate systems:They are independent by design so you can disable the anonymous beacon while keeping OTEL metrics enabled, or vice versa.+#### Beacon identity fields++When the anonymous beacon is enabled, each report includes two identity fields+so usage can be segmented by integration surface and deployment shape:++- `headroom_stack` — how Headroom is invoked in this process. Values:+ `proxy`, `wrap_<agent>` (e.g. `wrap_claude`, `wrap_codex`),+ `adapter_<lang>_<provider>` (e.g. `adapter_ts_openai`), `mixed`+ (multi-stack proxy with no dominant caller), or `unknown`. Overridable via+ `HEADROOM_STACK`; `headroom wrap <tool>` sets it automatically.+- `install_mode` — how the proxy is deployed. Values: `wrapped` (spawned by+ `headroom wrap`), `persistent` (long-lived service on a fixed port),+ `on_demand` (short-lived direct invocation), or `unknown`.+- `requests_by_stack` — for proxies serving multiple integrations (e.g. a+ persistent proxy hit by both `wrap_claude` and a TS adapter), a per-stack+ request count dict mirroring the `headroom_requests_by_stack` counter.++Clients tag requests with an `X-Headroom-Stack` header; the proxy's FastAPI+middleware buckets these on `/v1/*`. Detection is best-effort — any failure+falls back to `"unknown"` and never breaks the proxy.+### LangfuseLangfuse fits next to this implementation as a **trace backend**, not as a metrics backend.