feat(claude-code): pin a fixed Meridian profile, decoupled from terminal login (P0)

OpenProgram's claude-code provider followed whatever account the terminal
`claude auth login` last logged in (Meridian with no profile uses the
keychain's current session), so switching the Claude Code account dragged
OpenProgram along. Now OpenProgram pins a fixed Meridian account by
injecting `x-meridian-profile` (Meridian's highest-priority profile
selector) on every claude-code request, read from
config.providers.claude-code.meridian_profile (or env
CLAUDE_MAX_PROXY_PROFILE / MERIDIAN_PROFILE) per request — live (no
restart) and independent of the keychain login.

Injection lives in openai_completions.stream_simple (the single chokepoint
every claude-code request passes through) via an inject_profile_header()
helper in the claude-code module. An adversarial review caught that the
first cut (in providers/stream.py's wrapper) was bypassed by
memory/llm_bridge.py calling the raw api-provider directly, which would
have leaked summarization traffic onto the terminal account; moving it
down covers every path. Gating on provider=="claude-code" inside
openai_completions also means a future claude-code-cli (different wire)
model can't get a meaningless header.

Tests (10): inject_profile_header behaviour, meridian_profile() precedence
+ non-string guard, and an integration test that the header reaches the
openai client default_headers. Verified end-to-end over real HTTP.

P1 (WebUI profile picker) and P2 (auto-install Meridian) still to come —
see docs/design/claude-code-meridian-profile.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Fzkuji

docs/design/claude-code-meridian-profile.md

@@ -62,19 +62,24 @@ header `x-meridian-profile: <name>` 是最高优先级**,会盖过钥匙串当
 
 ### 注入点
 
-`openprogram/providers/stream.py` 的 `stream_simple()` —— 所有 provider 的
-统一入口,已经在这里做 per-provider 处理(注入 api_key)。在调
-`provider.stream_simple(...)` 之前,若 `model.provider == "claude-code"`
-且解析出 profile,就把 `x-meridian-profile` 合并进 `opts.headers`。
-
-选这里而不是 `openai_completions`(claude-code 走的 wire)的原因:
-
-- `openai_completions` 是被很多 provider 共用的通用层,不该塞 claude-code
-  专属逻辑;
-- `stream.py` 已经按 `model.provider` 做事,语义一致;
-- 注入到 `opts.headers` 后,`openai_completions` 现有的
-  `extra_headers = opts.headers or {}` 直接发出去,**openai_completions
-  无需改动**。
+`openprogram/providers/openai_completions/openai_completions.py` 的
+`stream_simple()` —— **claude-code 所有请求的唯一必经点**。claude-code 的
+model `api="openai-completions"`,所以不论请求经由 `providers/stream.py`
+的统一 wrapper、还是被某些调用方(如 `memory/llm_bridge.py` 直接调
+`api_provider.stream_simple`)绕过 wrapper,最终都落到这个函数。
+
+> 设计评审纠正:最初把注入放在 `providers/stream.py` 的 wrapper 里,但对抗
+> 审查发现 `memory/llm_bridge.py` 直接调 raw api-provider、绕过 wrapper,
+> 于是 memory summarization 在默认模型是 claude-code 时仍不带 header、泄漏
+> 到终端登录账号 —— 正是本设计要消除的耦合。改放 openai_completions 这个
+> chokepoint 后覆盖全部路径。
+
+注入逻辑封装在 claude-code 模块的
+`_claude_max_proxy_registry.inject_profile_header(model, headers)`(不把
+claude-code 专属逻辑塞进通用层),`openai_completions` 仅在
+`model.provider == "claude-code"` 时惰性 import 并调用它。由于只有
+`api="openai-completions"` 的 model 才会进 openai_completions,将来即便重新
+启用 `claude-code-cli`(另一种 wire)的同名 provider 模型,也不会被误注入。
 
 ### 立即生效
 
@@ -88,10 +93,22 @@ worker**。`opts` 用 `model_copy` 注入,不改原对象,无副作用。
 尊重调用方的(per-call 比全局配置更具体)。即:
 `{"x-meridian-profile": profile, **(opts.headers or {})}`。
 
-### `_meridian_profile()` 落点
+### `meridian_profile()` / `inject_profile_header()` 落点
 
 放在 `openprogram/providers/anthropic/_claude_max_proxy_registry.py`
-(claude-code 相关模块已经在这),`stream.py` 惰性 import 以避免循环。
+(claude-code 相关模块已经在这),`openai_completions` 惰性 import 以避免
+循环。`meridian_profile()` 对非字符串配置值做 `str()` 兜底,免得手改
+config.json 写错类型时在 `.strip()` 抛错被静默吞掉。
+
+### 已知限制
+
+- **不校验 profile 是否真实存在**:Meridian 没有 JSON profiles API,这一层
+  无法在发请求前确认 `meridian_profile` 名字有效。名字错了由 Meridian 决定
+  行为(报错→正常 API error,或静默回落到它的 default = 可能用错账号)。
+  P1 的 WebUI picker 用 `meridian profile list` 把可选值约束到已知 profile,
+  从源头堵住这个问题。
+- **每请求读一次 config.json**(~0.3ms,被代理+模型网络往返淹没)。为支持
+  "WebUI 改了立即生效"而不缓存;若日后成为热点,可按 mtime 记忆化。
 
 ## P1(后续)WebUI 配置入口
 
@@ -109,9 +126,12 @@ worker**。`opts` 用 `model_copy` 注入,不改原对象,无副作用。
 
 ## 验证
 
-- 单元:`stream_simple` 对 `model.provider=="claude-code"` 且配了 profile
-  时,`provider.stream_simple` 收到的 `opts.headers` 含
-  `x-meridian-profile`;未配时不含;非 claude-code provider 永不受影响。
-- 端到端:配 profile 后从 OpenProgram 实跑一次 claude-code,确认 Meridian
-  路由到该 profile 的账号;`claude auth status`(终端)仍是另一个账号、
-  不受影响。
+- 单元(`tests/unit/test_claude_code_meridian_profile.py`,10 passed):
+  `inject_profile_header` 在 claude-code + pin 时加 header,未配 / 其他
+  provider / caller 自带 header 时的行为;`meridian_profile()` 的
+  config > env > None 优先级与非字符串兜底;集成测试确认 claude-code 经
+  `openai_completions.stream_simple` 时 header 真的进了 openai client 的
+  `default_headers`。
+- 端到端(P1/P2 配好 profile 后):从 OpenProgram 实跑一次 claude-code,确认
+  Meridian 路由到该 profile 的账号;`claude auth status`(终端)仍是另一个
+  账号、不受影响。

openprogram/providers/anthropic/_claude_max_proxy_registry.py

@@ -36,6 +36,75 @@ def _proxy_base_url() -> str:
     return base
 
 
+def meridian_profile() -> str | None:
+    """The Meridian profile OpenProgram's claude-code traffic is pinned to.
+
+    Meridian (the local Claude proxy) can hold several Claude accounts as
+    named profiles and routes each request to the one named by an
+    ``x-meridian-profile`` header — its highest-priority profile selector,
+    overriding both the keychain's current ``claude auth login`` session
+    and Meridian's own active/default profile. Pinning one here is what
+    decouples OpenProgram's Claude account from the terminal Claude Code
+    login (see docs/design/claude-code-meridian-profile.md).
+
+    Resolution order:
+      1. ``config.providers.claude-code.meridian_profile`` — set manually
+         in config.json today; a WebUI control to write it is P1 (planned).
+         Read per request so a change takes effect live.
+      2. env ``CLAUDE_MAX_PROXY_PROFILE`` (alias ``MERIDIAN_PROFILE``).
+      3. ``None`` — no header; Meridian falls back to its active/default
+         profile or the keychain login (unchanged legacy behaviour).
+
+    No validation that the named profile actually exists in Meridian —
+    that needs a Meridian profiles API we don't have. A bad name makes
+    Meridian either error (surfaced as a normal API error) or silently use
+    its default; the WebUI picker (P1) will constrain the value to known
+    profiles so this can't happen via the UI.
+    """
+    try:
+        from openprogram.setup import _read_config
+
+        pcfg = (_read_config().get("providers") or {}).get("claude-code") or {}
+        # str() guards a hand-edited non-string value (e.g. a bare number)
+        # from raising inside .strip() and being swallowed below.
+        val = str(pcfg.get("meridian_profile") or "").strip()
+        if val:
+            return val
+    except Exception:
+        # config unreadable (fresh install, race) — fall through to env.
+        pass
+    val = (
+        os.environ.get("CLAUDE_MAX_PROXY_PROFILE")
+        or os.environ.get("MERIDIAN_PROFILE")
+        or ""
+    ).strip()
+    return val or None
+
+
+def inject_profile_header(model, headers: dict | None) -> dict:
+    """Return ``headers`` plus the pinned ``x-meridian-profile`` for
+    claude-code, if one is configured and the caller didn't set it.
+
+    Called from ``openai_completions.stream_simple`` — the single layer
+    every claude-code request passes through (the ``providers/stream.py``
+    wrapper is bypassed by some callers, e.g. memory summarization). The
+    gate on ``provider == "claude-code"`` plus the fact that only
+    ``api == "openai-completions"`` models reach openai_completions means a
+    CLI-api claude-code model (different wire) never gets a meaningless
+    header. A caller-supplied ``x-meridian-profile`` wins (it's more
+    specific than the global config binding). Always returns a fresh dict.
+    """
+    out = dict(headers or {})
+    if (
+        getattr(model, "provider", None) == "claude-code"
+        and "x-meridian-profile" not in out
+    ):
+        profile = meridian_profile()
+        if profile:
+            out["x-meridian-profile"] = profile
+    return out
+
+
 # Only three model ids the ``claude-max-api`` proxy actually
 # recognises (verified against ``GET /v1/models`` on v1.0.0). Anything
 # else the proxy silently downgrades to ``claude-haiku-4``, so we

openprogram/providers/openai_completions/openai_completions.py

@@ -198,6 +198,16 @@ async def stream_simple(
 
     base_url = model.base_url if model.base_url != "https://api.openai.com/v1" else None
     extra_headers = opts.headers or {}
+    # claude-code: pin a fixed Meridian account (profile) so OpenProgram's
+    # Claude subscription is decoupled from whatever the terminal
+    # `claude auth login` last logged in. This is the single chokepoint
+    # every claude-code request passes through (the providers/stream.py
+    # wrapper is bypassed by some callers, e.g. memory summarization), so
+    # the injection lives here, not there. No-op for every other provider.
+    # See docs/design/claude-code-meridian-profile.md.
+    if model.provider == "claude-code":
+        from ..anthropic._claude_max_proxy_registry import inject_profile_header
+        extra_headers = inject_profile_header(model, extra_headers)
 
     # Match other HTTP providers' stream retry budget (default 3) so
     # transient 429/5xx/connect failures are absorbed without

openprogram/providers/stream.py

@@ -61,6 +61,13 @@ async def stream_simple(
     if not opts.api_key:
         opts = opts.model_copy(update={"api_key": get_env_api_key(model.provider)})
 
+    # NOTE: the claude-code Meridian-profile header (x-meridian-profile) is
+    # injected one layer down, in openai_completions.stream_simple — that's
+    # the single chokepoint EVERY claude-code request passes through. This
+    # wrapper is bypassed by some callers (e.g. memory/llm_bridge.py calls
+    # the raw api-provider directly), so injecting here would miss them.
+    # See docs/design/claude-code-meridian-profile.md.
+
     provider = get_api_provider(model.api)
     if provider is None:
         raise ValueError(f"No stream function registered for API: {model.api!r}")

tests/unit/test_claude_code_meridian_profile.py

@@ -0,0 +1,141 @@
+"""claude-code pins a fixed Meridian account (profile) via the
+``x-meridian-profile`` header, so OpenProgram's Claude subscription is
+decoupled from whatever the terminal ``claude auth login`` last logged
+in. See docs/design/claude-code-meridian-profile.md.
+
+The injection lives in ``openai_completions.stream_simple`` — the single
+chokepoint every claude-code request passes through (the
+``providers/stream.py`` wrapper is bypassed by some callers, e.g. memory
+summarization). Tests cover the pure resolver/injector plus an
+integration check that the header actually reaches the openai client.
+
+Note: several provider modules are shadowed as package attributes, so we
+grab the real module objects from ``sys.modules`` and patch by object.
+"""
+from __future__ import annotations
+
+import asyncio
+import sys
+from types import SimpleNamespace
+
+import openprogram.providers.openai_completions.openai_completions  # noqa: F401
+import openprogram.providers.anthropic._claude_max_proxy_registry  # noqa: F401
+import openprogram.setup  # noqa: F401
+from openprogram.providers.types import Context, Model, SimpleStreamOptions
+
+_REG = sys.modules["openprogram.providers.anthropic._claude_max_proxy_registry"]
+_OC = sys.modules["openprogram.providers.openai_completions.openai_completions"]
+_SETUP = sys.modules["openprogram.setup"]
+
+
+def _model(provider: str, api: str = "openai-completions") -> Model:
+    return Model(
+        id="claude-sonnet-4", name="x", api=api, provider=provider,
+        base_url="http://localhost:3456/v1",
+    )
+
+
+# ── inject_profile_header (pure) ──────────────────────────────────────────
+
+def test_injects_for_claude_code_when_pinned(monkeypatch):
+    monkeypatch.setattr(_REG, "meridian_profile", lambda: "experiment")
+    out = _REG.inject_profile_header(_model("claude-code"), {"a": "1"})
+    assert out["x-meridian-profile"] == "experiment"
+    assert out["a"] == "1"  # existing headers preserved
+
+
+def test_no_header_when_no_profile(monkeypatch):
+    monkeypatch.setattr(_REG, "meridian_profile", lambda: None)
+    out = _REG.inject_profile_header(_model("claude-code"), None)
+    assert "x-meridian-profile" not in out
+
+
+def test_other_provider_never_injected(monkeypatch):
+    # Even with a profile configured, a non-claude-code model must not get it.
+    monkeypatch.setattr(_REG, "meridian_profile", lambda: "experiment")
+    out = _REG.inject_profile_header(_model("openai"), None)
+    assert "x-meridian-profile" not in out
+
+
+def test_caller_header_wins(monkeypatch):
+    monkeypatch.setattr(_REG, "meridian_profile", lambda: "experiment")
+    out = _REG.inject_profile_header(
+        _model("claude-code"), {"x-meridian-profile": "adhoc"},
+    )
+    assert out["x-meridian-profile"] == "adhoc"
+
+
+def test_returns_fresh_dict(monkeypatch):
+    monkeypatch.setattr(_REG, "meridian_profile", lambda: "experiment")
+    src = {"a": "1"}
+    out = _REG.inject_profile_header(_model("claude-code"), src)
+    assert out is not src and "x-meridian-profile" not in src
+
+
+# ── meridian_profile() resolution ─────────────────────────────────────────
+
+def _cfg(profile):
+    return {"providers": {"claude-code": {"meridian_profile": profile}}}
+
+
+def test_resolve_config_wins_over_env(monkeypatch):
+    monkeypatch.setattr(_SETUP, "_read_config", lambda: _cfg("acctA"))
+    monkeypatch.setenv("CLAUDE_MAX_PROXY_PROFILE", "envP")
+    assert _REG.meridian_profile() == "acctA"
+
+
+def test_resolve_env_fallback(monkeypatch):
+    monkeypatch.setattr(_SETUP, "_read_config", lambda: {"providers": {}})
+    monkeypatch.delenv("MERIDIAN_PROFILE", raising=False)
+    monkeypatch.setenv("CLAUDE_MAX_PROXY_PROFILE", "envP")
+    assert _REG.meridian_profile() == "envP"
+
+
+def test_resolve_none_when_unset(monkeypatch):
+    monkeypatch.setattr(_SETUP, "_read_config", lambda: {})
+    monkeypatch.delenv("CLAUDE_MAX_PROXY_PROFILE", raising=False)
+    monkeypatch.delenv("MERIDIAN_PROFILE", raising=False)
+    assert _REG.meridian_profile() is None
+
+
+def test_resolve_non_string_config_does_not_crash(monkeypatch):
+    # A hand-edited non-string value must not raise (and get swallowed).
+    monkeypatch.setattr(_SETUP, "_read_config", lambda: _cfg(123))
+    monkeypatch.delenv("CLAUDE_MAX_PROXY_PROFILE", raising=False)
+    monkeypatch.delenv("MERIDIAN_PROFILE", raising=False)
+    assert _REG.meridian_profile() == "123"  # coerced, not crashed
+
+
+# ── integration: openai_completions actually sends the header ─────────────
+
+def test_openai_completions_sends_header_for_claude_code(monkeypatch):
+    captured: dict = {}
+
+    class _FakeClient:
+        def __init__(self, **kwargs):
+            captured["default_headers"] = kwargs.get("default_headers")
+
+            async def _create(**_):
+                raise RuntimeError("stop-after-client-built")
+
+            self.chat = SimpleNamespace(
+                completions=SimpleNamespace(create=_create),
+            )
+
+    monkeypatch.setattr(_OC._openai, "AsyncOpenAI", _FakeClient)
+    monkeypatch.setattr(_REG, "meridian_profile", lambda: "experiment")
+
+    async def go() -> None:
+        try:
+            async for _ in _OC.stream_simple(
+                _model("claude-code"), Context(messages=[]),
+                SimpleStreamOptions(api_key="x"),
+            ):
+                pass
+        except Exception:
+            pass  # create aborts on purpose; client (+headers) already built
+
+    asyncio.run(go())
+    assert (captured.get("default_headers") or {}).get(
+        "x-meridian-profile"
+    ) == "experiment"