[dependabot]

Warning

Cooldown could not be applied because no publication date was available from the registry.

Bumps headroomlabs-ai/headroom from 35b799e to 318b431.

Changelog

Sourced from headroomlabs-ai/headroom's changelog.

Changelog

All notable changes to Headroom will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Features

• proxy: opt-in cost-aware model routing (#1706). Set HEADROOM_MODEL_ROUTER_ENABLED=1 and HEADROOM_MODEL_ROUTES (a JSON array of ordered rules) to rewrite the upstream model based on estimated input size and tool presence, complementary to content compression, e.g. send small, tool-free requests to a cheaper model. First matching rule wins, and each decision is logged with a reason so routing stays observable. Malformed rules fail open (the rule is skipped, never silently widened). Disabled by default so behavior is unchanged, skipped under x-headroom-bypass/passthrough, and currently applied on the Anthropic /v1/messages path.
• install: headroom install apply now accepts --code-aware/--no-code-aware, --intercept-tool-results, --protect-tool-results, and --bedrock-profile, mirroring the equivalent flags already on headroom proxy. Previously the only way to run a persistent deployment with these settings was to hand-edit manifest.json after the fact, which silently reverts on the next install apply.
• install: headroom install apply --env KEY=VALUE (repeatable) passes environment variables into supervised runners (macOS launchd, Linux systemd/cron, Windows services/tasks). These runners previously started with a bare environment and did not inherit the interactive shell's exports — e.g. a custom HEADROOM_WORKSPACE_DIR never reached the supervised process, so headroom install agent run looked for its manifest in the wrong location and failed outright even though install apply itself succeeded. --env values are merged into DeploymentManifest.base_env last, so they can override auto-derived defaults, and are threaded into the generated run-headroom.sh/ensure-headroom.sh (and Windows equivalents) as export/$env: lines before the exec.

Fixed

• memory: preserve semantically similar memories after memory_save. Cosine similarity now produces a consolidation hint only; it no longer schedules a background deletion, because related memories can describe distinct facts. Supersession remains available through the explicit memory_update path with a caller-supplied memory ID.
• mcp: reap orphaned headroom mcp serve processes when the launching client dies. An MCP stdio server relies on stdin EOF to shut down, but an abrupt client SIGKILL leaves the SDK's blocking stdin-reader thread wedged, so server.run() never returns; the process is reparented to init/launchd (ppid == 1) and lingers, pinning one Python interpreter + tree-sitter grammars per dead session (observed 3+ simultaneously). run_stdio() now runs a parent-death watchdog alongside server.run() that fires when the captured parent pid changes and os._exit(0)s from inside the stdio context manager, bypassing the same wedged teardown (#2185, #1761).
• cache/prefix-freeze: resolve PrefixCacheTrackers per conversation lineage within a session id, so concurrent conversations sharing a fallback id no longer thrash one tracker's frozen-prefix state (#2085). Without an x-headroom-session-id header the fallback id hashes model + system prompt — identical across a Claude Code session and every one of its parallel subagents (and any set of sessions reusing one system prompt). On the shared tracker their interleaved histories cross-contaminate the freeze state: the forwarded prefix is byte-unstable on nearly every turn and the provider prompt cache is re-written instead of read — reported as ~4.4x cache-creation inflation and a 2.5–3x net cost increase under Claude Code. SessionTrackerStore.resolve_tracker now reuses the tracker whose previous request messages are a prefix of the incoming history (client histories are append-only, so a conversation's next request always extends its previous one), starts a fresh lineage when the history diverges or was rewritten (client-side compaction — that provider cache line is gone anyway), and caps lineages per session id (PrefixFreezeConfig.max_lineages_per_session, default 32; over-cap conversations share one overflow tracker instead of evicting established lineages, so a fan-out storm past the cap degrades only its own tail — and 0 disables lineage splitting). Matching compares the original client bytes under the same canonical cross-turn equivalence as the cache-stable delta path (_canonicalize_for_prefix_compare), so a moved cache breakpoint, string<->block content sugar, or per-turn transport annotations do not read as a rewrite. Separately, the fallback id now hashes only the LEADING run of role:"system" messages: agentic clients interleave <system-reminder> turns into the history as actual system-role messages (hook output, skills lists, truncation notices), and hashing those rotated the session id mid-conversation — orphaning the prefix tracker and every other session-sticky subsystem (beta headers, CCR/memory registries, the compression cache) each time a reminder landed. Both handler paths now derive the session id and the lineage from the same original client bytes, so a turn-dependent hook rewrite cannot rotate one without the other. The session id itself never changes: session-sticky state keyed on it (beta-header stickiness, CCR and memory-tool registries, the compression cache) is untouched, and a single-conversation session keeps its exact previous behavior (the first lineage lives under the bare id).
• proxy/bedrock: wire PrefixCacheTracker updates into both Bedrock backend paths (handle_anthropic_messages's non-streaming branch in anthropic.py, and _stream_response_bedrock in streaming.py). update_from_response() was previously only called from the direct-Anthropic-API branch; both Bedrock branches returned before ever reaching it, so the tracker's state stayed permanently empty for the life of a session on any --backend bedrock deployment: extract_cache_stable_delta() always saw no previous turn, and --mode cache fell back to full unmodified passthrough on every turn instead of freezing the already-cached prefix and compressing only the new suffix.
• install: install_supervisor's macOS branch did an unconditional launchctl bootout followed by a bare bootstrap with no retry, unlike start_supervisor, which already rides out the ~15s EIO (error 5) window launchd exhibits for several seconds after a bootout. This left install apply's own reinstall path (and anything that re-applies a deployment, e.g. a future headroom doctor --fix) exposed to a race that previously required manual recovery (bootout + remove the plist + reapply). Extracted the retry loop already used by start_supervisor into a shared _bootstrap_with_retry() helper, now used by both call sites.
• proxy/savings: SavingsTracker.record_request() only appended a history point when tokens_saved > 0 (headroom's own lossy compression). In --mode cache, tokens_saved is near-always 0 by design, since the frozen prefix is byte-replayed rather than compressed to keep the provider's prompt cache warm. That silently dropped every history point on a cache-mode deployment even when cache_read_tokens/cache_savings_usd were large, making headroom-monthly-style tooling read as a total savings collapse. The guard now fires on tokens_saved OR cache_read_tokens, and the appended entry carries cache_read_tokens/cache_savings_usd so downstream consumers can show them; _normalize_history_entry defaults both fields to 0/0.0 for legacy entries that predate this change.
• litellm: vendor-specific top-level fields on /v1/chat/completions, including vLLM's chat_template_kwargs for per-request Qwen3 thinking-mode toggles, now reach OpenAI-compatible backends through LiteLLM extra_body instead of being dropped by the standard-parameter allowlist (#2128).
• cache aligner: hash the actual frozen Claude Code prefix instead of only system-message text, so stable_prefix_hash / prefix_changed now surface prompt-cache churn when a cached tool-result block changes without any system-prompt edit (#2085).
• proxy image compression: run native image compression in a spawned subprocess so an OpenCV or KleidiCV crash now fails open to the original image payload instead of taking down the whole proxy process (#2107).
• proxy/windows: support Windows selector-event-loop startup on uvicorn versions older than 0.36. Newer uvicorn accepts loop="asyncio:SelectorEventLoop" as a custom loop-factory import path, but older versions treat it as an unknown built-in loop name and raise KeyError. Windows now sets WindowsSelectorEventLoopPolicy for those older versions instead of passing an unsupported loop value (#1650, #1621).
• backends/litellm: preserve cache_control on tool_result blocks when converting Anthropic messages for the Bedrock Converse path, and complete streaming cache-stats surfacing in stream_message. Complements #1390, which preserves cache_control on the system prompt and plain text blocks but explicitly leaves tool_result out of scope — in agent loops the moving cache breakpoint lands on the tail tool_result far more often than on the system prompt, so that gap left most of the caching benefit on the table. Separately, stream_message never requested stream_options.include_usage, so LiteLLM/Bedrock never returned a usage chunk over SSE and cache_read_input_tokens/cache_creation_input_tokens always reported 0 downstream even when the prompt cache was genuinely engaged; the terminal message_delta now carries the real cache values captured from the trailing usage chunk once the stream completes.
• shared_context: SharedContext.put no longer evicts an unrelated entry when it merely updates a key that is already cached at capacity — same defect class fixed for SemanticCache in #2094.
• compress: stop mutating the caller's CompressConfig. compress(config=my_cfg, protect_recent=0, target_ratio=0.2) used to write those kwargs onto my_cfg, so a shared per-agent config was silently rewritten by every request that overrode a single option.
• paths: reject ., .., and NUL as plugin names so plugin_config_dir / plugin_workspace_dir cannot resolve outside the plugins/ sandbox. Previously plugin_config_dir("..") returned the entire config root and plugin_workspace_dir("..") returned the workspace root (savings ledger, memory DB, license cache, logs).
• backends/litellm: drop tool names over 64 chars before calling Bedrock Converse (send_message and stream_message), instead of letting the whole request 401. The Bedrock Converse API hard-rejects any tool name past that length, and Claude Code includes every globally-added claude.ai MCP connector tool in every request, even ones the user hasn't enabled locally, so a single oversized connector name broke every call through this backend. Only the bedrock provider filters; other providers forward tool names unfiltered.
• memory: annotate _EMBEDDER_CACHE as dict[tuple[str, str, str], Embedder] to match the 3-element key (backend, model, ollama_base_url). The stale 2-tuple annotation made mypy headroom fail on main, which broke the lint CI job on every open PR.
• install: include orjson in the [proxy] extra so uv tool install "headroom-ai[all]" satisfies LiteLLM OpenRouter/provider backends that import it at runtime (#2056).
• The dashboard's per-request metadata (the recent_requests / request_logs tail and the config block with upstream URLs) is gated to loopback callers via _request_is_loopback. When Headroom runs in a bridge-network container (Docker/podman, or Apple Containerization / mocker), a browser on the host reaches the proxy through the container gateway, so request.client.host is the gateway IP rather than 127.0.0.1 — the sensitive block was stripped and the "Recent Requests" table rendered empty even though the operator is local. A peer inside an operator-configured trusted-gateway CIDR (HEADROOM_PROXY_TRUSTED_GATEWAY_CIDRS, already used to sanitize X-Forwarded-*) is now treated as loopback-equivalent, while the loopback Host-header gate is retained as the DNS-rebinding defence. Opt-in and empty by default, so there is no behavior change unless the gateway CIDR is allow-listed.
• Non-finite values (NaN, Infinity) in proxy_savings.json or in upstream cost/token metadata no longer crash the proxy or corrupt the savings dashboard. SavingsTracker's numeric coercion caught only TypeError and ValueError, so int(float('inf')) raised an uncaught OverflowError while

... (truncated)

Commits

• See full diff in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

---

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

[github-actions]

This is a Dependabot digest bump of the pinned Headroom Docker image, and it is incomplete rather than incorrect in the lines it touches.

Should fix

• docker/headroom.Dockerfile bumps the anchor digest, but the matching action.yml:382 headroom_image default is not updated in this PR, even though this repository's own documentation (the Dockerfile's own header comment, docs/headroom.md, and .github/dependabot.yml) explicitly requires both to change together, and nothing automated does it for this ecosystem entry. See the inline comment for detail.

No other findings. The PR title and description are Dependabot's own standard, specific summary (exact old/new digest, scoped to /docker) and need no correction. This is a first review on this revision, so there is nothing prior to reconcile.

[github-actions]

🟠 Should fix [policy]: this bumps the digest anchor, but action.yml:382's headroom_image default still points at the old digest (sha256:35b799e9...). This file's own header comment two lines up says "when this digest bumps, update action.yml's default to match in the same PR", and docs/headroom.md's "Version pinning" section and .github/dependabot.yml's own comment on this ecosystem entry say the same thing — this ecosystem entry is deliberately not routed through the "Investigate and adapt" automation that handles the anthropics/claude-code-action upstream bump, so nothing else is going to make this edit for you.

Left out of sync, headroom_install_method: docker consumers keep pulling the old image while this anchor (never built, purely a Dependabot tracking file) claims the new one — and per action.yml:2594's own comment, a version mismatch between the two pins fails silently (a plausible-looking "0 tokens saved" rather than an error), so this is worth catching before merge rather than after.

Suggested fix: update action.yml:382's default to ghcr.io/headroomlabs-ai/headroom@sha256:318b431788f83e0c153ece2975b64b3963060c14e19d1bc4aa773f8fa5bfc00e in this same PR.

[github-actions]

🗜️ Headroom context compression

Metric	Value
Requests proxied	17
Tokens saved	28913
Aggregate savings	1.8% of all tokens sent
Average per-request compression	2.6%