mtrx-cli 0.1.0

package/src/matrx/cli/launcher.py

@@ -0,0 +1,796 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import datetime as dt
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import uuid
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.10 compatibility
+    tomllib = None
+from dataclasses import dataclass
+from pathlib import Path
+
+from matrx.cli.state import (
+    DEFAULT_MATRX_BASE_URL,
+    ensure_root_url,
+    ensure_v1_url,
+    get_workspace_binding,
+    set_workspace_binding,
+)
+
+
+def _capture_env_snapshot() -> dict:
+    """Capture OS, shell, cwd, venv, node for evolutionary scaffolding injection."""
+    import subprocess as _sp
+    out: dict = {
+        "os": platform.system(),
+        "shell": os.environ.get("SHELL", os.environ.get("COMSPEC", "")),
+        "cwd": os.getcwd(),
+    }
+    out["venv"] = os.environ.get("VIRTUAL_ENV", "") or None
+    if not out["venv"]:
+        out["venv_active"] = False
+    node = shutil.which("node")
+    if node:
+        try:
+            r = _sp.run([node, "-v"], capture_output=True, text=True, timeout=2)
+            out["node"] = r.stdout.strip() if r.returncode == 0 else None
+        except Exception:
+            out["node"] = None
+    else:
+        out["node"] = None
+    return out
+
+
+MATRX_ENV_KEYS = {
+    "MTRX_KEY",
+    "OPENAI_BASE_URL",
+    "OPENAI_API_BASE",
+    "OPENAI_API_KEY",
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "ANTHROPIC_CUSTOM_HEADERS",
+}
+
+MTRX_CODEX_BLOCK_START = "# >>> mtrx managed codex route >>>"
+MTRX_CODEX_BLOCK_END = "# <<< mtrx managed codex route <<<"
+VALID_ROUTES = {"direct", "matrx"}
+
+
+@dataclass
+class LaunchPlan:
+    tool: str
+    route: str
+    executable: str
+    args: list[str]
+    env: dict[str, str]
+    auth_source: str
+
+
+def configured_route(state: dict, tool: str) -> str | None:
+    route = state.get("defaults", {}).get(tool)
+    if route in VALID_ROUTES:
+        return str(route)
+    return None
+
+
+def resolve_route(state: dict, tool: str, route_override: str | None) -> str:
+    if route_override:
+        return route_override
+    return configured_route(state, tool) or "direct"
+
+
+def initialize_first_launch_route(state: dict, tool: str, route_override: str | None) -> bool:
+    if route_override:
+        return False
+    if configured_route(state, tool) is not None:
+        return False
+    state.setdefault("defaults", {})[tool] = "matrx"
+    return True
+
+
+def find_executable(tool: str) -> str | None:
+    candidates = [tool]
+    if tool == "claude":
+        candidates.extend(["claude.exe", "claude.cmd"])
+    if tool == "codex":
+        candidates.extend(["codex.exe", "codex.cmd"])
+    for candidate in candidates:
+        found = shutil.which(candidate)
+        if found:
+            return found
+    return None
+
+
+def build_launch_plan(
+    state: dict,
+    *,
+    tool: str,
+    route_override: str | None = None,
+    passthrough_args: list[str] | None = None,
+    base_env: dict[str, str] | None = None,
+) -> LaunchPlan:
+    executable = find_executable(tool)
+    if not executable:
+        raise ValueError(f"{tool} executable not found in PATH")
+
+    route = resolve_route(state, tool, route_override)
+    env = dict(base_env or os.environ)
+    auth_source = ""
+    launch_args = list(passthrough_args or [])
+
+    if tool == "codex":
+        env, auth_source, launch_args = _build_codex_env(
+            state,
+            route,
+            env,
+            launch_args,
+        )
+    elif tool == "claude":
+        env, auth_source = _build_claude_env(state, route, env)
+    else:
+        raise ValueError(f"Unsupported tool: {tool}")
+
+    return LaunchPlan(
+        tool=tool,
+        route=route,
+        executable=executable,
+        args=launch_args,
+        env=env,
+        auth_source=auth_source,
+    )
+
+
+def prepare_routed_setup(
+    state: dict,
+    *,
+    tool: str,
+    route_override: str | None = None,
+    base_env: dict[str, str] | None = None,
+) -> tuple[dict, bool]:
+    """
+    Inline setup for routed launches.
+
+    Returns (mutated_state, changed).
+    Raises ValueError when the launch should abort.
+    """
+    route = resolve_route(state, tool, route_override)
+    changed = False
+    env = dict(base_env or os.environ)
+    if route == "matrx" and _ensure_matrx_auth(state, env=env):
+        changed = True
+    if route == "matrx" and _persist_workspace_binding_from_env(state, env):
+        changed = True
+
+    if _sync_tool_route_config(state, tool=tool, route=route):
+        changed = True
+
+    if route != "matrx":
+        return state, changed
+
+    return state, changed
+
+
+def launch(plan: LaunchPlan) -> int:
+    result = subprocess.run([plan.executable, *plan.args], env=plan.env, check=False)
+    return int(result.returncode)
+
+
+def validate_launch_plan(plan: LaunchPlan, state: dict) -> None:
+    """Validate launch plan before spawning the process."""
+    if plan.tool == "claude":
+        _validate_claude_launch_plan(plan, state)
+    if plan.tool == "codex":
+        _validate_codex_launch_plan(plan, state)
+
+
+def claude_credentials_path() -> Path:
+    return Path.home() / ".claude" / ".credentials.json"
+
+
+def claude_settings_path() -> Path:
+    return Path.home() / ".claude" / "settings.json"
+
+
+def codex_config_path() -> Path:
+    return Path.home() / ".codex" / "config.toml"
+
+
+def codex_auth_path() -> Path:
+    return Path.home() / ".codex" / "auth.json"
+
+
+def claude_oauth_available() -> bool:
+    token = read_claude_oauth_token()
+    return bool(token)
+
+
+def read_claude_oauth_token() -> str | None:
+    path = claude_credentials_path()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    oauth = data.get("claudeAiOauth")
+    if not isinstance(oauth, dict):
+        return None
+    token = oauth.get("accessToken")
+    if not isinstance(token, str) or not token.strip():
+        return None
+    return token.strip()
+
+
+def read_codex_access_token() -> str | None:
+    path = codex_auth_path()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+    tokens = data.get("tokens")
+    if not isinstance(tokens, dict):
+        return None
+    token = tokens.get("access_token")
+    if not isinstance(token, str) or not token.strip():
+        return None
+    return token.strip()
+
+
+def _resolve_matrx_route_key(
+    state: dict,
+    env: dict[str, str],
+) -> tuple[str, str]:
+    env_key = (env.get("MTRX_KEY") or "").strip()
+    if env_key:
+        return env_key, "env_matrx_key"
+
+    binding = get_workspace_binding(state, cwd=_workspace_cwd(env))
+    binding_key = ((binding or {}).get("matrx_key") or "").strip()
+    if binding_key:
+        return binding_key, "workspace_matrx_key"
+
+    saved_key = (state.get("auth", {}).get("matrx", {}).get("key") or "").strip()
+    if saved_key:
+        return saved_key, "saved_matrx_key"
+
+    return "", "missing_matrx_key"
+
+
+def _workspace_cwd(env: dict[str, str]) -> str:
+    return (env.get("PWD") or os.getcwd()).strip()
+
+
+def _resolve_matrx_context_overrides(
+    state: dict,
+    env: dict[str, str],
+) -> tuple[str, str]:
+    binding = get_workspace_binding(state, cwd=_workspace_cwd(env)) or {}
+    group_id = (env.get("MTRX_GROUP_ID") or binding.get("group_id") or "").strip()
+    project_id = (env.get("MTRX_PROJECT_ID") or binding.get("project_id") or "").strip()
+    return group_id, project_id
+
+
+def _persist_workspace_binding_from_env(state: dict, env: dict[str, str]) -> bool:
+    env_key = (env.get("MTRX_KEY") or "").strip()
+    env_project = (env.get("MTRX_PROJECT_ID") or "").strip()
+    env_group = (env.get("MTRX_GROUP_ID") or "").strip()
+    saved_personal_key = (state.get("auth", {}).get("matrx", {}).get("key") or "").strip()
+
+    if not any((env_key, env_project, env_group)):
+        return False
+
+    if env_key and env_key == saved_personal_key and not env_project and not env_group:
+        return False
+
+    return set_workspace_binding(
+        state,
+        cwd=_workspace_cwd(env),
+        matrx_key=env_key if "MTRX_KEY" in env else None,
+        project_id=env_project if "MTRX_PROJECT_ID" in env else None,
+        group_id=env_group if "MTRX_GROUP_ID" in env else None,
+    )
+
+def _build_codex_env(
+    state: dict,
+    route: str,
+    env: dict[str, str],
+    passthrough_args: list[str],
+) -> tuple[dict[str, str], str, list[str]]:
+    matrx = state["auth"]["matrx"]
+    openai = state["auth"]["openai"]
+    proxy_base = ensure_v1_url(matrx.get("base_url"))
+    mx_key, matrx_auth_source = _resolve_matrx_route_key(state, env)
+    direct_key = (openai.get("key") or "").strip()
+
+    if route == "matrx":
+        if not mx_key:
+            raise ValueError("No Matrx key available. Run: mtrx login matrx --key mx_... or set MTRX_KEY")
+        access_token = read_codex_access_token()
+        if not access_token:
+            raise ValueError("Codex login required. Run: codex login")
+        for key in MATRX_ENV_KEYS:
+            env.pop(key, None)
+        env_snap = _capture_env_snapshot()
+        env_b64 = base64.b64encode(json.dumps(env_snap).encode()).decode() if env_snap else ""
+        session_id = str(uuid.uuid4())
+        group_id, project_id = _resolve_matrx_context_overrides(state, env)
+        header_parts = [
+            f'"Authorization" = "Bearer {access_token}"',
+            f'"X-Matrx-Key" = "{mx_key}"',
+            '"X-Matrx-Agent-Id" = "codex-cli"',
+            '"X-Matrx-Provider" = "codex"',
+            f'"X-Matrx-Session-Id" = "{session_id}"',
+        ]
+        if group_id:
+            header_parts.append(f'"X-Matrx-Group" = "{group_id}"')
+        if project_id:
+            header_parts.append(f'"X-Matrx-Project-Id" = "{project_id}"')
+        if env_b64:
+            header_parts.append(f'"X-Matrx-Env" = "{env_b64}"')
+        headers_str = ", ".join(header_parts)
+        return env, matrx_auth_source, [
+            "-c",
+            "model_provider=matrx",
+            "-c",
+            'model_providers.matrx.name="Matrx Proxy"',
+            "-c",
+            f'model_providers.matrx.base_url="{proxy_base}"',
+            "-c",
+            'model_providers.matrx.wire_api="responses"',
+            "-c",
+            f'model_providers.matrx.http_headers={{ {headers_str} }}',
+            *passthrough_args,
+        ]
+
+    _clear_if_matches(env, "OPENAI_BASE_URL", proxy_base)
+    _clear_if_matches(env, "OPENAI_API_BASE", proxy_base)
+    _clear_if_matches(env, "OPENAI_API_KEY", mx_key)
+    env.pop("MTRX_KEY", None)
+    if env.get("OPENAI_API_KEY"):
+        return env, "existing_openai_env", passthrough_args
+    if direct_key:
+        env["OPENAI_API_KEY"] = direct_key
+        return env, "saved_openai_key", passthrough_args
+    return env, "existing_codex_auth", passthrough_args
+
+
+def _build_claude_env(
+    state: dict,
+    route: str,
+    env: dict[str, str],
+) -> tuple[dict[str, str], str]:
+    matrx = state["auth"]["matrx"]
+    anthropic = state["auth"]["anthropic"]
+    # Claude Code gateway uses the root URL, not a /v1-suffixed base.
+    proxy_base = ensure_root_url(matrx.get("base_url"))
+    mx_key, matrx_auth_source = _resolve_matrx_route_key(state, env)
+    direct_key = (anthropic.get("key") or "").strip()
+
+    if route == "matrx":
+        if not mx_key:
+            raise ValueError("No Matrx key available. Run: mtrx login matrx --key mx_... or set MTRX_KEY")
+        env.pop("MTRX_KEY", None)
+        env["MATRX_BASE_URL"] = proxy_base
+        env["MATRX_API_KEY"] = mx_key
+        # Claude Code gateway uses root URL, not /v1
+        env["ANTHROPIC_BASE_URL"] = proxy_base
+        group_id, project_id = _resolve_matrx_context_overrides(state, env)
+        session_id = str(uuid.uuid4())
+        # Evolutionary scaffolding: env snapshot for AI context injection
+        env_snap = _capture_env_snapshot()
+        env_b64 = base64.b64encode(json.dumps(env_snap).encode()).decode() if env_snap else ""
+        custom_headers = "\n".join(
+            [
+                f"x-matrx-key: {mx_key}",
+                "x-matrx-agent-id: claude-cli",
+                "x-matrx-provider: claude_code",
+                f"x-matrx-session-id: {session_id}",
+            ]
+        )
+        if group_id:
+            custom_headers += f"\nx-matrx-group: {group_id}"
+        if project_id:
+            custom_headers += f"\nx-matrx-project-id: {project_id}"
+        if env_b64:
+            custom_headers += f"\nx-matrx-env: {env_b64}"
+        # Always send the matrx key via ANTHROPIC_CUSTOM_HEADERS so it arrives on
+        # the dedicated X-Matrx-Key header. This keeps the Authorization slot free
+        # for the real Anthropic credential (OAuth token or API key) so the proxy can
+        # forward it to Anthropic without confusing the matrx key with a provider key.
+        env["ANTHROPIC_CUSTOM_HEADERS"] = custom_headers
+        env.pop("ANTHROPIC_AUTH_TOKEN", None)
+        if _claude_uses_oauth(state):
+            # OAuth token flows through natively via Authorization: Bearer sk-ant-oat01-*
+            env.pop("ANTHROPIC_API_KEY", None)
+        else:
+            # Non-OAuth: if a saved Anthropic API key is available, set it so the SDK
+            # sends x-api-key to the proxy and the proxy can forward it upstream.
+            # If no key is saved, the proxy will fall back to the org vault.
+            if direct_key:
+                env["ANTHROPIC_API_KEY"] = direct_key
+            else:
+                env.pop("ANTHROPIC_API_KEY", None)
+        return env, matrx_auth_source
+
+    # Direct route: clear any matrx-managed env vars
+    env.pop("MTRX_KEY", None)
+    _clear_if_matches(env, "ANTHROPIC_BASE_URL", proxy_base)
+    _clear_if_matches(env, "ANTHROPIC_API_KEY", mx_key)
+    _clear_if_matches(env, "ANTHROPIC_AUTH_TOKEN", mx_key)
+    custom_headers = env.get("ANTHROPIC_CUSTOM_HEADERS", "")
+    if mx_key and mx_key in custom_headers:
+        env.pop("ANTHROPIC_CUSTOM_HEADERS", None)
+    if claude_oauth_available():
+        return env, "local_claude_oauth"
+    if env.get("ANTHROPIC_API_KEY"):
+        return env, "existing_anthropic_env"
+    if direct_key:
+        env["ANTHROPIC_API_KEY"] = direct_key
+        return env, "saved_anthropic_key"
+    imported = (state["auth"]["claude_code"].get("oauth_token") or "").strip()
+    if imported:
+        return env, "imported_claude_oauth"
+    return env, "existing_claude_auth"
+
+
+def _validate_claude_launch_plan(plan: LaunchPlan, state: dict) -> None:
+    """Validate Claude launch plan before spawning."""
+    if plan.route != "matrx":
+        return
+
+    base_url = (plan.env.get("ANTHROPIC_BASE_URL") or "").strip()
+    if not base_url:
+        raise ValueError("Claude Matrx route is missing ANTHROPIC_BASE_URL")
+    if base_url.endswith("/v1"):
+        raise ValueError(
+            "Claude Matrx route must use the gateway root base URL, not a /v1 URL. "
+            f"Got: {base_url}"
+        )
+
+    mx_key = (plan.env.get("MATRX_API_KEY") or "").strip()
+    if not mx_key.startswith("mx_"):
+        raise ValueError("Claude Matrx route is missing a valid MATRX_API_KEY")
+
+    # All routes use ANTHROPIC_CUSTOM_HEADERS for matrx key delivery so that
+    # the Authorization slot remains free for the real Anthropic credential.
+    custom_headers = (plan.env.get("ANTHROPIC_CUSTOM_HEADERS") or "").strip()
+    if not custom_headers or mx_key not in custom_headers:
+        raise ValueError("Claude Matrx route is missing ANTHROPIC_CUSTOM_HEADERS with the Matrx key")
+    lowered_headers = custom_headers.lower()
+    if "x-matrx-session-id:" not in lowered_headers:
+        raise ValueError("Claude Matrx route is missing ANTHROPIC_CUSTOM_HEADERS with X-Matrx-Session-Id")
+    if "x-matrx-provider: claude_code" not in lowered_headers:
+        raise ValueError("Claude Matrx route is missing ANTHROPIC_CUSTOM_HEADERS with X-Matrx-Provider=claude_code")
+
+    if plan.env.get("ANTHROPIC_AUTH_TOKEN"):
+        raise ValueError("Claude Matrx route should not set ANTHROPIC_AUTH_TOKEN")
+
+    if _claude_uses_oauth(state):
+        oauth_token = read_claude_oauth_token() or (state.get("auth", {}).get("claude_code", {}).get("oauth_token") or "").strip()
+        if not oauth_token:
+            raise ValueError("Claude OAuth was selected but no Claude OAuth token is available. Run: mtrx login claude-code --import")
+        if plan.env.get("ANTHROPIC_API_KEY"):
+            raise ValueError("Claude Matrx OAuth route should not set ANTHROPIC_API_KEY")
+
+
+def _validate_codex_launch_plan(plan: LaunchPlan, state: dict) -> None:
+    if plan.route != "matrx":
+        return
+
+    expected_base_url = ensure_v1_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+    required_args = {
+        "model_provider=matrx",
+        'model_providers.matrx.name="Matrx Proxy"',
+        f'model_providers.matrx.base_url="{expected_base_url}"',
+        'model_providers.matrx.wire_api="responses"',
+    }
+    actual_args = set(plan.args)
+    if any(arg not in actual_args for arg in required_args):
+        raise ValueError("Codex Matrx route is missing required launch overrides")
+    http_headers_arg = next(
+        (arg for arg in plan.args if arg.startswith('model_providers.matrx.http_headers=')),
+        None,
+    )
+    if not http_headers_arg or '"Authorization" = "Bearer ' not in http_headers_arg:
+        raise ValueError("Codex Matrx route is missing launch-time Authorization bearer forwarding")
+    key_match = re.search(r'"X-Matrx-Key"\s*=\s*"([^"]+)"', http_headers_arg)
+    if key_match is None or not key_match.group(1).startswith("mx_"):
+        raise ValueError("Codex Matrx route is missing launch-time X-Matrx-Key forwarding")
+    if '"X-Matrx-Provider" = "codex"' not in http_headers_arg:
+        raise ValueError("Codex Matrx route is missing launch-time X-Matrx-Provider=codex")
+    if '"X-Matrx-Session-Id"' not in http_headers_arg:
+        raise ValueError("Codex Matrx route is missing launch-time X-Matrx-Session-Id")
+
+
+def describe_launch_plan(plan: LaunchPlan, state: dict) -> list[str]:
+    if plan.route != "matrx":
+        return []
+
+    if plan.tool == "codex":
+        base_url = ensure_v1_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+        return [
+            "Launching codex via Matrx",
+            f"  config: {codex_config_path()}",
+            f"  base_url: {base_url}",
+            f"  auth_source: {plan.auth_source}",
+            f"  codex_auth_path: {codex_auth_path()}",
+            f"  codex_access_token_present: {bool(read_codex_access_token())}",
+            "  runtime_route: forced launch overrides",
+            "  persistent_route: disabled",
+        ]
+
+    if plan.tool == "claude":
+        base_url = ensure_root_url(state.get("auth", {}).get("matrx", {}).get("base_url"))
+        custom_headers = (plan.env.get("ANTHROPIC_CUSTOM_HEADERS") or "").strip()
+        api_key_present = bool((plan.env.get("ANTHROPIC_API_KEY") or "").strip())
+        return [
+            "Launching claude via Matrx",
+            f"  base_url: {base_url or DEFAULT_MATRX_BASE_URL}",
+            f"  auth_source: {plan.auth_source}",
+            f"  oauth_mode: {_claude_uses_oauth(state)}",
+            f"  custom_headers_present: {bool(custom_headers)}",
+            f"  api_key_present: {api_key_present}",
+        ]
+
+    return []
+
+
+def get_tool_config_status(state: dict, tool: str) -> dict[str, str | bool | None]:
+    status = (
+        state.setdefault("setup", {})
+        .setdefault("tool_config", {})
+        .setdefault(
+            tool,
+            {
+                "configured": False,
+                "verified": False,
+                "config_path": None,
+                "backup_path": None,
+                "original_backup_path": None,
+                "config_fingerprint": None,
+                "matrx_key_fingerprint": None,
+                "last_verified_at": None,
+                "previous_model_provider": None,
+                "previous_matrx_block": None,
+                "previous_values": {},
+            },
+        )
+    )
+    return {
+        "configured": bool(status.get("configured")),
+        "verified": bool(status.get("verified")),
+        "config_path": status.get("config_path"),
+        "backup_path": status.get("backup_path"),
+        "last_verified_at": status.get("last_verified_at"),
+    }
+
+
+def _ensure_matrx_auth(state: dict, *, env: dict[str, str] | None = None) -> bool:
+    key, _ = _resolve_matrx_route_key(state, dict(env or os.environ))
+    if not key:
+        raise ValueError("Login required. Run: mtrx login matrx --key mx_... or set MTRX_KEY")
+    if not key.startswith("mx_"):
+        raise ValueError("Matrx key is invalid. Run: mtrx login matrx --key mx_... or set MTRX_KEY")
+    return False
+
+
+def _fingerprint_secret(secret: str) -> str:
+    return hashlib.sha256(secret.encode()).hexdigest()
+
+
+def _clear_if_matches(env: dict[str, str], key: str, expected: str) -> None:
+    if expected and env.get(key) == expected:
+        env.pop(key, None)
+
+
+def _claude_uses_oauth(state: dict) -> bool:
+    if read_claude_oauth_token():
+        return True
+    imported = (state.get("auth", {}).get("claude_code", {}).get("oauth_token") or "").strip()
+    return bool(imported)
+
+
+def _sync_tool_route_config(state: dict, *, tool: str, route: str) -> bool:
+    if tool == "claude":
+        return _cleanup_claude_managed_config(state)
+    if tool == "codex":
+        return _sync_codex_route_config(state, route=route)
+    return False
+
+
+def _tool_config_entry(state: dict, tool: str) -> dict:
+    return (
+        state.setdefault("setup", {})
+        .setdefault("tool_config", {})
+        .setdefault(
+            tool,
+            {
+                "configured": False,
+                "verified": False,
+                "config_path": None,
+                "backup_path": None,
+                "original_backup_path": None,
+                "config_fingerprint": None,
+                "matrx_key_fingerprint": None,
+                "last_verified_at": None,
+                "previous_model_provider": None,
+                "previous_matrx_block": None,
+                "previous_values": {},
+            },
+        )
+    )
+
+
+def _read_json_file(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Failed to parse {path}") from exc
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected {path} to contain a JSON object")
+    return data
+
+
+def _write_json_file(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _cleanup_claude_managed_config(state: dict) -> bool:
+    path = claude_settings_path()
+    entry = _tool_config_entry(state, "claude")
+    entry["config_path"] = str(path)
+
+    if not path.exists():
+        entry["configured"] = False
+        entry["verified"] = True
+        entry["config_fingerprint"] = None
+        entry["matrx_key_fingerprint"] = None
+        entry["last_verified_at"] = dt.datetime.now(dt.timezone.utc).isoformat()
+        return False
+
+    data = _read_json_file(path)
+    env = data.get("env")
+    if env is None:
+        entry["configured"] = False
+        entry["verified"] = True
+        entry["config_fingerprint"] = _fingerprint_secret(json.dumps(data, sort_keys=True))
+        entry["matrx_key_fingerprint"] = None
+        entry["last_verified_at"] = dt.datetime.now(dt.timezone.utc).isoformat()
+        return False
+    if not isinstance(env, dict):
+        raise ValueError(f"Expected {path} env to be a JSON object")
+
+    previous = entry.setdefault("previous_values", {})
+    changed = False
+
+    for key in ("ANTHROPIC_BASE_URL", "ANTHROPIC_CUSTOM_HEADERS", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"):
+        prior = previous.get(key, None)
+        if prior is None:
+            if key in env:
+                env.pop(key, None)
+                changed = True
+        elif env.get(key) != prior:
+            env[key] = prior
+            changed = True
+
+    if not env:
+        data.pop("env", None)
+
+    entry["configured"] = False
+    entry["verified"] = True
+    entry["config_fingerprint"] = _fingerprint_secret(json.dumps(data, sort_keys=True))
+    entry["matrx_key_fingerprint"] = None
+    entry["last_verified_at"] = dt.datetime.now(dt.timezone.utc).isoformat()
+
+    if changed:
+        _write_json_file(path, data)
+    return changed
+
+
+def _sync_codex_route_config(state: dict, *, route: str) -> bool:
+    path = codex_config_path()
+    entry = _tool_config_entry(state, "codex")
+    prior_entry = dict(entry)
+    entry["config_path"] = str(path)
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    managed_block, content = _strip_codex_managed_block(text)
+    new_text = text
+
+    if managed_block is not None:
+        new_text = _restore_codex_config_text(entry, content)
+
+    changed = _normalize_toml_text(new_text) != _normalize_toml_text(text)
+
+    entry["configured"] = False
+    entry["verified"] = True
+    normalized_text = _normalize_toml_text(new_text)
+    entry["config_fingerprint"] = _fingerprint_secret(normalized_text) if normalized_text else None
+    entry["matrx_key_fingerprint"] = None
+    entry["last_verified_at"] = dt.datetime.now(dt.timezone.utc).isoformat()
+    entry["previous_model_provider"] = None
+    entry["previous_matrx_block"] = None
+
+    if changed:
+        _write_or_remove_codex_config(path, new_text)
+
+    return changed or entry != prior_entry
+
+
+def _strip_codex_managed_block(text: str) -> tuple[str | None, str]:
+    pattern = rf"(?ms)^\s*{re.escape(MTRX_CODEX_BLOCK_START)}\r?\n.*?^\s*{re.escape(MTRX_CODEX_BLOCK_END)}\s*$\r?\n?"
+    match = re.search(pattern, text)
+    if not match:
+        return None, text.strip()
+    without_managed = text[:match.start()] + text[match.end():]
+    return match.group(0).strip(), without_managed.strip()
+
+
+def _restore_codex_config_text(entry: dict, content: str) -> str:
+    original_backup_path = (entry.get("original_backup_path") or "").strip()
+    if original_backup_path:
+        backup_path = Path(original_backup_path)
+        if backup_path.exists():
+            return backup_path.read_text(encoding="utf-8")
+
+    restored = content.rstrip()
+    prior_model_provider = (entry.get("previous_model_provider") or "").strip()
+    prior_matrx_block = (entry.get("previous_matrx_block") or "").strip()
+
+    if prior_model_provider and not re.search(r"(?m)^model_provider\s*=", restored):
+        restored = _append_toml_block(restored, prior_model_provider)
+    if prior_matrx_block and "[model_providers.matrx]" not in restored:
+        restored = _append_toml_block(restored, prior_matrx_block)
+
+    return restored
+
+
+def _write_or_remove_codex_config(path: Path, text: str) -> None:
+    normalized = _normalize_toml_text(text)
+    if normalized:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(normalized, encoding="utf-8")
+        _verify_codex_config_file(path)
+        return
+    if path.exists():
+        path.unlink()
+
+
+def _append_toml_block(content: str, block: str) -> str:
+    base = content.rstrip()
+    addition = block.strip()
+    if not addition:
+        return base
+    if not base:
+        return addition
+    return f"{base}\n\n{addition}"
+
+
+def _normalize_toml_text(text: str) -> str:
+    cleaned = text.strip()
+    if not cleaned:
+        return ""
+    return cleaned + "\n"
+
+
+def _verify_codex_config_file(path: Path) -> None:
+    if tomllib is None:
+        return
+    text = path.read_text(encoding="utf-8")
+    try:
+        tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ValueError(f"Failed to parse Codex config at {path}") from exc