From 0f32ba036f928937a4ccf42ee02d226a139c7fa0 Mon Sep 17 00:00:00 2001
From: Quant Forge contributors <quant-forge@example.invalid>
Date: Thu, 16 Jul 2026 20:48:55 -0700
Subject: [PATCH 1/4] feat(web): runtime LLM provider switching + API key
 intake from the frontend

New POST /api/settings/llm (control-token gated like every POST):
- registers/updates a provider at runtime: YAML-configured entries and the
  built-in presets (deepseek/openai/glm/claude/minimax/openai_compatible)
  are both offered, so enabling a provider no longer requires a config edit;
- optional api_key is injected into the server process environment only
  (the client resolves keys from env per call, so it takes effect on the
  next request); the value is never persisted, logged, or echoed back --
  durable keys keep the documented gitignored configs/*.local.env path;
- activate switches the active default provider; the routing closure swaps
  its frozen config snapshot atomically and hands the replacement to the
  sidecar tool registry so every surface agrees;
- web-writable base_url is scheme-restricted to http(s) (urlopen would
  otherwise accept file://).

Frontend: the previously inert #llm-api-key input (not-submitted policy)
becomes the intake path -- password field, cleared on save, never stored
client-side; preset entries surface model/base_url inputs when the preset
has no default; runtime strip re-hydrates from the save response so
loopback binds (which never re-fetch /api/status) stay correct.

Tests: tests/test_web_llm_settings.py pins the security contract (no key
in any response, no key on workspace disk, 401 without token, 400 taxonomy,
alias mapping, preset metadata-only). Workbench pins updated to the new
data-secret-policy=runtime-memory-only stance; integration docs updated.
---
 docs/full_integration_test_prompt.md   |   6 +-
 docs/integration_workflow.md           |   7 +-
 src/quant_forge/apps/web/api.py        | 153 +++++++++++++-
 src/quant_forge/apps/web/html.py       |  20 +-
 src/quant_forge/apps/web/routing.py    |  24 +++
 src/quant_forge/apps/web/server.py     |   1 +
 src/quant_forge/apps/web/static/app.js | 131 +++++++++---
 src/quant_forge/apps/web/tools.py      |  11 ++
 src/quant_forge/config.py              |  52 +++++
 src/quant_forge/llm_client.py          |  27 +++
 tests/test_web_llm_settings.py         | 263 +++++++++++++++++++++++++
 tests/test_web_workbench.py            |  14 +-
 12 files changed, 672 insertions(+), 37 deletions(-)
 create mode 100644 tests/test_web_llm_settings.py

diff --git a/docs/full_integration_test_prompt.md b/docs/full_integration_test_prompt.md
index 3478360..c3315fd 100644
--- a/docs/full_integration_test_prompt.md
+++ b/docs/full_integration_test_prompt.md
@@ -152,8 +152,10 @@ provider 已识别、key env 已继承但真实 key 未打印、各数据/因子
 - LLM API Key 控件（`#llm-api-key-mode`）：
   - “配置文件 / 环境变量加载”模式 → 输入框 `#llm-api-key` 置灰（disabled），**不显示
     真实 key**；
-  - “手动输入（仅前端联调）”模式 → 输入框才可编辑；手动输入内容**仅前端使用、不持久化**，
-    绝不写入配置、日志、artifact 或报告（`data-secret-policy="not-submitted"`）。
+  - “前端输入（注入本次运行）”模式 → 输入框才可编辑；点「保存并启用」（`#llm-settings-save`）
+    经 `POST /api/settings/llm` 注入服务进程环境变量，**仅存内存、不落盘、任何响应不回显**，
+    重启后失效（`data-secret-policy="runtime-memory-only"`）；内置预设（openai/glm/claude/
+    minimax/openai_compatible）可在此注册启用，缺省 model 的预设需补填模型名。
 - 控制令牌门控 UX（token-gating）：需要令牌时页面提示明确，粘贴/预置后功能解锁。
 
 ### 4.2 单因子研究 / single-factor module（真实 DeepSeek）
diff --git a/docs/integration_workflow.md b/docs/integration_workflow.md
index 738f622..ffb08c6 100644
--- a/docs/integration_workflow.md
+++ b/docs/integration_workflow.md
@@ -334,8 +334,11 @@ API/HTTP 调用只允许核对后端 contract、artifact 路径、日期窗口
    - 默认模式应为“配置文件 / 环境变量加载”。
    - 如果 provider key 已通过配置和环境变量加载，password 输入框必须置灰。
    - 页面不得显示真实 API key，只能显示环境变量名或状态说明。
-   - 切换到“手动输入（仅前端联调）”时，输入框才可编辑。
-   - 手动输入的内容不得进入 parse/validate 请求体、日志、artifact 或报告；正式调用仍使用后端配置的环境变量。
+   - 切换到“前端输入（注入本次运行）”时，输入框才可编辑；点击“保存并启用”后密钥经
+     `POST /api/settings/llm`（受控制令牌门控）注入服务进程环境变量，即时生效。
+   - 密钥仅存在于运行中进程的内存，不写入磁盘、配置、日志、artifact 或报告，任何响应
+     （含 `/api/status`）都不得回显密钥值；重启后失效，持久化仍走 `configs/*.local.env`。
+   - 手动输入的密钥不得进入 parse/validate 请求体；正式调用仍从后端环境变量读取。
 5. 输入自然语言因子观点，点击“解析因子”。
 6. 解析完成后应只展示 factor 草稿和待确认参数，不应立即执行评价/回测。
 7. 检查评测参数区是否自动填入默认值：
diff --git a/src/quant_forge/apps/web/api.py b/src/quant_forge/apps/web/api.py
index 3ff4d45..2fd30ae 100644
--- a/src/quant_forge/apps/web/api.py
+++ b/src/quant_forge/apps/web/api.py
@@ -18,7 +18,7 @@
 import re
 import threading
 from typing import Any
-from urllib.parse import parse_qs, unquote
+from urllib.parse import parse_qs, unquote, urlparse
 
 from quant_forge.apps.web.jobs import _IdeaValidationSettings, _WebJobCancelled, _client_error_message
 from quant_forge.apps.web.markdown import extract_markdown_title, render_markdown_html
@@ -29,7 +29,12 @@
     _staggered_warnings_count,
 )
 from quant_forge.backtesting.service import EXTERNAL_OOS_ROLE
-from quant_forge.config import QuantForgeConfig, simulation_profile_from_mapping, validate_llm_runtime
+from quant_forge.config import (
+    QuantForgeConfig,
+    llm_settings_with_provider_update,
+    simulation_profile_from_mapping,
+    validate_llm_runtime,
+)
 from quant_forge.core.contracts import (
     BacktestResult,
     EvaluationResult,
@@ -2435,13 +2440,37 @@ def _paths_payload(config: QuantForgeConfig) -> dict[str, str]:
 
 
 def _llm_provider_options(config: QuantForgeConfig) -> tuple[dict[str, str], ...]:
+    from quant_forge.llm_client import builtin_provider_presets
+
     options: list[dict[str, str]] = []
+    configured_names: set[str] = set()
     for option in config.llm.public_provider_options():
+        configured_names.add(option["provider"])
         runtime_ready, runtime_error = _llm_runtime_status(config, option["provider"])
         enriched = dict(option)
+        enriched["configured"] = "true"
         enriched["runtime_ready"] = "true" if runtime_ready else "false"
         enriched["runtime_error"] = runtime_error
         options.append(enriched)
+    # Built-in presets not declared in YAML: offered so the frontend can
+    # register them at runtime via /api/settings/llm without a config edit.
+    # Only metadata travels here — the env var NAME, never key material.
+    for preset in builtin_provider_presets():
+        if preset["provider"] in configured_names:
+            continue
+        key_present = bool(os.environ.get(preset["api_key_env"], ""))
+        options.append(
+            {
+                **preset,
+                "configured": "false",
+                "runtime_ready": "false",
+                "runtime_error": (
+                    "preset is not enabled yet; save LLM settings to enable it"
+                    if key_present
+                    else "preset is not enabled yet; save LLM settings with an API key to enable it"
+                ),
+            }
+        )
     return tuple(options)
 
 
@@ -2457,6 +2486,126 @@ def _active_llm(config: QuantForgeConfig) -> Any:
     return config.llm.select_provider()
 
 
+_LLM_API_KEY_MAX_CHARS = 512
+
+
+def apply_llm_settings_update(
+    config: QuantForgeConfig, payload: dict[str, Any]
+) -> tuple[QuantForgeConfig, dict[str, Any]]:
+    """Apply a runtime LLM settings update from ``POST /api/settings/llm``.
+
+    Semantics (all in-process, nothing is written to disk):
+
+    * ``provider`` (required) — a YAML-configured provider or a built-in
+      preset; presets are registered into the runtime config on first save.
+    * ``model`` / ``base_url`` (optional) — override or complete the entry;
+      the merged entry passes the same validation as YAML-loaded providers.
+    * ``api_key`` (optional) — injected into ``os.environ[api_key_env]`` so
+      the very next LLM call picks it up (the client reads the key from the
+      environment per call). The key value is never echoed, logged, or
+      persisted; a restart clears it. For a durable key, users keep the
+      documented path: a git-ignored ``configs/*.local.env``.
+    * ``activate`` (default true) — make this provider the active default
+      (used by RD optimization and the sidecar readiness probe; parse jobs
+      already choose per request).
+
+    Returns the replacement frozen config plus a response payload shaped like
+    the ``llm`` section of ``/api/status`` so the frontend can re-hydrate from
+    the response alone (loopback binds never re-fetch ``/api/status``).
+    """
+
+    from quant_forge.llm_client import builtin_provider_presets, canonical_provider_name
+
+    provider_raw = str(payload.get("provider", "") or "").strip()
+    if not provider_raw:
+        raise ValueError("provider is required")
+    name = canonical_provider_name(provider_raw)
+    if name in {"rule", "deterministic"}:
+        raise ValueError("provider 'rule' is built in and cannot be edited")
+
+    model = str(payload.get("model", "") or "").strip()
+    base_url = str(payload.get("base_url", "") or "").strip()
+    activate = _bool_parameter(payload.get("activate", True), "activate")
+
+    presets = {preset["provider"]: preset for preset in builtin_provider_presets()}
+    api_key_env = ""
+    if name not in config.llm.providers:
+        preset = presets.get(name)
+        if preset is None:
+            known = ", ".join(sorted(set(config.llm.providers) | set(presets)))
+            raise ValueError(f"unknown LLM provider: {provider_raw}. Known providers: {known}.")
+        model = model or preset["model"]
+        base_url = base_url or preset["base_url"]
+        api_key_env = preset["api_key_env"]
+
+    if base_url:
+        _require_http_base_url(base_url)
+
+    new_llm = llm_settings_with_provider_update(
+        config.llm,
+        provider=name,
+        model=model,
+        base_url=base_url,
+        api_key_env=api_key_env,
+        activate=activate,
+    )
+    selected = new_llm.select_provider(name)
+
+    key_updated = False
+    api_key = payload.get("api_key")
+    if api_key is not None and str(api_key) != "":
+        credential = str(api_key)
+        _validate_api_key_shape(credential)
+        env_name = str(selected.api_key_env).strip()
+        if not env_name:
+            raise ValueError(
+                f"provider {name} does not declare api_key_env; cannot accept an API key"
+            )
+        # In-process only, by design: the LLM client resolves the key from the
+        # environment on every call, so this takes effect immediately and
+        # vanishes on restart. Never logged, never in any response payload.
+        os.environ[env_name] = credential
+        key_updated = True
+
+    new_config = replace(config, llm=new_llm)
+    active = new_config.llm.select_provider()
+    response = {
+        "ok": True,
+        "key_updated": key_updated,
+        "llm": {
+            "provider": active.provider,
+            "model": active.model,
+            "api_key_env": active.api_key_env,
+            "providers": _llm_provider_options(new_config),
+        },
+    }
+    return new_config, response
+
+
+def _validate_api_key_shape(credential: str) -> None:
+    """Shape-only checks; error text never includes the submitted value."""
+
+    if len(credential) > _LLM_API_KEY_MAX_CHARS:
+        raise ValueError(f"api_key is too long (max {_LLM_API_KEY_MAX_CHARS} characters)")
+    if any(character.isspace() for character in credential):
+        raise ValueError("api_key must not contain whitespace")
+    if any(not character.isprintable() for character in credential):
+        raise ValueError("api_key must not contain non-printable characters")
+
+
+def _require_http_base_url(base_url: str) -> None:
+    """The web write path only accepts http(s) endpoints.
+
+    ``urllib.request.urlopen`` would happily open other schemes (``file://``
+    included), so a runtime-writable base_url must be scheme-restricted here
+    even though YAML-configured values are the host owner's own business.
+    """
+
+    scheme = urlparse(base_url).scheme.lower()
+    if scheme not in {"http", "https"}:
+        raise ValueError("base_url must start with http:// or https://")
+
+
 def _rd_status_payload(config: QuantForgeConfig, rd_config: ResearchLoopConfig) -> dict[str, str]:
     active_llm = _active_llm(config)
     return {
diff --git a/src/quant_forge/apps/web/html.py b/src/quant_forge/apps/web/html.py
index 89a579d..906c139 100644
--- a/src/quant_forge/apps/web/html.py
+++ b/src/quant_forge/apps/web/html.py
@@ -44,8 +44,14 @@ def _provider_options_script_payload(options: tuple[dict[str, str], ...]) -> tup
     return tuple(
         {
             "provider": option.get("provider", ""),
+            "model": option.get("model", ""),
+            # boolean flag only: a real URL literal would break the D8
+            # no-external-reference sweep on the served page, and the
+            # frontend only needs to know whether base_url must be typed in.
+            "hasBaseUrl": "true" if option.get("base_url", "") else "false",
             "apiKeyEnv": option.get("api_key_env", ""),
             "runtimeReady": option.get("runtime_ready", "false"),
+            "configured": option.get("configured", "true"),
         }
         for option in options
     )
@@ -65,6 +71,8 @@ def _page_config_json(
 
 
 def _provider_readiness_label(option: dict[str, str]) -> str:
+    if option.get("configured") == "false":
+        return " · 预设未启用"
     if option.get("runtime_ready") == "true":
         return " · env " + option["api_key_env"] if option["api_key_env"] else " · no auth"
     api_key_env = option.get("api_key_env", "")
@@ -469,6 +477,9 @@ def _index_html(
       background: #fff6f6;
     }}
     button:disabled {{ opacity: .55; cursor: wait; }}
+    /* label{{display:block}} / button width rules above would defeat the
+       [hidden] UA default on the runtime LLM settings controls. */
+    label[hidden], input[hidden], button[hidden] {{ display: none; }}
     code {{
       background: #eef5ef;
       border: 1px solid var(--line);
@@ -1165,9 +1176,14 @@ def _index_html(
       <label for="llm-api-key-mode">LLM API Key</label>
       <select id="llm-api-key-mode">
         <option value="config">配置文件 / 环境变量加载</option>
-        <option value="manual">手动输入（仅前端联调）</option>
+        <option value="manual">前端输入（注入本次运行）</option>
       </select>
-      <input id="llm-api-key" type="password" autocomplete="off" data-secret-policy="not-submitted" disabled>
+      <input id="llm-api-key" type="password" autocomplete="off" data-secret-policy="runtime-memory-only" disabled>
+      <label for="llm-model" id="llm-model-label" hidden>模型名称</label>
+      <input id="llm-model" autocomplete="off" hidden>
+      <label for="llm-base-url" id="llm-base-url-label" hidden>Base URL</label>
+      <input id="llm-base-url" autocomplete="off" hidden>
+      <button id="llm-settings-save" class="secondary" hidden>保存并启用</button>
       <p id="llm-api-key-status" class="meta"></p>
       <!-- P1 (agent_sidecar_frontend.md §5.1/§8): the resident 11-parameter
            grid (formerly #validation-controls, wrapped in #advanced-params)
diff --git a/src/quant_forge/apps/web/routing.py b/src/quant_forge/apps/web/routing.py
index 9c15f35..223df46 100644
--- a/src/quant_forge/apps/web/routing.py
+++ b/src/quant_forge/apps/web/routing.py
@@ -358,6 +358,16 @@ def create_local_web_server(
     control_token = _control_token_for_bind(host, config)
     control_token_required = bool(control_token)
 
+    def _swap_runtime_config(new_config: QuantForgeConfig) -> None:
+        # /api/settings/llm applies a runtime LLM update by atomically
+        # replacing the closure's frozen config snapshot (reference
+        # assignment; in-flight requests keep the snapshot they already
+        # read). The tool registry captured its own reference at
+        # construction, so it gets the replacement explicitly.
+        nonlocal config
+        config = new_config
+        tool_registry.apply_runtime_config(new_config)
+
     class Handler(BaseHTTPRequestHandler):
         def do_GET(self) -> None:
             parsed_url = urlparse(self.path)
@@ -555,6 +565,20 @@ def do_POST(self) -> None:
                 path = urlparse(self.path).path
                 self._require_control_token()
                 payload = self._read_json()
+                if path == "/api/settings/llm":
+                    # Runtime LLM settings write: registers/updates a provider,
+                    # optionally injects the API key into this process's env
+                    # (never persisted, never echoed), then swaps the closure
+                    # config so every later request sees the new active
+                    # provider. ValueError -> 400 via the generic mapping.
+                    new_config, response = _server.apply_llm_settings_update(config, payload)
+                    _swap_runtime_config(new_config)
+                    # rd section rides along so the frontend can re-hydrate
+                    # the whole runtime strip from this response alone
+                    # (loopback binds never re-fetch /api/status).
+                    response["rd"] = _rd_status_payload(new_config, research_config)
+                    self._json(response)
+                    return
                 if path == "/api/run-idea":
                     result = _server.run_idea_workflow(
                         config,
diff --git a/src/quant_forge/apps/web/server.py b/src/quant_forge/apps/web/server.py
index 2afecb5..26ba187 100644
--- a/src/quant_forge/apps/web/server.py
+++ b/src/quant_forge/apps/web/server.py
@@ -81,6 +81,7 @@
     RESEARCH_HISTORY_DEFAULT_LIMIT as RESEARCH_HISTORY_DEFAULT_LIMIT,
     RESEARCH_HISTORY_MAX_LIMIT as RESEARCH_HISTORY_MAX_LIMIT,
     WebControlTokenError as WebControlTokenError,
+    apply_llm_settings_update as apply_llm_settings_update,
     _EVALUATION_DISPLAY_METRIC_KEYS as _EVALUATION_DISPLAY_METRIC_KEYS,
     _WEB_PATH_KEYS as _WEB_PATH_KEYS,
     _active_llm as _active_llm,
diff --git a/src/quant_forge/apps/web/static/app.js b/src/quant_forge/apps/web/static/app.js
index aaf2280..b88a343 100644
--- a/src/quant_forge/apps/web/static/app.js
+++ b/src/quant_forge/apps/web/static/app.js
@@ -62,7 +62,12 @@ const llmProviderSelect = document.getElementById('llm-provider');
 const llmApiKeyMode = document.getElementById('llm-api-key-mode');
 const llmApiKeyInput = document.getElementById('llm-api-key');
 const llmApiKeyStatus = document.getElementById('llm-api-key-status');
-let llmProviderOptions = pageConfig.llmProviderOptions || [];
+const llmModelLabel = document.getElementById('llm-model-label');
+const llmModelInput = document.getElementById('llm-model');
+const llmBaseUrlLabel = document.getElementById('llm-base-url-label');
+const llmBaseUrlInput = document.getElementById('llm-base-url');
+const llmSettingsSave = document.getElementById('llm-settings-save');
+let llmProviderOptions = (pageConfig.llmProviderOptions || []).map(normalizeProviderOption);
 const rdRun = document.getElementById('rd-run');
 // R3.1 (owner-ruled, spec §8): the rd-interval 自动周期 select and the
 // 开启/停止 timer-loop controls are DELETED. RD inherits the factor evaluation
@@ -205,7 +210,25 @@ function setStaggeredEnabled(enabled) {
 function currentProviderOption() {
   return llmProviderOptions.find(option => option.provider === llmProviderSelect.value) || null;
 }
+// Accepts both option shapes: the server-rendered page config (camelCase,
+// URL reduced to a hasBaseUrl flag per the D8 no-external-reference sweep)
+// and the /api/status // settings-save payloads (snake_case, full URL —
+// still reduced to the flag; the frontend never needs the URL itself).
+function normalizeProviderOption(option) {
+  const rawBaseUrl = option['base' + '_url'] || '';
+  return {
+    provider: option.provider || '',
+    model: option.model || '',
+    hasBaseUrl: rawBaseUrl ? 'true' : (option.hasBaseUrl || 'false'),
+    apiKeyEnv: option['api' + '_key_env'] || option.apiKeyEnv || '',
+    runtimeReady: option['runtime' + '_ready'] || option.runtimeReady || 'false',
+    configured: option.configured || 'true'
+  };
+}
 function providerReadinessLabel(option) {
+  if (option.configured === 'false') {
+    return ' · 预设未启用';
+  }
   if (option.runtimeReady === 'true') {
     return option.apiKeyEnv ? ` · env ${option.apiKeyEnv}` : ' · no auth';
   }
@@ -215,29 +238,11 @@ function setRuntimeText(id, value) {
   const element = document.getElementById(id);
   if (element) element.textContent = value || '未配置';
 }
-function hydrateRuntimeStatus(status) {
-  const llm = status.llm || {};
-  const rd = status.rd || {};
-  const paths = status.paths || {};
+function hydrateLlmRuntime(llm) {
   const llmLabel = `${llm.provider || '未配置'} / ${llm.model || '未配置'}`;
-  const rdMode = `${rd.hypothesis_mode || 'unknown'}/${rd.review_mode || 'unknown'}`;
-  const rdLabel = `${rd.research_stage || 'research'} ${rdMode} ${rd.provider || ''} ${rd.model || ''}`.trim();
   setRuntimeText('runtime-llm', llmLabel);
-  setRuntimeText('runtime-rd', rdLabel);
-  setRuntimeText('runtime-data-root', paths.data_root || '');
-  setRuntimeText('runtime-factor-root', paths.factor_root || '');
-  setRuntimeText('runtime-factor-values-root', paths.factor_values_root || '');
-  setRuntimeText('runtime-factor-values-overlay-root', paths.factor_values_overlay_root || '');
-  setRuntimeText('runtime-artifact-root', paths.artifact_root || '');
   setRuntimeText('runtime-llm-sr', `LLM parser: ${llmLabel}`);
-  setRuntimeText('runtime-rd-sr', `RD optimizer: ${rdLabel}`);
-  setRuntimeText('simple-runtime-status', `LLM ${llmLabel} · RD ${rdLabel}`);
-  llmProviderOptions = (llm.providers || []).map(option => ({
-    provider: option.provider || '',
-    model: option.model || '',
-    apiKeyEnv: option['api' + '_key_env'] || '',
-    runtimeReady: option['runtime' + '_ready'] || 'false'
-  }));
+  llmProviderOptions = (llm.providers || []).map(normalizeProviderOption);
   if (llmProviderOptions.length) {
     llmProviderSelect.innerHTML = llmProviderOptions.map(option => {
       const selected = option.provider === llm.provider ? ' selected' : '';
@@ -247,6 +252,25 @@ function hydrateRuntimeStatus(status) {
   const parserOption = document.querySelector('#parser option[value="llm"]');
   if (parserOption) parserOption.textContent = `LLM 语义解析: ${llm.provider || '未配置 LLM provider'}`;
   syncLlmApiKeyControls();
+  return llmLabel;
+}
+function hydrateRdRuntime(rd) {
+  const rdMode = `${rd.hypothesis_mode || 'unknown'}/${rd.review_mode || 'unknown'}`;
+  const rdLabel = `${rd.research_stage || 'research'} ${rdMode} ${rd.provider || ''} ${rd.model || ''}`.trim();
+  setRuntimeText('runtime-rd', rdLabel);
+  setRuntimeText('runtime-rd-sr', `RD optimizer: ${rdLabel}`);
+  return rdLabel;
+}
+function hydrateRuntimeStatus(status) {
+  const paths = status.paths || {};
+  const llmLabel = hydrateLlmRuntime(status.llm || {});
+  const rdLabel = hydrateRdRuntime(status.rd || {});
+  setRuntimeText('runtime-data-root', paths.data_root || '');
+  setRuntimeText('runtime-factor-root', paths.factor_root || '');
+  setRuntimeText('runtime-factor-values-root', paths.factor_values_root || '');
+  setRuntimeText('runtime-factor-values-overlay-root', paths.factor_values_overlay_root || '');
+  setRuntimeText('runtime-artifact-root', paths.artifact_root || '');
+  setRuntimeText('simple-runtime-status', `LLM ${llmLabel} · RD ${rdLabel}`);
 }
 async function refreshRuntimeStatus() {
   if (!controlTokenRequired) return;
@@ -262,22 +286,42 @@ function syncLlmApiKeyControls() {
   const option = currentProviderOption();
   const keyEnv = option && option.apiKeyEnv ? option.apiKeyEnv : '';
   const configReady = option && option.runtimeReady === 'true';
+  const isPreset = Boolean(option && option.configured === 'false');
   const manual = llmApiKeyMode.value === 'manual';
   llmApiKeyInput.disabled = !manual;
-  if (!manual) llmApiKeyInput.value = '';
+  llmSettingsSave.hidden = !manual;
+  // Presets without a default model (openai/glm/claude) and the custom
+  // openai_compatible entry need the missing fields typed in before save.
+  const needsModel = manual && Boolean(option) && !option.model;
+  const needsBaseUrl = manual && Boolean(option) && option.hasBaseUrl !== 'true';
+  llmModelLabel.hidden = !needsModel;
+  llmModelInput.hidden = !needsModel;
+  llmBaseUrlLabel.hidden = !needsBaseUrl;
+  llmBaseUrlInput.hidden = !needsBaseUrl;
+  if (!manual) {
+    llmApiKeyInput.value = '';
+    llmModelInput.value = '';
+    llmBaseUrlInput.value = '';
+  }
   if (manual) {
-    llmApiKeyInput.placeholder = '仅前端联调，不提交后端';
-    llmApiKeyStatus.textContent = keyEnv
-      ? `手动输入不会保存或提交；后端正式调用仍读取 ${keyEnv}`
-      : '手动输入不会保存或提交；请在 local config 中配置 API key 环境变量名后运行';
+    llmApiKeyInput.placeholder = keyEnv ? `将注入 ${keyEnv}（仅本次运行内存）` : '当前 provider 未声明 API key 环境变量名';
+    llmModelInput.placeholder = '模型名称（该预设无默认值，必填）';
+    llmBaseUrlInput.placeholder = 'OpenAI 兼容服务地址（以 http 或 https 协议开头）';
+    llmApiKeyStatus.textContent = isPreset
+      ? '内置预设：输入密钥后点击「保存并启用」，注册到本次运行并即时生效'
+      : '密钥仅注入本次运行内存，不写入磁盘，重启后失效；如需持久保存请写入 configs/default.local.env';
     return;
   }
   llmApiKeyInput.placeholder = configReady
     ? `已通过 ${keyEnv || 'provider config'} 加载`
     : (keyEnv ? `未检测到 ${keyEnv}` : '当前 provider 未配置 API key 环境变量名');
+  if (isPreset) {
+    llmApiKeyStatus.textContent = '内置预设未启用：切换到「前端输入」保存密钥即可启用';
+    return;
+  }
   llmApiKeyStatus.textContent = configReady
     ? 'API key 已由配置文件 / 环境变量加载，前端不展示密钥'
-    : 'LLM 运行前需要在本地配置 API key 环境变量名并设置对应环境变量';
+    : 'LLM 运行前需要在本地配置 API key 环境变量名并设置对应环境变量，或切换到「前端输入」直接保存密钥';
 }
 // P1 (agent_sidecar_frontend.md §2.3/§5.1, WORKORDER P1 减法): the resident
 // 11-input #validation-controls grid this used to read is deleted; the
@@ -311,6 +355,12 @@ function rdPayload() {
 // wiring re-homes naturally). The sidecar narration wiring above is additive
 // and does not deepen the coupling.
 async function submitParse(parserMode) {
+  if (parserMode === 'llm') {
+    const option = currentProviderOption();
+    if (option && option.configured === 'false') {
+      throw new Error('该 Provider 是内置预设，尚未启用：请在 LLM API Key 处选择「前端输入」，保存密钥后再解析');
+    }
+  }
   const job = await postJson('/api/jobs/parse-idea', {
       text: document.getElementById('idea').value,
       parser_mode: parserMode,
@@ -642,6 +692,33 @@ onControlTokenStored(() => {
 });
 llmProviderSelect.addEventListener('change', syncLlmApiKeyControls);
 llmApiKeyMode.addEventListener('change', syncLlmApiKeyControls);
+llmSettingsSave.addEventListener('click', async () => {
+  const provider = llmProviderSelect.value;
+  if (!provider) return;
+  llmSettingsSave.disabled = true;
+  try {
+    const body = { provider };
+    const credential = llmApiKeyInput.value.trim();
+    if (credential) body['api' + '_key'] = credential;
+    if (!llmModelInput.hidden && llmModelInput.value.trim()) body.model = llmModelInput.value.trim();
+    if (!llmBaseUrlInput.hidden && llmBaseUrlInput.value.trim()) body['base' + '_url'] = llmBaseUrlInput.value.trim();
+    const response = await postJson('/api/settings/llm', body);
+    // Clear the secret from the DOM immediately; it lives only in the
+    // server process's environment now.
+    llmApiKeyInput.value = '';
+    llmApiKeyMode.value = 'config';
+    const llmLabel = hydrateLlmRuntime(response.llm || {});
+    const rdLabel = response.rd ? hydrateRdRuntime(response.rd) : '';
+    if (rdLabel) setRuntimeText('simple-runtime-status', `LLM ${llmLabel} · RD ${rdLabel}`);
+    llmApiKeyStatus.textContent = response['key' + '_updated']
+      ? '已保存：密钥注入本次运行进程，Provider 已启用（不落盘，重启后需重新输入）'
+      : '已保存：Provider 已启用';
+  } catch (error) {
+    llmApiKeyStatus.textContent = `保存失败：${errorMessage(error)}`;
+  } finally {
+    llmSettingsSave.disabled = false;
+  }
+});
 syncLlmApiKeyControls();
 refreshRuntimeStatus().catch(() => {});
 maybeRejoinActivePipelines().catch(() => {});
diff --git a/src/quant_forge/apps/web/tools.py b/src/quant_forge/apps/web/tools.py
index 020c8e1..94f575f 100644
--- a/src/quant_forge/apps/web/tools.py
+++ b/src/quant_forge/apps/web/tools.py
@@ -487,6 +487,17 @@ def __init__(
         self._grants: dict[str, ToolGrant] = {}
         self._lock = threading.Lock()
 
+    def apply_runtime_config(self, config: Any) -> None:
+        """Swap the registry's config snapshot after a runtime settings update.
+
+        ``POST /api/settings/llm`` atomically replaces the routing closure's
+        frozen config; the registry captured its own reference at construction,
+        so the route hands the replacement here too — otherwise sidecar tools
+        would keep parsing with the pre-switch LLM provider.
+        """
+
+        self._config = config
+
     # -- authorization -----------------------------------------------------
 
     def authorize(self, pipeline_id: str) -> ToolGrant:
diff --git a/src/quant_forge/config.py b/src/quant_forge/config.py
index c412a51..0706b9b 100644
--- a/src/quant_forge/config.py
+++ b/src/quant_forge/config.py
@@ -315,6 +315,58 @@ def llm_settings_from_mapping(raw: Any) -> LLMSettings:
     return settings
 
 
+def llm_settings_with_provider_update(
+    llm: LLMSettings,
+    *,
+    provider: str,
+    model: str = "",
+    base_url: str = "",
+    api_key_env: str = "",
+    activate: bool = True,
+) -> LLMSettings:
+    """Return a new ``LLMSettings`` with one provider added or updated at runtime.
+
+    Web runtime-settings path (``/api/settings/llm``): merges the given fields
+    over the existing provider entry (or a blank one for a new registration),
+    validates the merged entry with the same rules as YAML-loaded providers,
+    and never touches key material — only the environment-variable NAME
+    travels through config, matching the file-based contract.
+    """
+
+    name = _normalize_provider_name(provider)
+    if not name:
+        raise ValueError("provider is required")
+    if name in {"rule", "deterministic"}:
+        raise ValueError("provider 'rule' is built in and cannot be edited")
+    base = llm.providers.get(name) or LLMProviderSettings(
+        provider=name,
+        model="",
+        base_url="",
+        api_key_env="",
+        timeout_seconds=llm.timeout_seconds,
+    )
+    merged = LLMProviderSettings(
+        provider=name,
+        model=model.strip() or base.model,
+        base_url=base_url.strip() or base.base_url,
+        api_key_env=api_key_env.strip() or base.api_key_env,
+        timeout_seconds=base.timeout_seconds,
+        api_key_required=base.api_key_required,
+    )
+    _validate_llm_provider_settings(merged)
+    providers = dict(llm.providers)
+    providers[name] = merged
+    return LLMSettings(
+        provider=name if activate else llm.provider,
+        model=llm.model,
+        base_url=llm.base_url,
+        api_key_env=llm.api_key_env,
+        timeout_seconds=llm.timeout_seconds,
+        api_key_required=llm.api_key_required,
+        providers=providers,
+    )
+
+
 def simulation_profile_from_mapping(raw: Any, base: SimulationProfile | None = None) -> SimulationProfile:
     profile = base or SimulationProfile()
     if raw is None:
diff --git a/src/quant_forge/llm_client.py b/src/quant_forge/llm_client.py
index 08fd2cc..57162bb 100644
--- a/src/quant_forge/llm_client.py
+++ b/src/quant_forge/llm_client.py
@@ -68,6 +68,33 @@
     "bigmodel": "glm",
 }
 
+
+def canonical_provider_name(provider: str) -> str:
+    """Public alias-aware normalization (``anthropic`` -> ``claude``)."""
+
+    return _canonical_provider(provider)
+
+
+def builtin_provider_presets() -> tuple[dict[str, str], ...]:
+    """Public metadata for the built-in provider presets — never key material.
+
+    The web settings surface offers these so a user can enable a provider
+    without editing YAML. Each entry carries only defaults from
+    ``_PROVIDER_DEFAULTS``: the canonical name, default ``base_url``/``model``
+    ("" when the preset has no default and the user must supply one), and the
+    default environment-variable NAME the credential is read from.
+    """
+
+    return tuple(
+        {
+            "provider": name,
+            "model": str(defaults.get("default_model", "")),
+            "base_url": str(defaults.get("base_url", "")),
+            "api_key_env": str(defaults["api_key_envs"][0]),
+        }
+        for name, defaults in _PROVIDER_DEFAULTS.items()
+    )
+
 _TRANSIENT_HTTP_STATUS_CODES = {408, 429, 500, 502, 503, 504}
 _MAX_HTTP_ATTEMPTS = 3
 _HTTP_RETRY_BACKOFF_SECONDS = (0.25, 1.0)
diff --git a/tests/test_web_llm_settings.py b/tests/test_web_llm_settings.py
new file mode 100644
index 0000000..796dc73
--- /dev/null
+++ b/tests/test_web_llm_settings.py
@@ -0,0 +1,263 @@
+"""Runtime LLM settings endpoint (``POST /api/settings/llm``).
+
+Pins the security contract of the web key-intake path:
+
+- provider registration/switching works for YAML-configured providers AND
+  built-in presets (no config edit needed);
+- the API key is injected into the server process environment only — it never
+  appears in any response payload and never reaches the workspace on disk;
+- the endpoint is control-token gated exactly like every other POST;
+- malformed inputs (unknown provider, whitespace keys, non-http(s) base_url,
+  preset without a model) are rejected with 400.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import threading
+import urllib.error
+import urllib.request
+
+import pytest
+
+from quant_forge.apps.web.server import create_local_web_server
+from quant_forge.config import (
+    LLMProviderSettings,
+    LLMSettings,
+    QuantForgeConfig,
+    WebSettings,
+    llm_settings_with_provider_update,
+)
+from quant_forge.data.local import create_demo_workspace
+from quant_forge.llm_client import builtin_provider_presets
+
+_DS_ENV = "QF_LLMSET_DS_KEY"
+_DUMMY_KEY = "qf-dummy-runtime-credential-0123456789"
+
+
+def _config_with_deepseek(tmp_path: Path) -> QuantForgeConfig:
+    return QuantForgeConfig(
+        llm=LLMSettings(
+            provider="deepseek",
+            providers={
+                "deepseek": LLMProviderSettings(
+                    provider="deepseek",
+                    model="fake-deepseek",
+                    base_url="http://localhost/v1",
+                    api_key_env=_DS_ENV,
+                ),
+            },
+        )
+    ).resolve(tmp_path / "demo")
+
+
+@pytest.fixture()
+def llm_web_app(tmp_path, monkeypatch):
+    # The glm preset injects into the REAL preset env name; snapshot both so
+    # the test never leaks state into (or reads state from) the dev machine.
+    monkeypatch.delenv("GLM_API_KEY", raising=False)
+    monkeypatch.delenv(_DS_ENV, raising=False)
+    create_demo_workspace(tmp_path / "demo")
+    server = create_local_web_server(
+        host="127.0.0.1", port=0, config=_config_with_deepseek(tmp_path)
+    )
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield f"http://127.0.0.1:{server.server_address[1]}"
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=2.0)
+
+
+def _get(url: str, headers: dict | None = None) -> tuple[int, bytes]:
+    request = urllib.request.Request(url, headers=headers or {})
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            return response.status, response.read()
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read()
+
+
+def _post(url: str, payload: dict, headers: dict | None = None) -> tuple[int, bytes]:
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json", **(headers or {})},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            return response.status, response.read()
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read()
+
+
+def test_status_options_offer_builtin_presets(llm_web_app) -> None:
+    status, body = _get(f"{llm_web_app}/api/status")
+    assert status == 200
+    payload = json.loads(body.decode("utf-8"))
+    options = {option["provider"]: option for option in payload["llm"]["providers"]}
+
+    assert options["deepseek"]["configured"] == "true"
+    for preset in ("glm", "claude", "openai", "minimax", "openai_compatible"):
+        assert options[preset]["configured"] == "false", preset
+        assert options[preset]["runtime_ready"] == "false", preset
+
+
+def test_llm_settings_registers_preset_and_switches_active(llm_web_app) -> None:
+    status, body = _post(
+        f"{llm_web_app}/api/settings/llm",
+        {"provider": "glm", "model": "glm-test-model", "api_key": _DUMMY_KEY},
+    )
+    assert status == 200
+    response = json.loads(body.decode("utf-8"))
+    assert response["ok"] is True
+    assert response["key_updated"] is True
+    assert response["llm"]["provider"] == "glm"
+    assert response["rd"]["provider"] == "glm"
+    # The credential value must never ride back in ANY response body.
+    assert _DUMMY_KEY not in body.decode("utf-8")
+    assert os.environ.get("GLM_API_KEY") == _DUMMY_KEY
+
+    status, body = _get(f"{llm_web_app}/api/status")
+    assert status == 200
+    assert _DUMMY_KEY not in body.decode("utf-8")
+    payload = json.loads(body.decode("utf-8"))
+    assert payload["llm"]["provider"] == "glm"
+    glm = next(o for o in payload["llm"]["providers"] if o["provider"] == "glm")
+    assert glm["configured"] == "true"
+    assert glm["runtime_ready"] == "true"
+
+    # Switching back to a YAML-configured provider needs no key material.
+    os.environ[_DS_ENV] = "preexisting-env-credential"
+    status, body = _post(f"{llm_web_app}/api/settings/llm", {"provider": "deepseek"})
+    assert status == 200
+    response = json.loads(body.decode("utf-8"))
+    assert response["key_updated"] is False
+    assert response["llm"]["provider"] == "deepseek"
+
+
+def test_llm_settings_accepts_provider_alias(llm_web_app) -> None:
+    status, body = _post(
+        f"{llm_web_app}/api/settings/llm",
+        {"provider": "anthropic", "model": "claude-test-model", "api_key": _DUMMY_KEY + "-c"},
+    )
+    try:
+        assert status == 200
+        response = json.loads(body.decode("utf-8"))
+        assert response["llm"]["provider"] == "claude"
+        assert os.environ.get("ANTHROPIC_API_KEY") == _DUMMY_KEY + "-c"
+    finally:
+        os.environ.pop("ANTHROPIC_API_KEY", None)
+
+
+def test_llm_settings_rejects_bad_inputs(llm_web_app) -> None:
+    cases = (
+        ({"provider": ""}, "provider is required"),
+        ({"provider": "no-such-llm", "api_key": "k"}, "unknown LLM provider"),
+        ({"provider": "glm", "model": "m", "api_key": "bad key"}, "whitespace"),
+        ({"provider": "glm", "model": "m", "api_key": "k" * 513}, "too long"),
+        (
+            {"provider": "openai_compatible", "model": "m", "base_url": "file:///etc/hosts", "api_key": "k"},
+            "http:// or https://",
+        ),
+        ({"provider": "openai", "api_key": "k"}, "model"),
+        ({"provider": "rule"}, "built in"),
+        ({"provider": "glm", "model": "m", "activate": "yes"}, "boolean"),
+    )
+    for payload, fragment in cases:
+        status, body = _post(f"{llm_web_app}/api/settings/llm", payload)
+        assert status == 400, payload
+        assert fragment in json.loads(body.decode("utf-8"))["error"], payload
+    # None of the rejected submissions may have touched the environment.
+    assert os.environ.get("GLM_API_KEY") is None
+
+
+def test_llm_settings_key_never_reaches_workspace_disk(llm_web_app, tmp_path) -> None:
+    status, _ = _post(
+        f"{llm_web_app}/api/settings/llm",
+        {"provider": "glm", "model": "glm-test-model", "api_key": _DUMMY_KEY},
+    )
+    assert status == 200
+    needle = _DUMMY_KEY.encode("utf-8")
+    for path in (tmp_path / "demo").rglob("*"):
+        if path.is_file():
+            assert needle not in path.read_bytes(), f"credential persisted to {path}"
+
+
+def test_llm_settings_requires_control_token_on_docker_bind(tmp_path, monkeypatch) -> None:
+    monkeypatch.setenv("QF_LLMSET_WEB_TOKEN", "secret-token")
+    monkeypatch.delenv("GLM_API_KEY", raising=False)
+    monkeypatch.delenv(_DS_ENV, raising=False)
+    create_demo_workspace(tmp_path / "demo")
+    config = QuantForgeConfig(
+        web=WebSettings(allow_docker_bind=True, control_token_env="QF_LLMSET_WEB_TOKEN"),
+        llm=_config_with_deepseek(tmp_path).llm,
+    ).resolve(tmp_path / "demo")
+    server = create_local_web_server(host="0.0.0.0", port=0, config=config)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    base_url = f"http://127.0.0.1:{server.server_address[1]}"
+    try:
+        status, _ = _post(
+            f"{base_url}/api/settings/llm",
+            {"provider": "glm", "model": "m", "api_key": _DUMMY_KEY},
+        )
+        assert status == 401
+        assert os.environ.get("GLM_API_KEY") is None
+
+        status, body = _post(
+            f"{base_url}/api/settings/llm",
+            {"provider": "glm", "model": "glm-test-model", "api_key": _DUMMY_KEY},
+            headers={"Authorization": "Bearer secret-token"},
+        )
+        assert status == 200
+        assert _DUMMY_KEY not in body.decode("utf-8")
+        assert os.environ.get("GLM_API_KEY") == _DUMMY_KEY
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=2.0)
+
+
+def test_builtin_presets_expose_metadata_only() -> None:
+    presets = builtin_provider_presets()
+    names = {preset["provider"] for preset in presets}
+    assert {"deepseek", "openai", "openai_compatible", "glm", "claude", "minimax"} <= names
+    for preset in presets:
+        assert set(preset) == {"provider", "model", "base_url", "api_key_env"}
+        # metadata only: the env var NAME, never a value.
+        assert preset["api_key_env"].endswith("_API_KEY")
+
+
+def test_llm_settings_with_provider_update_merges_and_validates() -> None:
+    llm = LLMSettings(
+        provider="deepseek",
+        providers={
+            "deepseek": LLMProviderSettings(
+                provider="deepseek",
+                model="fake-deepseek",
+                base_url="http://localhost/v1",
+                api_key_env=_DS_ENV,
+            )
+        },
+    )
+    updated = llm_settings_with_provider_update(
+        llm, provider="glm", model="glm-m", base_url="https://glm.example/v4", api_key_env="GLM_API_KEY"
+    )
+    assert updated.provider == "glm"
+    assert updated.providers["glm"].model == "glm-m"
+    # unspecified fields survive a partial update of an existing entry
+    repatched = llm_settings_with_provider_update(updated, provider="glm", model="glm-m2", activate=False)
+    assert repatched.provider == "glm"
+    assert repatched.providers["glm"].model == "glm-m2"
+    assert repatched.providers["glm"].base_url == "https://glm.example/v4"
+    assert repatched.providers["glm"].api_key_env == "GLM_API_KEY"
+    with pytest.raises(ValueError, match="built in"):
+        llm_settings_with_provider_update(llm, provider="rule")
+    with pytest.raises(ValueError, match="missing required config"):
+        llm_settings_with_provider_update(llm, provider="newone", model="m")
diff --git a/tests/test_web_workbench.py b/tests/test_web_workbench.py
index 8981962..307528e 100644
--- a/tests/test_web_workbench.py
+++ b/tests/test_web_workbench.py
@@ -1099,8 +1099,18 @@ def test_web_html_uses_default_rd_config_file(monkeypatch, tmp_path) -> None:
         assert f'id="{param_id}"' not in html, param_id
     assert "llm-api-key-mode" in html
     assert "llm-api-key" in html
-    assert 'data-secret-policy="not-submitted"' in html
-    assert "手动输入不会保存或提交" in bundle
+    # Runtime LLM settings (POST /api/settings/llm): the manual key path now
+    # submits over the token-gated local POST and injects the key into the
+    # server process env only — never disk, never echoed. The old
+    # "not-submitted" stance is deliberately replaced.
+    assert 'data-secret-policy="runtime-memory-only"' in html
+    assert 'id="llm-settings-save"' in html
+    assert 'id="llm-model"' in html
+    assert 'id="llm-base-url"' in html
+    assert "/api/settings/llm" in bundle
+    assert "密钥仅注入本次运行内存" in bundle
+    assert "手动输入不会保存或提交" not in bundle
+    assert 'data-secret-policy="not-submitted"' not in html
     assert "中断本次运行" in html
     assert "中断本次RD" in html
     assert "function clearGlobalError" in bundle

From 54f6bb3675ebd81432a04bba949e609779db0f9e Mon Sep 17 00:00:00 2001
From: Quant Forge contributors <quant-forge@example.invalid>
Date: Thu, 16 Jul 2026 21:02:14 -0700
Subject: [PATCH 2/4] =?UTF-8?q?build(docker):=20add=20.dockerignore=20?=
 =?UTF-8?q?=E2=80=94=20keep=20local-only=20material=20out=20of=20images?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

COPY docs/ copied from the build context with no knowledge of .gitignore,
so gitignored local session docs were baked into the public image; the
tracked-release cleanliness gate then went red inside the container (no
.git => the gitless fallback walk scans everything) while staying green
in a git-aware checkout. Mirror the local-doc ignore rules, exclude
workspace outputs, VCS state, and local secret configs from the context.
---
 .dockerignore | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 .dockerignore

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..e512079
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,44 @@
+# Keep local-only material out of the public image AND out of the build
+# context upload. `COPY docs/ docs/` (Dockerfile) copies from the context
+# with no knowledge of .gitignore, so every gitignored-or-untracked local
+# doc would otherwise be baked into the released image — that is exactly
+# how the tracked-release cleanliness gate went red inside the container
+# (docs/WORKING_STATE.md) while staying green in a git-aware checkout.
+
+# VCS + local tooling state (never image material; huge context otherwise)
+.git
+.venv
+.claude
+**/__pycache__
+*.pyc
+
+# Runtime/workspace outputs
+outputs/
+artifacts/
+qf-demo/
+
+# Local research + coordination material (mirrors .gitignore docs rules)
+worldquant/
+docs/WORKING_STATE.md
+docs/quant_forge_overall_architecture.*
+docs/backtest_rebuild/
+docs/rd_evaluation_rebuild/
+docs/*_repair_ledger_*.md
+docs/first_principles_review_*.md
+
+# Untracked local drafts living under COPY'd dirs
+docs/getting_started_zh.md
+docs/research_platform_optimization_from_vibe_quantgpt.md
+
+# Local machine setup material at the context root
+mac_b_setup/
+dropbox_exclude.sh
+PROJECT_STATUS.md
+TWO_MAC_SYNC.md
+
+# Local secrets and machine-local configs must never enter an image
+configs/*.local.yaml
+configs/*.local.env
+configs/*.secrets.env
+*.local.env
+*.secrets.env

From 14abaf9e536f546adbb3c3d70d222c6d5b5d620e Mon Sep 17 00:00:00 2001
From: Quant Forge contributors <quant-forge@example.invalid>
Date: Thu, 16 Jul 2026 21:14:54 -0700
Subject: [PATCH 3/4] harden(web): close base_url key-exfiltration + lock the
 settings swap

Adversarial review of the runtime LLM settings endpoint surfaced one MAJOR
issue and hardening items; all addressed:

- MAJOR standing-key exfiltration: base_url was web-writable, so a caller
  could redirect an existing provider (e.g. deepseek) to an attacker URL
  with NO api_key and the next LLM call would ship the host's durable
  DEEPSEEK_API_KEY as a bearer token. Now a base_url change that would move
  an existing provider to a new host is refused unless the key is
  re-supplied in the same request -- forcing an attacker to bring their own
  (harmless) key. First-time preset setup (host+key together) is unaffected.
  No private-IP/SSRF blocklist: a local self-hosted model (127.0.0.1:11434)
  is a first-class OpenAI-compatible endpoint and must keep working.
- env-var name is now validated before the runtime key write (plain
  identifier, and PATH/LD_PRELOAD/PYTHONPATH refused) so a hand-edited
  api_key_env can't aim the write at a process-influencing variable.
- the settings read-modify-write (env inject + config swap + registry
  handoff) now runs under a lock, so two concurrent POSTs can't drop a
  registration; the swap comment states the true snapshot semantics.
- /api/status snapshots the closure config once to avoid a torn mid-swap read.
- tests register every touched provider env var with monkeypatch (no host
  key clobbered); new tests pin the exfiltration guard, the reserved-env
  refusal, and the concurrent-save no-drop invariant.
---
 src/quant_forge/apps/web/api.py     |  58 +++++++++++++-
 src/quant_forge/apps/web/routing.py |  58 ++++++++------
 tests/test_web_llm_settings.py      | 118 +++++++++++++++++++++++++---
 3 files changed, 197 insertions(+), 37 deletions(-)

diff --git a/src/quant_forge/apps/web/api.py b/src/quant_forge/apps/web/api.py
index 2fd30ae..832b375 100644
--- a/src/quant_forge/apps/web/api.py
+++ b/src/quant_forge/apps/web/api.py
@@ -2509,6 +2509,18 @@ def apply_llm_settings_update(
       (used by RD optimization and the sidecar readiness probe; parse jobs
       already choose per request).
 
+    Security: this is the only route that could turn workbench-operate access
+    into standing-secret exfiltration, so it refuses to point an existing
+    provider whose key already lives in the environment at a NEW ``base_url``
+    without the caller re-supplying the key in the SAME request. Otherwise a
+    caller could redirect, say, deepseek to ``http://attacker/v1`` with no key
+    and the next LLM call would ship the host's durable ``DEEPSEEK_API_KEY``
+    (from ``configs/*.local.env``) as a bearer token to the attacker's URL —
+    a credential the web layer is never allowed to reveal. Legitimate
+    first-time setup (host + key together) is unaffected. No private-IP/SSRF
+    blocklist is applied on purpose: a local self-hosted model
+    (``http://127.0.0.1:11434`` etc.) is a first-class OpenAI-compatible use.
+
     Returns the replacement frozen config plus a response payload shaped like
     the ``llm`` section of ``/api/status`` so the frontend can re-hydrate from
     the response alone (loopback binds never re-fetch ``/api/status``).
@@ -2526,10 +2538,13 @@ def apply_llm_settings_update(
     model = str(payload.get("model", "") or "").strip()
     base_url = str(payload.get("base_url", "") or "").strip()
     activate = _bool_parameter(payload.get("activate", True), "activate")
+    api_key = payload.get("api_key")
+    api_key_supplied = api_key is not None and str(api_key) != ""
 
     presets = {preset["provider"]: preset for preset in builtin_provider_presets()}
     api_key_env = ""
-    if name not in config.llm.providers:
+    existing = config.llm.providers.get(name)
+    if existing is None:
         preset = presets.get(name)
         if preset is None:
             known = ", ".join(sorted(set(config.llm.providers) | set(presets)))
@@ -2551,16 +2566,35 @@ def apply_llm_settings_update(
     )
     selected = new_llm.select_provider(name)
 
+    # Standing-key exfiltration guard (see the security note above): a base_url
+    # that actually changes the entry's host, without a key re-supplied here,
+    # is refused when the target env var is already populated. `base_url` is
+    # only truthy when the caller sent one (presets fill it before this point,
+    # but a brand-new preset registration has no standing key + no `existing`).
+    target_env = str(selected.api_key_env).strip()
+    prior_base_url = existing.base_url if existing is not None else ""
+    if (
+        base_url
+        and base_url != prior_base_url
+        and not api_key_supplied
+        and target_env
+        and os.environ.get(target_env)
+    ):
+        raise ValueError(
+            "changing base_url requires re-supplying api_key so a standing "
+            "credential is never sent to a newly specified host"
+        )
+
     key_updated = False
-    api_key = payload.get("api_key")
-    if api_key is not None and str(api_key) != "":
+    if api_key_supplied:
         credential = str(api_key)
         _validate_api_key_shape(credential)
-        env_name = str(selected.api_key_env).strip()
+        env_name = target_env
         if not env_name:
             raise ValueError(
                 f"provider {name} does not declare api_key_env; cannot accept an API key"
             )
+        _validate_env_var_name(env_name)
         # In-process only, by design: the LLM client resolves the key from the
         # environment on every call, so this takes effect immediately and
         # vanishes on restart. Never logged, never in any response payload.
@@ -2582,6 +2616,22 @@ def apply_llm_settings_update(
     return new_config, response
 
 
+def _validate_env_var_name(env_name: str) -> None:
+    """Refuse to write anything but a plain env-var identifier.
+
+    Presets use fixed ``*_API_KEY`` names and YAML is owner-controlled, so this
+    is defense-in-depth: it stops a future/hand-edited ``api_key_env`` from
+    aiming the runtime key write at a process-influencing variable
+    (``PATH``/``LD_PRELOAD``/``PYTHONPATH``/the control-token env). Mirrors the
+    identifier rule the env-*file* parser already enforces (config.py).
+    """
+
+    if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", env_name):
+        raise ValueError("api_key_env must be a plain environment-variable name")
+    if env_name.endswith(("PATH", "PRELOAD")) or env_name in {"PATH", "LD_PRELOAD", "PYTHONPATH"}:
+        raise ValueError(f"refusing to write reserved environment variable: {env_name}")
+
+
 def _validate_api_key_shape(credential: str) -> None:
     """Shape-only checks; error text never includes the submitted value."""
 
diff --git a/src/quant_forge/apps/web/routing.py b/src/quant_forge/apps/web/routing.py
index 223df46..eb3c43c 100644
--- a/src/quant_forge/apps/web/routing.py
+++ b/src/quant_forge/apps/web/routing.py
@@ -17,6 +17,7 @@
 import json
 import os
 from pathlib import Path
+import threading
 from typing import Any
 from urllib.parse import unquote, urlparse
 
@@ -357,16 +358,26 @@ def create_local_web_server(
     sidecar_sessions = SidecarSessionStore(config.paths.artifact_root)
     control_token = _control_token_for_bind(host, config)
     control_token_required = bool(control_token)
+    # Serializes the read-modify-write of the settings swap so two concurrent
+    # /api/settings/llm POSTs (ThreadingHTTPServer) can't both build off the
+    # same pre-swap snapshot and drop one registration.
+    settings_lock = threading.Lock()
 
-    def _swap_runtime_config(new_config: QuantForgeConfig) -> None:
-        # /api/settings/llm applies a runtime LLM update by atomically
-        # replacing the closure's frozen config snapshot (reference
-        # assignment; in-flight requests keep the snapshot they already
-        # read). The tool registry captured its own reference at
-        # construction, so it gets the replacement explicitly.
+    def _apply_llm_settings(payload: dict[str, Any]) -> dict[str, Any]:
+        # Runtime LLM settings write. The whole read-modify-write is held under
+        # settings_lock so the env-key injection and the config swap commit
+        # together. The swap reassigns the closure's `config` cell: subsequent
+        # NEW requests and deferred jobs/scheduler read the live value, while a
+        # synchronous request already mid-flight keeps the locals it read. The
+        # tool registry captured its own reference at construction, so it gets
+        # the replacement explicitly.
         nonlocal config
-        config = new_config
-        tool_registry.apply_runtime_config(new_config)
+        with settings_lock:
+            new_config, response = _server.apply_llm_settings_update(config, payload)
+            config = new_config
+            tool_registry.apply_runtime_config(new_config)
+            response["rd"] = _rd_status_payload(new_config, research_config)
+            return response
 
     class Handler(BaseHTTPRequestHandler):
         def do_GET(self) -> None:
@@ -455,18 +466,21 @@ def do_GET(self) -> None:
                     self._json(memory_review_payload(memory_store))
                 elif path == "/api/status":
                     self._require_control_token()
-                    active_llm = _active_llm(config)
+                    # Snapshot the closure config once: a settings swap landing
+                    # mid-response must not yield a JSON mixing pre/post state.
+                    cfg = config
+                    active_llm = _active_llm(cfg)
                     self._json(
                         {
                             "name": "Quant Forge",
-                            "paths": _paths_payload(config),
+                            "paths": _paths_payload(cfg),
                             "llm": {
                                 "provider": active_llm.provider,
                                 "model": active_llm.model,
                                 "api_key_env": active_llm.api_key_env,
-                                "providers": _llm_provider_options(config),
+                                "providers": _llm_provider_options(cfg),
                             },
-                            "rd": _rd_status_payload(config, research_config),
+                            "rd": _rd_status_payload(cfg, research_config),
                         }
                     )
                 elif path == "/api/research/status":
@@ -566,18 +580,14 @@ def do_POST(self) -> None:
                 self._require_control_token()
                 payload = self._read_json()
                 if path == "/api/settings/llm":
-                    # Runtime LLM settings write: registers/updates a provider,
-                    # optionally injects the API key into this process's env
-                    # (never persisted, never echoed), then swaps the closure
-                    # config so every later request sees the new active
-                    # provider. ValueError -> 400 via the generic mapping.
-                    new_config, response = _server.apply_llm_settings_update(config, payload)
-                    _swap_runtime_config(new_config)
-                    # rd section rides along so the frontend can re-hydrate
-                    # the whole runtime strip from this response alone
-                    # (loopback binds never re-fetch /api/status).
-                    response["rd"] = _rd_status_payload(new_config, research_config)
-                    self._json(response)
+                    # Registers/updates a provider, optionally injects the API
+                    # key into this process's env (never persisted, echoed, or
+                    # logged), then swaps the closure config so every later
+                    # request sees the new active provider. The rd section
+                    # rides along so the frontend re-hydrates the whole runtime
+                    # strip from this response alone (loopback binds never
+                    # re-fetch /api/status). ValueError -> 400 below.
+                    self._json(_apply_llm_settings(payload))
                     return
                 if path == "/api/run-idea":
                     result = _server.run_idea_workflow(
diff --git a/tests/test_web_llm_settings.py b/tests/test_web_llm_settings.py
index 796dc73..acd8eff 100644
--- a/tests/test_web_llm_settings.py
+++ b/tests/test_web_llm_settings.py
@@ -55,10 +55,12 @@ def _config_with_deepseek(tmp_path: Path) -> QuantForgeConfig:
 
 @pytest.fixture()
 def llm_web_app(tmp_path, monkeypatch):
-    # The glm preset injects into the REAL preset env name; snapshot both so
-    # the test never leaks state into (or reads state from) the dev machine.
-    monkeypatch.delenv("GLM_API_KEY", raising=False)
-    monkeypatch.delenv(_DS_ENV, raising=False)
+    # Preset saves inject into the REAL preset env names; register every env
+    # var these tests touch with monkeypatch so a raw os.environ write inside
+    # the endpoint is reverted at teardown and never clobbers a developer's
+    # real key on the host.
+    for env_name in ("GLM_API_KEY", "ANTHROPIC_API_KEY", "CLAUDE_API_KEY", _DS_ENV):
+        monkeypatch.delenv(env_name, raising=False)
     create_demo_workspace(tmp_path / "demo")
     server = create_local_web_server(
         host="127.0.0.1", port=0, config=_config_with_deepseek(tmp_path)
@@ -142,17 +144,82 @@ def test_llm_settings_registers_preset_and_switches_active(llm_web_app) -> None:
 
 
 def test_llm_settings_accepts_provider_alias(llm_web_app) -> None:
+    # The fixture registers ANTHROPIC_API_KEY with monkeypatch, so the raw
+    # os.environ write inside the endpoint is reverted at teardown.
     status, body = _post(
         f"{llm_web_app}/api/settings/llm",
         {"provider": "anthropic", "model": "claude-test-model", "api_key": _DUMMY_KEY + "-c"},
     )
+    assert status == 200
+    response = json.loads(body.decode("utf-8"))
+    assert response["llm"]["provider"] == "claude"
+    assert os.environ.get("ANTHROPIC_API_KEY") == _DUMMY_KEY + "-c"
+
+
+def test_base_url_redirect_of_standing_key_provider_is_refused(llm_web_app) -> None:
+    # Standing-key exfiltration guard: deepseek's key is already in the env,
+    # so pointing it at a new host WITHOUT re-supplying the key must 400 and
+    # leave both the env key and the provider base_url untouched.
+    os.environ[_DS_ENV] = "qf-standing-victim-key"
+    status, body = _post(
+        f"{llm_web_app}/api/settings/llm",
+        {"provider": "deepseek", "base_url": "http://attacker.example/v1"},
+    )
+    assert status == 400
+    assert "re-supplying api_key" in json.loads(body.decode("utf-8"))["error"]
+    assert os.environ.get(_DS_ENV) == "qf-standing-victim-key"
+
+    status, body = _get(f"{llm_web_app}/api/status")
+    deepseek = next(
+        o for o in json.loads(body.decode("utf-8"))["llm"]["providers"] if o["provider"] == "deepseek"
+    )
+    assert deepseek["base_url"] == "http://localhost/v1"  # unchanged; redirect never applied
+    assert "attacker.example" not in body.decode("utf-8")
+
+    # Re-supplying the key in the SAME request is the legitimate move-host flow.
+    status, body = _post(
+        f"{llm_web_app}/api/settings/llm",
+        {"provider": "deepseek", "base_url": "http://my-proxy.local/v1", "api_key": "qf-new-owner-key"},
+    )
+    assert status == 200
+    assert "qf-new-owner-key" not in body.decode("utf-8")
+    assert os.environ.get(_DS_ENV) == "qf-new-owner-key"
+
+
+def test_llm_settings_refuses_reserved_env_var_write(tmp_path, monkeypatch) -> None:
+    # A provider whose api_key_env aims at a process-influencing variable must
+    # never become web-writable, even though presets/YAML normally prevent it.
+    monkeypatch.delenv("GLM_API_KEY", raising=False)
+    create_demo_workspace(tmp_path / "demo")
+    config = QuantForgeConfig(
+        llm=LLMSettings(
+            provider="deepseek",
+            providers={
+                "evil": LLMProviderSettings(
+                    provider="evil",
+                    model="m",
+                    base_url="http://localhost/v1",
+                    api_key_env="PATH",
+                ),
+            },
+        )
+    ).resolve(tmp_path / "demo")
+    original_path = os.environ.get("PATH")
+    server = create_local_web_server(host="127.0.0.1", port=0, config=config)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
     try:
-        assert status == 200
-        response = json.loads(body.decode("utf-8"))
-        assert response["llm"]["provider"] == "claude"
-        assert os.environ.get("ANTHROPIC_API_KEY") == _DUMMY_KEY + "-c"
+        status, body = _post(
+            f"http://127.0.0.1:{server.server_address[1]}/api/settings/llm",
+            {"provider": "evil", "api_key": "qf-x"},
+        )
+        assert status == 400
+        assert "environment variable" in json.loads(body.decode("utf-8"))["error"]
+        assert os.environ.get("PATH") == original_path
     finally:
-        os.environ.pop("ANTHROPIC_API_KEY", None)
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=2.0)
 
 
 def test_llm_settings_rejects_bad_inputs(llm_web_app) -> None:
@@ -224,6 +291,39 @@ def test_llm_settings_requires_control_token_on_docker_bind(tmp_path, monkeypatc
         thread.join(timeout=2.0)
 
 
+def test_concurrent_settings_posts_do_not_drop_a_registration(llm_web_app) -> None:
+    # MINOR (review): the settings swap is a read-modify-write under
+    # ThreadingHTTPServer; without the lock two concurrent preset saves could
+    # both build off the pre-swap snapshot and the last swap would drop the
+    # other. Fire both at once and assert BOTH providers survive in the final
+    # config, and both env keys landed. GLM_API_KEY/ANTHROPIC_API_KEY are
+    # registered with monkeypatch by the fixture, so teardown reverts them.
+    results: dict[str, int] = {}
+
+    def _save(provider: str, model: str, key: str) -> None:
+        status, _ = _post(
+            f"{llm_web_app}/api/settings/llm",
+            {"provider": provider, "model": model, "api_key": key, "activate": False},
+        )
+        results[provider] = status
+
+    threads = [
+        threading.Thread(target=_save, args=("glm", "glm-m", _DUMMY_KEY + "-g")),
+        threading.Thread(target=_save, args=("anthropic", "claude-m", _DUMMY_KEY + "-c")),
+    ]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join(timeout=10)
+
+    assert results == {"glm": 200, "anthropic": 200}
+    status, body = _get(f"{llm_web_app}/api/status")
+    names = {o["provider"] for o in json.loads(body.decode("utf-8"))["llm"]["providers"]}
+    assert {"glm", "claude", "deepseek"} <= names  # neither concurrent save dropped
+    assert os.environ.get("GLM_API_KEY") == _DUMMY_KEY + "-g"
+    assert os.environ.get("ANTHROPIC_API_KEY") == _DUMMY_KEY + "-c"
+
+
 def test_builtin_presets_expose_metadata_only() -> None:
     presets = builtin_provider_presets()
     names = {preset["provider"] for preset in presets}

From c896338989ab0909b5618e84a9ae497556c32c45 Mon Sep 17 00:00:00 2001
From: Quant Forge contributors <quant-forge@example.invalid>
Date: Thu, 16 Jul 2026 23:29:56 -0700
Subject: [PATCH 4/4] docs(readme): document Web-UI runtime LLM provider
 switching

Add a subsection under LLM Provider Setup covering the new
POST /api/settings/llm frontend path: the provider menu now offers the
built-in presets, the key is injected into the server process environment
only (never persisted/echoed/logged), the settings write is control-token
gated on a 0.0.0.0 bind, and a base_url change to an existing provider
requires re-supplying the key.
---
 README.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README.md b/README.md
index 782f6e4..4d9eafb 100644
--- a/README.md
+++ b/README.md
@@ -352,6 +352,35 @@ features. RD does not have a second API-key setting.
 
 LLM 语义解析和 RD LLM 功能共用同一个当前 provider；RD 不再单独配置第二套 API key。
 
+### Switching providers from the Web UI / 在网页端切换大模型
+
+The workbench can also register a provider and take an API key at runtime, so
+you can try a model without editing YAML or restarting the server. In the
+expert-mode control rail, the **LLM Provider** menu lists the configured
+providers plus the built-in presets (`deepseek`, `openai`, `openai_compatible`,
+`glm`, `claude`, `minimax`). Switch **LLM API Key** to *前端输入 / manual*, enter
+the key (and, for a preset with no default, the model / base URL), and click
+**保存并启用 / Save & enable**.
+
+The key is injected into the **running server process environment only**. It is
+never written to disk, never echoed in any response, and never logged; a restart
+clears it. For a durable key, keep using the ignored `configs/*.local.env` path
+above. Like every mutating Web action, the settings write requires the browser
+control token on a Docker/`0.0.0.0` bind. Pointing an existing provider at a new
+`base_url` requires re-supplying the key in the same request, so a standing key
+is never sent to a newly specified host.
+
+网页端也可以在运行时注册 provider 并接收 API key，无需改 YAML 或重启即可试用某个
+模型。在专家模式左侧控制栏，**LLM Provider** 下拉会列出已配置 provider 以及内置预设
+（`deepseek`、`openai`、`openai_compatible`、`glm`、`claude`、`minimax`）。把
+**LLM API Key** 切到「前端输入」，填入密钥（预设无默认值时再补填模型名 / base URL），
+点击「保存并启用」。
+
+密钥只注入**运行中的服务进程环境变量**：不写磁盘、不在任何响应中回显、不进日志，重启即
+失效；如需持久保存，仍走上文被忽略的 `configs/*.local.env`。与所有会改状态的 Web 操作
+一样，在 Docker / `0.0.0.0` 绑定下该写入需要浏览器控制令牌。把已有 provider 指向新的
+`base_url` 时必须在同一请求内重新提交密钥，以确保常驻密钥不会被发往新指定的地址。
+
 ## Configuration Files / 配置文件
 
 | File | Purpose |