feat: add CLI-arg proxy toggles to settings panel

Add the remaining env-backed `headroom proxy` flags to the GUI so they
persist via settings.json: optimization on/off (HEADROOM_OPTIMIZE),
semantic cache on/off (HEADROOM_CACHE_ENABLED), rate limiting on/off
(HEADROOM_RATE_LIMIT_ENABLED), tool-result interception
(HEADROOM_INTERCEPT_ENABLED), and the embedding-server sidecar +socket.

- Wire the Click path to honor HEADROOM_OPTIMIZE/CACHE_ENABLED/
  RATE_LIMIT_ENABLED (previously only the argparse entrypoint read them);
  when unset _get_env_bool returns the True default, so behavior is
  unchanged.
- Fix HEADROOM_INTERCEPT_ENABLED readers (server + pipeline) to bool-parse
  instead of truthy os.environ.get, so "0"/"false" disable rather than
  wrongly enable; place the knob on the Compression page (startup-read, not
  a live Output Shaping knob).
- Widen runtime_env.set_overrides to Mapping[str, object] to clear a
  pre-existing mypy invariance error.

Registry 89 -> 95 fields. Docs updated; INTERCEPT_ENABLED moved out of the
live-knobs section (it is startup-read).

Author: nangsontay

docs/environment-variables.md

@@ -48,14 +48,20 @@ tables in this section, the panel now also surfaces (all restart-required): the
 Kompress engine backend, cross-turn dedup and tool-search toggles (§6); the CCR
 storage backend, Redis URL and CCR TTL (§7); stateless/offline mode, strict-TLS,
 and CORS/WebSocket origins (§5); the Vertex/Bedrock/Gemini/Cloud Code base URLs
-(above); and the Qdrant URL/host/port/API-key (§9).
+(above); the Qdrant URL/host/port/API-key (§9); the proxy mode and the core
+CLI toggles — optimization, semantic cache, and rate-limiting on/off, plus
+tool-result interception (§2 Compression); and the embedding-server sidecar (§9).
 `manifest_managed` fields are read-only on supervised Docker/service installs.
 
 ### Compression
 
 | Variable | Type | Default | Description |
 |---|---|---|---|
 | `HEADROOM_MODE` | enum | `token` | Proxy posture: `token` (compress; history may be rewritten for max savings) or `cache` (freeze prior turns for provider prefix-cache stability). |
+| `HEADROOM_OPTIMIZE` | bool | `true` | Master optimization switch. `false` = passthrough (no compression); mirrors `--no-optimize`. |
+| `HEADROOM_CACHE_ENABLED` | bool | `true` | Semantic response cache. `false` mirrors `--no-cache`. |
+| `HEADROOM_RATE_LIMIT_ENABLED` | bool | `true` | Enforce RPM/TPM limits. `false` mirrors `--no-rate-limit`. |
+| `HEADROOM_INTERCEPT_ENABLED` | bool | `false` | Enable ast-grep tool_result interceptors (Read outliner); mirrors `--intercept-tool-results`. |
 | `HEADROOM_SAVINGS_PROFILE` | enum | `coding` | Named compression posture: `agent-90`, `balanced`, `coding`, `general`. |
 | `HEADROOM_TARGET_RATIO` | float 0-1 | adaptive | Kompress keep-ratio (lower = more aggressive). |
 | `HEADROOM_DISABLE_KOMPRESS` | bool | `false` | Disable Kompress ML compression (structural compression stays on). |
@@ -164,7 +170,6 @@ restart) through the same override store.
 | `HEADROOM_VERBOSITY_AUTOTUNE` | bool | Use the AIMD verbosity controller state. |
 | `HEADROOM_OUTPUT_HOLDOUT` | float | Fraction of conversations held out for A/B measurement. |
 | `HEADROOM_INTERCEPT_READ_MIN_CHARS` | int | Min tool-output chars before the ast-grep read rewrite. |
-| `HEADROOM_INTERCEPT_ENABLED` | bool | Enable ast-grep-based tool-result interception/rewrite. |
 
 ---
 
@@ -286,6 +291,7 @@ selection* for the `HEADROOM_KOMPRESS_BACKEND` value table (`auto`, `onnx`,
 |---|---|
 | `HEADROOM_EMBEDDER_RUNTIME` | Set `pytorch_mps` to run the memory embedder on Apple GPU (requires `[pytorch-mps]` extra, MPS-availability-gated). |
 | `HEADROOM_EMBEDDING_SERVER_SOCKET` | Unix socket path for the out-of-process embedding server. |
+| `HEADROOM_EMBEDDING_SERVER` | Run a shared out-of-process embedding server sidecar across workers (saves ~600 MB RSS). GUI-editable (§2 Memory). |
 | `HEADROOM_EMBED_CONCURRENCY` | Max concurrent embedding calls. |
 | `HEADROOM_EMBED_NUM_THREADS` | Thread count for the embedding backend. |
 | `HEADROOM_QDRANT_URL` | Full Qdrant URL (e.g. hosted Qdrant Cloud). |

headroom/cli/proxy.py

@@ -1168,9 +1168,13 @@ def proxy(
         cloudcode_api_url=provider_api_overrides.cloudcode,
         vertex_api_url=provider_api_overrides.vertex,
         mode=effective_mode,
-        optimize=not no_optimize,
-        cache_enabled=not no_cache,
-        rate_limit_enabled=not no_rate_limit,
+        # CLI flag disables; else honor the env toggle (settings.json path).
+        # When the env var is unset _get_env_bool returns the True default, so
+        # behavior is identical to the historic `not no_<flag>`.
+        optimize=not no_optimize and _get_env_bool("HEADROOM_OPTIMIZE", True),
+        cache_enabled=not no_cache and _get_env_bool("HEADROOM_CACHE_ENABLED", True),
+        rate_limit_enabled=not no_rate_limit
+        and _get_env_bool("HEADROOM_RATE_LIMIT_ENABLED", True),
         rate_limit_requests_per_minute=rpm if rpm is not None else 60,
         rate_limit_tokens_per_minute=tpm if tpm is not None else 100_000,
         compress_user_messages=_get_env_bool("HEADROOM_COMPRESS_USER_MESSAGES", False),

headroom/proxy/runtime_env.py

@@ -103,7 +103,7 @@ def getenv(name: str, default: str | None = None) -> str | None:
     return os.environ.get(name, default)
 
 
-def set_overrides(values: dict[str, object]) -> dict[str, str]:
+def set_overrides(values: Mapping[str, object]) -> dict[str, str]:
     """Apply hot-reload overrides for known knobs. Returns what was applied.
 
     Unknown keys and non-string values are ignored (the endpoint is loopback-only

headroom/proxy/server.py

@@ -846,7 +846,12 @@ def _router_config_for(kompress_disabled: bool) -> ContentRouterConfig:
         self._code_aware_status = "lazy" if config.code_aware_enabled else "disabled"
 
         _intercept_prefix: list = []
-        if os.environ.get("HEADROOM_INTERCEPT_ENABLED"):
+        if os.environ.get("HEADROOM_INTERCEPT_ENABLED", "").strip().lower() in (
+            "1",
+            "true",
+            "yes",
+            "on",
+        ):
             from headroom.proxy.interceptors import ToolResultInterceptorTransform
 
             _intercept_prefix = [ToolResultInterceptorTransform()]

headroom/settings_store.py

@@ -987,6 +987,75 @@ def live(self) -> bool:
         help="API key for hosted Qdrant (e.g. Qdrant Cloud).",
         tier="advanced",
     ),
+    # --- CLI-arg toggles (env-backed; restart-required) ---------------------
+    # These mirror `headroom proxy` flags that resolve from an env var, so the
+    # settings.json -> setdefault path reaches them.
+    # Compression page
+    SettingField(
+        "HEADROOM_OPTIMIZE",
+        "optimize",
+        "Optimization enabled",
+        "Compression",
+        "bool",
+        default=True,
+        help="Master switch. Off = passthrough mode (no compression/optimization); mirrors --no-optimize.",
+        tier="basic",
+    ),
+    # Compression page (tool_result interception is a startup-read transform, so
+    # it must NOT sit on the Output Shaping page, whose fields are auto-live).
+    SettingField(
+        "HEADROOM_INTERCEPT_ENABLED",
+        "intercept_enabled",
+        "Tool-result interception",
+        "Compression",
+        "bool",
+        default=False,
+        help="Enable ast-grep tool_result interceptors (Read outliner, etc.); mirrors --intercept-tool-results.",
+        tier="advanced",
+    ),
+    # CCR & Caching page
+    SettingField(
+        "HEADROOM_CACHE_ENABLED",
+        "cache_enabled",
+        "Semantic cache enabled",
+        "CCR",
+        "bool",
+        default=True,
+        help="Semantic response cache. Off mirrors --no-cache.",
+        tier="basic",
+    ),
+    # Limits & Budget page
+    SettingField(
+        "HEADROOM_RATE_LIMIT_ENABLED",
+        "rate_limit_enabled",
+        "Rate limiting enabled",
+        "Limits",
+        "bool",
+        default=True,
+        help="Enforce RPM/TPM limits. Off mirrors --no-rate-limit.",
+        tier="basic",
+    ),
+    # Memory page (out-of-process embedding server sidecar)
+    SettingField(
+        "HEADROOM_EMBEDDING_SERVER",
+        "embedding_server",
+        "Embedding server sidecar",
+        "Memory",
+        "bool",
+        default=False,
+        help="Run a shared out-of-process embedder across workers (saves ~600 MB RSS); mirrors --embedding-server.",
+        tier="advanced",
+    ),
+    SettingField(
+        "HEADROOM_EMBEDDING_SERVER_SOCKET",
+        "embedding_server_socket",
+        "Embedding server socket",
+        "Memory",
+        "str",
+        default=None,
+        help="Unix socket path for the embedding sidecar. Default: /tmp/headroom-embed-<port>.sock.",
+        tier="advanced",
+    ),
     # --- Output Shaping (live: applied via runtime_env, no restart) ----------
     # These mirror headroom/proxy/runtime_env.py RUNTIME_ENV_KNOBS. A save
     # persists to settings.json AND hot-reloads through set_overrides(), so it

headroom/transforms/pipeline.py

@@ -144,9 +144,13 @@ def _build_default_transforms(self) -> list[Transform]:
         # users try it and compare before we make it the default.
         import os as _os
 
-        if getattr(self.config, "intercept_tool_results", False) or _os.environ.get(
-            "HEADROOM_INTERCEPT_ENABLED"
-        ):
+        _intercept_env = _os.environ.get("HEADROOM_INTERCEPT_ENABLED", "").strip().lower() in (
+            "1",
+            "true",
+            "yes",
+            "on",
+        )
+        if getattr(self.config, "intercept_tool_results", False) or _intercept_env:
             from headroom.proxy.interceptors import ToolResultInterceptorTransform
 
             transforms.append(ToolResultInterceptorTransform())

tests/test_settings_pages.py

@@ -80,6 +80,12 @@ def test_added_curated_knobs_on_expected_pages(self):
             "qdrant_host": "Memory",
             "qdrant_port": "Memory",
             "qdrant_api_key": "Memory",
+            "optimize": "Compression",
+            "intercept_enabled": "Compression",
+            "cache_enabled": "CCR & Caching",
+            "rate_limit_enabled": "Limits & Budget",
+            "embedding_server": "Memory",
+            "embedding_server_socket": "Memory",
         }
         for key, page in expected.items():
             field = settings_store._BY_KEY[key]
@@ -204,3 +210,29 @@ def test_mode_enum_roundtrip_and_apply(self, workspace):
     def test_mode_rejects_unknown_value(self, workspace):
         with pytest.raises(settings_store.SettingsValidationError):
             settings_store.save({"mode": "turbo"})
+
+
+class TestCliArgToggles:
+    def test_positive_toggles_default_enabled(self):
+        for key in ("optimize", "cache_enabled", "rate_limit_enabled"):
+            assert settings_store._BY_KEY[key].default is True, key
+
+    def test_disable_toggle_serializes_zero(self, workspace):
+        settings_store.save({"optimize": False, "cache_enabled": False})
+        settings_store.apply_to_environ(settings_store.load())
+        assert os.environ["HEADROOM_OPTIMIZE"] == "0"
+        assert os.environ["HEADROOM_CACHE_ENABLED"] == "0"
+
+    def test_intercept_and_embedding_server_are_bools(self):
+        assert settings_store._BY_KEY["intercept_enabled"].type == "bool"
+        assert settings_store._BY_KEY["intercept_enabled"].default is False
+        assert settings_store._BY_KEY["embedding_server"].default is False
+
+    def test_intercept_enabled_applies_as_one(self, workspace):
+        settings_store.save({"intercept_enabled": True})
+        settings_store.apply_to_environ(settings_store.load())
+        assert os.environ["HEADROOM_INTERCEPT_ENABLED"] == "1"
+
+    def test_embedding_server_socket_str_roundtrip(self, workspace):
+        settings_store.save({"embedding_server_socket": "/tmp/e.sock"})
+        assert settings_store.load()["embedding_server_socket"] == "/tmp/e.sock"