Merge pull request #23 from nangsontay/feat/setting-add

Feat/setting add

Author: nangsontay

docs/environment-variables.md

@@ -1183,9 +1183,12 @@ 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/cli/proxy.py

@@ -469,7 +469,7 @@ <h3 class="mb-3 text-sm font-medium text-gray-300">Live Activity</h3>
                 </div>
 
                 <!-- Prefix Cache Impact: current process only -->
-                <template x-if="cacheSessionActive">
+                <template x-if="hasPrefixCacheImpact">
                     <div class="bg-surface rounded-lg p-4 border border-border mb-6">
                         <div class="flex justify-between items-center mb-3">
                             <div class="text-sm font-medium text-gray-300">Prefix Cache Impact</div>
@@ -516,6 +516,13 @@ <h3 class="mb-3 text-sm font-medium text-gray-300">Live Activity</h3>
                                 <div class="text-xs text-gray-500" x-show="!cacheSessionActive">no activity since restart</div>
                             </div>
                         </div>
+                        <template x-if="lifetimeCacheReadTokens > 0 || lifetimeCacheSavingsUsd > 0">
+                            <div class="rounded-lg border border-emerald-500/20 bg-emerald-500/5 p-3 mb-4">
+                                <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Cache Reads (lifetime)</div>
+                                <div class="text-2xl font-light tabular-nums text-emerald-400" x-text="formatNumber(lifetimeCacheReadTokens)"></div>
+                                <div class="text-xs text-emerald-400/70" x-text="'$' + formatCurrency(lifetimeCacheSavingsUsd) + ' saved'"></div>
+                            </div>
+                        </template>
                         <!-- Cache efficiency bar (session-scoped; hidden until traffic arrives) -->
                         <div x-show="cacheSessionActive">
                             <div class="flex justify-between text-xs text-gray-500 mb-1">
@@ -2478,6 +2485,20 @@ <h3 class="mb-3 text-sm font-medium text-gray-300">Live Activity</h3>
                     return (this.stats.prefix_cache?.totals?.requests || 0) > 0;
                 },
 
+                get lifetimeCacheReadTokens() {
+                    return this.stats.persistent_savings?.lifetime?.cache_read_tokens || 0;
+                },
+
+                get lifetimeCacheSavingsUsd() {
+                    return this.stats.persistent_savings?.lifetime?.cache_savings_usd || 0;
+                },
+
+                get hasPrefixCacheImpact() {
+                    return this.cacheSessionActive
+                        || this.lifetimeCacheReadTokens > 0
+                        || this.lifetimeCacheSavingsUsd > 0;
+                },
+
                 get cacheSavingsPercent() {
                     const t = this.stats.prefix_cache?.totals || {};
                     const total = (t.cache_read_tokens || 0) + (t.cache_write_tokens || 0);

headroom/dashboard/templates/dashboard.html

@@ -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
@@ -126,6 +126,17 @@ def clear_overrides() -> None:
         _overrides.clear()
 
 
+def clear_override(name: str) -> bool:
+    """Drop a single override so ``getenv`` falls back to the environment.
+
+    Returns True if an override was present. Used when a live knob is unset in
+    the settings GUI: removing the override (rather than pushing ``""``) lets
+    the reader see the value as genuinely absent again.
+    """
+    with _lock:
+        return _overrides.pop(name, None) is not None
+
+
 def explicit_env(environ: Mapping[str, str] | None = None) -> dict[str, str]:
     """Knobs *explicitly* set (non-empty) in ``environ`` — the wrap push payload.
 

headroom/dashboard/templates/settings.html

@@ -944,7 +944,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()]
@@ -2387,12 +2392,23 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:
 
     # Defensive re-apply of file-backed settings for embedded/non-CLI callers
     # that construct the app without going through the `headroom` CLI entrypoint
-    # (which already applies them before Click parsing). setdefault keeps
-    # explicit env exports authoritative; fail-open so it never blocks startup.
+    # (which already applies them before Click parsing). settings.json wins over
+    # a shell-exported env var here — highest priority below an explicit CLI arg;
+    # manifest_managed knobs keep the export. Fail-open so it never blocks startup.
     try:
         from headroom import settings_store
 
-        settings_store.apply_to_environ(settings_store.load())
+        stored = settings_store.load()
+        settings_store.apply_to_environ(stored)
+        # Live (Output Shaping) knobs are intentionally NOT written to os.environ
+        # (that would env-lock them in the GUI). Seed them into the hot-reload
+        # override store so persisted values stay active after a restart yet
+        # remain editable. The override wins over os.environ, so the stored
+        # value takes precedence over a shell export, matching settings-first.
+        _live_seed = settings_store.runtime_overrides(
+            settings_store.live_keys(list(stored)), stored
+        )
+        runtime_env.set_overrides(_live_seed)
     except Exception:  # noqa: BLE001 — settings load must never break startup
         pass
 
@@ -3359,6 +3375,15 @@ async def settings_schema(_request: Request):
             schema["supervised"] = mode != "foreground"
         except Exception:  # noqa: BLE001 — schema must render even if detection fails
             schema["supervised"] = False
+        # Live (runtime_env) knobs apply without a restart, so their true current
+        # value is the hot-reload override — not the launch-time environ the store
+        # read. Reflect that so the form shows what is actually active right now.
+        for field_schema in schema["fields"]:
+            if field_schema.get("live"):
+                field_schema["value"] = settings_store.coerce_env_value(
+                    field_schema["key"], runtime_env.getenv(field_schema["env"])
+                )
+        schema["values"] = {f["key"]: f["value"] for f in schema["fields"]}
         return JSONResponse(status_code=200, content=schema)
 
     @app.get("/settings", dependencies=[Depends(_require_loopback)])
@@ -3399,6 +3424,20 @@ async def settings_post(request: Request):
             )
         after = settings_store.load()
         changed_keys = sorted(k for k in set(before) | set(after) if before.get(k) != after.get(k))
+        # Live (Output Shaping) knobs hot-reload with no restart: push their new
+        # values to the runtime-env override store so they take effect on the
+        # next request. Every other knob is startup-captured and needs a restart.
+        live_changed = settings_store.live_keys(changed_keys)
+        if live_changed:
+            runtime_env.set_overrides(settings_store.runtime_overrides(live_changed, after))
+            # A live knob cleared to its default is absent from `after`; drop its
+            # override so the reader falls back to the adaptive default right away.
+            for key in live_changed:
+                if key not in after:
+                    env = settings_store.env_for(key)
+                    if env:
+                        runtime_env.clear_override(env)
+        restart_changed = [k for k in changed_keys if k not in live_changed]
         record_admin_action(
             request=request,
             action="settings_update",
@@ -3407,7 +3446,12 @@ async def settings_post(request: Request):
         )
         return JSONResponse(
             status_code=200,
-            content={"ok": True, "needs_restart": bool(changed_keys), "changed_keys": changed_keys},
+            content={
+                "ok": True,
+                "needs_restart": bool(restart_changed),
+                "changed_keys": changed_keys,
+                "live_keys": live_changed,
+            },
         )
 
     @app.post(