Merge branch 'headroomlabs-ai:main' into main

Author: nangsontay

.github/workflows/release.yml

@@ -608,18 +608,30 @@ jobs:
                 fi
               elif command -v apt-get >/dev/null 2>&1; then
                 export DEBIAN_FRONTEND=noninteractive
-                apt-get update -qq
+                apt_retry() {
+                  apt_get_args="$*"
+                  for attempt in 1 2 3; do
+                    if apt-get "$@"; then
+                      return 0
+                    fi
+                    echo "apt-get ${apt_get_args} failed on attempt ${attempt}; refreshing package lists" >&2
+                    apt-get update -qq || true
+                    sleep $((attempt * 5))
+                  done
+                  apt-get "$@"
+                }
+                apt_retry update -qq
                 # ubuntu:20.04s default repo only ships 3.8; 3.10 lives
                 # in deadsnakes. Add it on demand. ubuntu:22.04 has
                 # 3.10/3.11 in main and 3.12 via deadsnakes.
-                apt-get install -y -qq --no-install-recommends ca-certificates software-properties-common >/dev/null
+                apt_retry install -y -qq --fix-missing --no-install-recommends ca-certificates software-properties-common >/dev/null
                 add-apt-repository -y ppa:deadsnakes/ppa >/dev/null 2>&1 || true
-                apt-get update -qq
-                apt-get install -y -qq --no-install-recommends \
+                apt_retry update -qq
+                apt_retry install -y -qq --fix-missing --no-install-recommends \
                   "python$PYTHON_VERSION" \
                   "python$PYTHON_VERSION-venv" \
                   "python$PYTHON_VERSION-distutils" >/dev/null 2>&1 \
-                || apt-get install -y -qq --no-install-recommends \
+                || apt_retry install -y -qq --fix-missing --no-install-recommends \
                   "python$PYTHON_VERSION" \
                   "python$PYTHON_VERSION-venv" >/dev/null
                 python_bin="python$PYTHON_VERSION"

CHANGELOG.md

@@ -10,9 +10,9 @@ use axum::http::{HeaderMap, HeaderName, Request, Response, StatusCode, Uri};
 use axum::response::IntoResponse;
 use axum::routing::{any, get, post};
 use axum::Router;
-use futures_util::{StreamExt as _, TryStreamExt};
 #[cfg(test)]
 use bytes::Bytes;
+use futures_util::{StreamExt as _, TryStreamExt};
 #[cfg(test)]
 use http_body_util::BodyExt;
 

crates/headroom-proxy/src/proxy.rs

@@ -71,7 +71,16 @@ When the LLM calls `headroom_retrieve`:
 3. The result is added to the conversation
 4. The API call continues automatically
 
-The client never sees CCR tool calls -- they are handled transparently by Headroom.
+The client never sees CCR tool calls on the Anthropic and OpenAI proxy paths; Headroom resolves them transparently there.
+
+<Callout type="warning" title="Current Gemini limitation">
+  Native Gemini requests do not yet run the server-side CCR response handler, so
+  `headroom_retrieve` is not resolved transparently on that path today. Google's
+  OpenAI-compatible Gemini endpoint can also return
+  `finish_reason=MALFORMED_FUNCTION_CALL` on large function-response continuations
+  after CCR retrieval. If you need fully transparent CCR resolution today, use the
+  Anthropic or OpenAI proxy paths. See [issue #2041](https://github.com/headroomlabs-ai/headroom/issues/2041).
+</Callout>
 
 ## Phase 4: Context Tracker
 
@@ -94,7 +103,7 @@ Turn 5: User asks "What about the auth middleware?"
 
 ## Retrieving originals
 
-CCR works automatically through the proxy, but you can also retrieve cached data programmatically:
+CCR works automatically on the Anthropic and OpenAI proxy paths, but you can also retrieve cached data programmatically:
 
 <Tabs groupId="lang" items={['TypeScript', 'Python']}>
 <Tab value="TypeScript">

docs/content/docs/ccr.mdx

@@ -133,6 +133,20 @@ The Python-native `headroom wrap ...` flow checks for a matching persistent depl
 
 The Docker-native host wrapper does **not** yet reuse or recover persistent profiles automatically; it still starts a fresh proxy container unless you opt into `--no-proxy`.
 
+## Claude Code VSCode extension caveat
+
+Persistent Claude deployments default to `ENABLE_TOOL_SEARCH=true` because the
+standalone Claude CLI benefits from deferred tool schemas.
+
+Anthropic's VSCode extension currently does not render those deferred-tool content
+blocks correctly through Headroom and can show `unsupported content type` in the
+webview. If your persistent install targets Claude Code inside VSCode, edit
+`~/.headroom/deploy/<profile>/manifest.json`, set
+`tool_envs.claude.ENABLE_TOOL_SEARCH` to `"false"`, then restart the deployment.
+
+Keep `ENABLE_TOOL_SEARCH=true` for the standalone `claude` CLI unless you hit the
+same renderer limitation there.
+
 ## Docker-native relationship
 
 The Docker-native host wrapper and the Python install CLI solve different layers of the runtime story:

docs/content/docs/persistent-installs.mdx

@@ -114,6 +114,64 @@ headroom proxy --codex-wire-debug
 The old LLMLingua proxy toggles are no longer part of the CLI. Headroom's proxy compression path uses ContentRouter plus the current built-in compressors, including Kompress where applicable.
 </Callout>
 
+## Savings profiles
+
+The proxy uses a **savings profile** to control compression behavior — which messages get compressed, how aggressively, and whether to prioritize provider prefix-cache stability or raw savings. Only the env var survives across related tools (`headroom wrap` passes it to the proxy it launches).
+
+```bash
+# Switch to a different profile
+HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy
+```
+
+### Built-in profiles
+
+| Profile | Target savings | proxy_mode | force_kompress | Best for |
+|---------|---------------|------------|---------------|----------|
+| `coding` (default) | ~50% (emergent) | `cache` | No | Coding agents — preserves Anthropic prefix-cache stability |
+| `agent-90` | 90% | `token` | Yes | Non-coding, cost-sensitive, or high-volume workloads |
+| `balanced` | 70% | `token` | No | General-purpose moderate compression |
+| `general` | ~60% (emergent) | `token` | No | Non-coding chat, little code in context |
+
+**`coding` (default)** — Optimizes for coding-agent workloads with Anthropic. Uses **cache mode** (`proxy_mode="cache"`): compresses only the newest delta in each turn so the provider's prefix-cache is never busted. User messages are compressed, system prompts preserved (hottest cache). Protects the 2 most recent turns verbatim. Lossless-first with lossy fallback; tool search and cross-turn dedup enabled. This is the profile that `headroom wrap` uses.
+
+**`agent-90`** — Forces ML-based (Kompress) compression with a 10% keep-ratio, ignoring the lossless path. Compresses both user and system messages. Designed for non-coding or cost-sensitive workloads where maximum compression is the goal.
+
+**`balanced`** — Token-mode compression with a 30% keep-ratio. Uses the standard lossless pipeline (does not force Kompress). Protects 4 recent turns. A safe general-purpose profile.
+
+**`general`** — Token-mode compression for non-coding conversations. No turn protection (`protect_recent=0` — nothing code-positional to preserve) and does not compress user or system messages. Uses the standard lossless pipeline.
+
+### Profiles override CLI flags
+
+A profile's `proxy_mode` setting overrides the `--mode` flag. The `coding` profile sets `proxy_mode="cache"`, so `--mode token` has **no effect** when coding is active:
+
+```bash
+# These are equivalent — coding's cache mode always wins
+headroom proxy
+headroom proxy --mode token          # --mode token is silently overridden
+```
+
+To run in token mode, switch to a profile that uses it:
+
+```bash
+HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxy --mode token
+```
+
+### Extending a profile with env overrides
+
+Profile defaults are applied only when the corresponding env var is not already set. You can start from a named profile and override individual settings:
+
+```bash
+# Start from coding but force Kompress on
+HEADROOM_SAVINGS_PROFILE=coding HEADROOM_FORCE_KOMPRESS=1 headroom proxy
+
+# Start from balanced but lower the keep-ratio
+HEADROOM_SAVINGS_PROFILE=balanced HEADROOM_TARGET_RATIO=0.15 headroom proxy
+```
+
+### Custom profiles
+
+For permanent custom profiles, see the profile definitions in `headroom/agent_savings.py`. Each profile is an `AgentSavingsProfile` dataclass with fields for compression mode, target ratio, turn protection, and pipeline toggles.
+
 ## API endpoints
 
 ### `GET /health`

docs/content/docs/proxy.mdx

@@ -183,6 +183,15 @@ When deferral is off, the proxy log also prints a one-time hint naming the fix.
 
 See [issue #746](https://github.com/chopratejas/headroom/issues/746) for the full analysis.
 
+<Callout type="warning" title="Claude Code VSCode extension caveat">
+  Anthropic's VSCode extension webview does not currently render the deferred-tool
+  content blocks that `ENABLE_TOOL_SEARCH=true` enables through Headroom. Tool
+  results can show up as `unsupported content type` in the extension even though
+  the standalone `claude` CLI works correctly. If you use Claude Code inside
+  VSCode, set `ENABLE_TOOL_SEARCH=false` for that target and restart the Headroom
+  deployment. See [issue #2028](https://github.com/headroomlabs-ai/headroom/issues/2028).
+</Callout>
+
 ## Remote Control unavailable through custom ANTHROPIC_BASE_URL
 
 **Symptom**: When Claude Code runs with `ANTHROPIC_BASE_URL` set to a custom host (for example, Headroom), the Remote Control menu is absent.

docs/content/docs/troubleshooting.mdx

@@ -25,6 +25,28 @@
 
 logger = logging.getLogger(__name__)
 
+_OPENAI_STANDARD_PARAMS = (
+    "max_tokens",
+    "temperature",
+    "top_p",
+    "stop",
+    "tools",
+    "tool_choice",
+    "response_format",
+    "seed",
+    "n",
+)
+
+_OPENAI_CONSUMED_BODY_KEYS = frozenset(
+    {
+        "model",
+        "messages",
+        "stream",
+        "stream_options",
+        *_OPENAI_STANDARD_PARAMS,
+    }
+)
+
 # litellm calls `dotenv.load_dotenv()` during its own import, which loads
 # the project `.env` into `os.environ`. We don't want that side effect —
 # importing a backend module should not silently leak API keys into the
@@ -139,6 +161,17 @@ def _build_bedrock_fallback_map(region: str) -> dict[str, str]:
     return {name: f"bedrock/{prefix}.{model_id}" for name, model_id in _CLAUDE_MODELS}
 
 
+def _build_openai_extra_body(body: dict[str, Any]) -> dict[str, Any]:
+    """Return unconsumed top-level OpenAI request fields for vendor passthrough."""
+    return {
+        key: value
+        for key, value in body.items()
+        if key not in _OPENAI_CONSUMED_BODY_KEYS
+        and not key.startswith("x-headroom-")
+        and not key.startswith("x_headroom_")
+    }
+
+
 def _fetch_bedrock_inference_profiles(
     region: str | None, profile_name: str | None = None
 ) -> dict[str, str]:
@@ -1177,20 +1210,14 @@ async def send_openai_message(
             }
 
             # Pass through OpenAI parameters
-            for param in [
-                "max_tokens",
-                "temperature",
-                "top_p",
-                "stop",
-                "tools",
-                "tool_choice",
-                "response_format",
-                "seed",
-                "n",
-            ]:
+            for param in _OPENAI_STANDARD_PARAMS:
                 if param in body:
                     kwargs[param] = body[param]
 
+            extra_body = _build_openai_extra_body(body)
+            if extra_body:
+                kwargs["extra_body"] = extra_body
+
             # Provider-specific region config
             if self.region:
                 if self.provider == "bedrock":
@@ -1352,23 +1379,17 @@ async def stream_openai_message(
                 "stream": True,
             }
 
-            for param in [
-                "max_tokens",
-                "temperature",
-                "top_p",
-                "stop",
-                "tools",
-                "tool_choice",
-                "response_format",
-                "seed",
-                "n",
-            ]:
+            for param in _OPENAI_STANDARD_PARAMS:
                 if param in body:
                     kwargs[param] = body[param]
 
             if "stream_options" in body:
                 kwargs["stream_options"] = body["stream_options"]
 
+            extra_body = _build_openai_extra_body(body)
+            if extra_body:
+                kwargs["extra_body"] = extra_body
+
             # Provider-specific region config
             if self.region:
                 if self.provider == "bedrock":

headroom/backends/litellm.py

@@ -742,10 +742,18 @@ def __init__(self, config: DetectorConfig):
             from headroom.models.ml_models import MLModelRegistry
 
             self._model = MLModelRegistry.get_sentence_transformer(config.embedding_model)
-            # Pre-compute exemplar embeddings
+            # Pre-compute exemplar embeddings. normalize_embeddings=True is
+            # required: detect() scores sentences with np.dot against these and
+            # compares to semantic_threshold (a 0-1 cosine value). Without
+            # normalization sentence_transformers returns raw vectors (norm
+            # ~5-15), so the dot product is an unbounded inner product, not a
+            # cosine similarity — nearly every sentence would clear the 0.7
+            # threshold and be misflagged as dynamic. Matches the siblings in
+            # prediction/feature_extractor.py and memory/adapters/embedders.py.
             self._exemplar_embeddings = self._model.encode(
                 self.DYNAMIC_EXEMPLARS,
                 convert_to_numpy=True,
+                normalize_embeddings=True,
             )
         except ImportError:
             self._load_error = (
@@ -812,9 +820,13 @@ def detect(
         if self._exemplar_embeddings is None:
             return [], "exemplar embeddings not initialized"
 
+        # normalize_embeddings=True so np.dot below is a true cosine similarity
+        # in [-1, 1], comparable to semantic_threshold; must match the exemplar
+        # encoding above (both normalized or the dot product is meaningless).
         sentence_embeddings = self._model.encode(
             sentence_texts,
             convert_to_numpy=True,
+            normalize_embeddings=True,
         )
 
         similarities = np.dot(sentence_embeddings, self._exemplar_embeddings.T)

headroom/cache/dynamic_detector.py

@@ -322,11 +322,18 @@ def _ensure_codex_provider(path: Path, port: int) -> None:
         f"{_CODEX_PROVIDER_MARKER_END}"
     )
     content = path.read_text(encoding="utf-8") if path.exists() else ""
-    # init owns model_provider/openai_base_url: drop any prior assignment (any
-    # value, including one an older version mis-scoped under a table) so we
-    # replace it instead of emitting a duplicate top-level key (#260).
-    content = re.sub(r"(?m)^[ \t]*model_provider[ \t]*=.*\r?\n", "", content)
-    content = re.sub(r"(?m)^[ \t]*openai_base_url[ \t]*=.*\r?\n", "", content)
+    # init owns the ROOT-level model_provider/openai_base_url: drop any prior
+    # root assignment so we replace it instead of emitting a duplicate top-level
+    # key (#260). Scope the strip to the document root (everything before the
+    # first table header) -- these keys also appear legitimately inside
+    # [profiles.*] tables as per-profile overrides, and stripping them there
+    # silently reroutes the user's profiles to the injected "headroom" default.
+    _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]*=.*\r?\n", "", root)
+    root = re.sub(r"(?m)^[ \t]*openai_base_url[ \t]*=.*\r?\n", "", root)
+    content = root + rest
     # The provider block carries top-level keys (model_provider, openai_base_url),
     # so it must land at the document root rather than after a trailing table (#260).
     content = _replace_marker_block(
@@ -469,24 +476,43 @@ def _ensure_codex_feature_flag(path: Path) -> None:
 def _ensure_codex_hooks(path: Path, profile: str) -> None:
     logger.debug("ensure codex hooks: %s (profile=%s)", path, profile)
     command = f"{_hook_command('--profile', profile)} --marker {_CODEX_HOOK_MARKER}"
-    payload = {
-        "hooks": {
-            "SessionStart": [
-                {
-                    "matcher": "startup|resume",
-                    "hooks": [{"type": "command", "command": command, "timeout": 15}],
-                }
-            ],
-            "PreToolUse": [
-                {
-                    "matcher": "Bash",
-                    "hooks": [{"type": "command", "command": command, "timeout": 15}],
-                }
-            ],
-        }
-    }
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    # Read-merge-write rather than overwrite: the previous version wrote a fresh
+    # payload wholesale, destroying any user-managed hooks (and other top-level
+    # keys) in codex hooks.json. Merge per event and dedup on the Headroom
+    # marker, matching _ensure_claude_hooks / _ensure_copilot_hooks.
+    payload = _json_file(path)
+    hooks = dict(payload.get("hooks") or {}) if isinstance(payload.get("hooks"), dict) else {}
+    for event, matcher in (
+        ("SessionStart", "startup|resume"),
+        ("PreToolUse", "Bash"),
+    ):
+        entries = list(hooks.get(event) or []) if isinstance(hooks.get(event), list) else []
+        retained: list[dict[str, Any]] = []
+        for entry in entries:
+            if not isinstance(entry, dict):
+                retained.append(entry)
+                continue
+            hook_items = entry.get("hooks")
+            if not isinstance(hook_items, list):
+                retained.append(entry)
+                continue
+            has_headroom = any(
+                isinstance(item, dict)
+                and item.get("command")
+                and _CODEX_HOOK_MARKER in str(item.get("command"))
+                for item in hook_items
+            )
+            if not has_headroom:
+                retained.append(entry)
+        retained.append(
+            {
+                "matcher": matcher,
+                "hooks": [{"type": "command", "command": command, "timeout": 15}],
+            }
+        )
+        hooks[event] = retained
+    payload["hooks"] = hooks
+    _write_json(path, payload)
 
 
 def _manifest_changed(