nexo-brain 7.9.27 → 7.9.28

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.27",
+  "version": "7.9.28",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,7 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.9.27` is the current packaged-runtime line. Patch release over `7.9.26`: server startup no longer hangs the MCP `initialize` handshake when legacy followups/reminders still need owner backfill — the synchronous startup migration now runs `--rules-only` and skips the multi-minute `LocalZeroShotClassifier` load, keeping handshake under a few seconds.
+Version `7.9.28` is the current packaged-runtime line. Patch release over `7.9.27`: optional override files at `~/.nexo/config/llm_endpoint.json` and `~/.nexo/config/auth_provider.json` let third-party orchestrators redirect Brain's Anthropic SDK calls and delegate bearer token resolution to a local command (analogous to git's `credential.helper`). The same redirection is propagated to every CLI child Brain spawns (deep-sleep, evolution, followup-runner, morning-agent, email-monitor, `nexo chat`) by injecting `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` into the spawned environment, so headless crons reach the proxy too. An `Idempotency-Key` (UUID4 hex) is attached per request for proxy-side dedup of transparent retries within 24h. Brain libre standalone (no override files) hits `api.anthropic.com` directly with `ANTHROPIC_API_KEY` exactly as before.
+
+Previously in `7.9.27`: server startup no longer hangs the MCP `initialize` handshake when legacy followups/reminders still need owner backfill — the synchronous startup migration now runs `--rules-only` and skips the multi-minute `LocalZeroShotClassifier` load, keeping handshake under a few seconds.
 
 Previously in `7.9.26`: headless automation prompts now receive the operator-language contract centrally, so reports, diaries, syntheses, followups, escalations, and Deep Sleep-generated memory text follow calibration even when the underlying template is English.
 
@@ -1077,6 +1079,19 @@ Use a personal plugin only when you need a new MCP tool in the runtime surface.
 - **Auto-update is resilient.** NEXO checks for updates on startup. If an update fails, it continues with the current version and notifies you. Local migrations (database schema, configuration) always run. Network updates (git pull) can be disabled by setting `auto_update: false` in `NEXO_HOME/config/schedule.json`.
 - **Secret redaction.** API keys and tokens are stripped before they ever reach memory storage.
 
+## Custom LLM endpoint (advanced)
+
+NEXO Brain reads two optional override files at `~/.nexo/config/`:
+
+- `llm_endpoint.json` — set a custom Anthropic-compatible base URL.
+- `auth_provider.json` — delegate bearer token resolution to a local command (analogous to git's `credential.helper`).
+
+This lets third-party orchestrators — for example an Anthropic-compatible proxy that adds rate limiting, cost accounting, multi-provider failover, or per-team auth — route Brain's LLM calls without modifying its source.
+
+**If neither file exists, Brain operates exactly as before:** direct call to `https://api.anthropic.com` using `ANTHROPIC_API_KEY` from environment or filesystem. The override path is opt-in.
+
+When override mode is active, Brain attaches an opaque `Idempotency-Key` to every request so the proxy can dedup transparent retries (24h window) without double-billing. The same redirection applies to every CLI child Brain spawns (deep-sleep, evolution, followup-runner, morning-agent, email-monitor, `nexo chat`): `agent_runner.py` injects `ANTHROPIC_BASE_URL` and `ANTHROPIC_API_KEY` into the spawned environment when override mode is on, so headless crons hit the proxy too — LaunchAgent crons do not inherit env from a UI process. See `docs/api/override-files.md` for the full schema, fallback rules, and an end-to-end example.
+
 ## The Psychology Behind NEXO Brain
 
 NEXO Brain isn't just engineering — it's applied cognitive psychology:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.27",
+  "version": "7.9.28",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/agent_runner.py

@@ -374,6 +374,47 @@ def _codex_config_path() -> Path:
     return Path.home() / ".codex" / "config.toml"
 
 
+def _apply_llm_endpoint_override(env: dict) -> dict:
+    """Redirect the child Anthropic-compatible CLI to the configured proxy
+    when Brain is in override mode (``~/.nexo/config/llm_endpoint.json``
+    present). Standalone runs leave ``env`` untouched, so Brain libre keeps
+    hitting ``api.anthropic.com`` directly with whatever ``ANTHROPIC_API_KEY``
+    the operator already had configured.
+
+    The contract is symmetric with what ``call_model_raw.py`` does for SDK
+    direct calls: same files, same precedence, same alias system. The CLI
+    child reads ``ANTHROPIC_BASE_URL`` (Anthropic SDK convention) and
+    ``ANTHROPIC_API_KEY`` from the spawned environment.
+
+    No-op (and silent) when ``call_model_raw`` is unavailable for any
+    reason; the headless surface should never block on this helper.
+    """
+    try:
+        from call_model_raw import (
+            is_override_mode,
+            resolve_api_base_url,
+            resolve_auth_token,
+        )
+    except Exception:
+        return env
+    try:
+        if not is_override_mode():
+            return env
+        base_url = resolve_api_base_url()
+        if base_url:
+            env["ANTHROPIC_BASE_URL"] = base_url
+        bearer = resolve_auth_token()
+        if bearer:
+            env["ANTHROPIC_API_KEY"] = bearer
+    except Exception:
+        # Override is best-effort: a misconfigured override file must not
+        # crash an automation run that would otherwise have worked in
+        # standalone. The SDK direct path already surfaces config errors
+        # via ClassifierUnavailableError; the CLI path stays defensive.
+        pass
+    return env
+
+
 def _headless_env(env: dict | None = None) -> dict:
     merged = os.environ.copy()
     if env:
@@ -382,7 +423,7 @@ def _headless_env(env: dict | None = None) -> dict:
     merged["NEXO_AUTOMATION"] = "1"
     merged.pop("CLAUDECODE", None)
     merged.pop("CLAUDE_CODE", None)
-    return merged
+    return _apply_llm_endpoint_override(merged)
 
 
 def _load_client_bootstrap_prompt(client: str) -> str:
@@ -603,6 +644,7 @@ def run_automation_interactive(
     launch_env = os.environ.copy()
     if env:
         launch_env.update(env)
+    launch_env = _apply_llm_endpoint_override(launch_env)
     cwd_path = Path(_interactive_target_cwd(target))
 
     # Best-effort resonance lookup — interactive sessions do not swap the
@@ -1043,7 +1085,21 @@ def run_automation_prompt(
 
         bare_api_key = ""
         if resolved_bare:
-            bare_api_key = _resolve_anthropic_api_key()
+            # In override mode the bearer was already injected into
+            # run_env by _apply_llm_endpoint_override (proxy token, not
+            # the operator's raw Anthropic key). Reuse it instead of
+            # asking the keychain helper for a real Anthropic key — the
+            # proxy expects its own bearer and would reject the real one.
+            override_bearer = run_env.get("ANTHROPIC_API_KEY", "").strip() if run_env else ""
+            try:
+                from call_model_raw import is_override_mode as _is_override_mode
+                _override_active = _is_override_mode()
+            except Exception:
+                _override_active = False
+            if _override_active and override_bearer:
+                bare_api_key = override_bearer
+            else:
+                bare_api_key = _resolve_anthropic_api_key()
             if not bare_api_key:
                 # Silent fallback: we would rather take the slower path
                 # than force the caller to fail-closed on an env quirk.

package/src/call_model_raw.py

@@ -41,7 +41,11 @@ gap.
 from __future__ import annotations
 
 import json
+import logging
 import os
+import subprocess
+import sys
+import uuid
 from pathlib import Path
 
 
@@ -65,6 +69,203 @@ _OPENAI_KEY_PATHS = (
     Path.home() / ".codex" / "auth.json",
 )
 
+# ---------------------------------------------------------------------------
+# Optional override files (~/.nexo/config/)
+# ---------------------------------------------------------------------------
+# Two forward-compatible JSON files let third-party orchestrators (such as an
+# Anthropic-compatible proxy) redirect the LLM endpoint and delegate token
+# resolution to a local helper. Pattern is analogous to git's `core.editor`
+# and `credential.helper`.
+#
+#   ~/.nexo/config/llm_endpoint.json
+#       {
+#         "version": 1,
+#         "anthropic_base_url": "https://my-proxy.example.com/api/proxy"
+#       }
+#
+#   ~/.nexo/config/auth_provider.json
+#       {
+#         "version": 1,
+#         "command": "/path/to/auth-helper",
+#         "args": ["--for", "anthropic"],
+#         "timeout_sec": 5
+#       }
+#
+# If neither file exists the caller falls back to standalone behaviour:
+# direct call to api.anthropic.com using ANTHROPIC_API_KEY from environment
+# or filesystem. NEXO Brain's open-source distribution is unaffected.
+
+def _resolve_brain_config_dir() -> Path:
+    """Honour ``NEXO_HOME`` so tests, devcontainers and non-default
+    installs (Maria iMac, Codex sandboxes, etc.) hit the right
+    ``config/`` directory. Falls back to ``~/.nexo/config/``."""
+    nexo_home = os.environ.get("NEXO_HOME", "").strip()
+    if nexo_home:
+        return Path(nexo_home).expanduser() / "config"
+    return Path.home() / ".nexo" / "config"
+
+
+_BRAIN_CONFIG_DIR = _resolve_brain_config_dir()
+_SUPPORTED_OVERRIDE_VERSION = 1
+_LLM_ENDPOINT_FILENAME = "llm_endpoint.json"
+_AUTH_PROVIDER_FILENAME = "auth_provider.json"
+_DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com"
+_DEFAULT_AUTH_PROVIDER_TIMEOUT = 5
+
+# Internal map: (concrete_model, effort) -> wire alias accepted by an
+# Anthropic-compatible proxy. ONLY consulted when override mode is active.
+# Standalone mode never reads this map and keeps using the concrete model.
+#
+# Add entries here in lockstep with new tiers added to resonance_tiers.json.
+# Failing fast on an unmapped (model, effort) is preferable to letting the
+# proxy reject the request with a 400 — the operator gets a clear local
+# error instead of a remote one.
+_CONCRETE_TO_ALIAS: dict[tuple[str, str], str] = {
+    ("claude-opus-4-7[1m]", "max"):    "nexo-max",
+    ("claude-opus-4-7[1m]", "xhigh"):  "nexo-high",
+    ("claude-opus-4-7[1m]", "high"):   "nexo-medium",
+    ("claude-opus-4-7[1m]", "medium"): "nexo-low",
+    ("claude-haiku-4-5-20251001", ""): "nexo-mini",
+}
+
+
+def _read_versioned_config(filename: str) -> dict | None:
+    """Load a versioned override file from the Brain config directory.
+
+    The directory is resolved at call time (not module import time) so
+    tests can monkeypatch ``_BRAIN_CONFIG_DIR`` and so a process that
+    sets ``NEXO_HOME`` after importing the module still picks up the
+    right path on the first real call.
+
+    Returns the dict iff the file exists, parses as JSON and declares
+    ``version: 1``. Any other case (missing, malformed, unsupported version)
+    returns None and emits a stderr warning so operators can see why the
+    override was ignored. Never raises.
+    """
+    path = _BRAIN_CONFIG_DIR / filename
+    try:
+        if not path.is_file():
+            return None
+        cfg = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        sys.stderr.write(
+            f"[brain] failed to read override {filename}: {exc}; ignoring\n"
+        )
+        return None
+    if not isinstance(cfg, dict):
+        sys.stderr.write(
+            f"[brain] override {filename} is not a JSON object; ignoring\n"
+        )
+        return None
+    version = cfg.get("version", 0)
+    if version != _SUPPORTED_OVERRIDE_VERSION:
+        sys.stderr.write(
+            f"[brain] override {filename} version {version!r} not supported "
+            f"(expected {_SUPPORTED_OVERRIDE_VERSION}); ignoring\n"
+        )
+        return None
+    return cfg
+
+
+def resolve_api_base_url() -> str:
+    """Return the Anthropic API base URL.
+
+    Resolution order:
+        1) ``~/.nexo/config/llm_endpoint.json`` with ``anthropic_base_url``.
+        2) ``NEXO_LLM_ENDPOINT`` env var.
+        3) Default ``https://api.anthropic.com`` (standalone).
+    """
+    cfg = _read_versioned_config(_LLM_ENDPOINT_FILENAME)
+    if cfg:
+        url = str(cfg.get("anthropic_base_url", "") or "").strip()
+        if url:
+            return url
+    env_url = os.environ.get("NEXO_LLM_ENDPOINT", "").strip()
+    if env_url:
+        return env_url
+    return _DEFAULT_ANTHROPIC_BASE_URL
+
+
+def _override_force_disabled() -> bool:
+    # Internal escape hatch used by the test suite and by maintainers when
+    # they need to validate a regression against the upstream Anthropic API
+    # without renaming the override files on disk. Intentionally undocumented
+    # outside the source so that the canonical override-mode contract stays
+    # purely file-driven for everybody else.
+    raw = os.environ.get("NEXO_RAW_ANTHROPIC", "").strip().lower()
+    return raw in ("1", "true", "yes", "on")
+
+
+def is_override_mode() -> bool:
+    """True iff a valid ``llm_endpoint.json`` is present and selects a custom
+    base URL. The override gate is the file (not an env var) so that
+    env-only configurations remain transparent to standalone callers."""
+    if _override_force_disabled():
+        return False
+    cfg = _read_versioned_config(_LLM_ENDPOINT_FILENAME)
+    if not cfg:
+        return False
+    url = str(cfg.get("anthropic_base_url", "") or "").strip()
+    return bool(url)
+
+
+def resolve_auth_token() -> str:
+    """Return the bearer token to use against the resolved base URL.
+
+    Resolution order:
+        1) ``~/.nexo/config/auth_provider.json`` ``command`` (subprocess
+           stdout, trimmed). Honours ``timeout_sec`` (default 5). Falls
+           through to (2) on any failure.
+        2) ``ANTHROPIC_API_KEY`` env var.
+        3) Legacy filesystem fallbacks (``_ANTHROPIC_KEY_PATHS``).
+
+    Returns an empty string if nothing resolves; the caller raises
+    ``ClassifierUnavailableError`` so the failure surfaces explicitly.
+    """
+    cfg = _read_versioned_config(_AUTH_PROVIDER_FILENAME)
+    if cfg:
+        cmd = str(cfg.get("command", "") or "").strip()
+        if cmd:
+            args_raw = cfg.get("args", []) or []
+            args = [str(a) for a in args_raw if isinstance(a, (str, int, float))]
+            try:
+                timeout_sec = int(cfg.get("timeout_sec", _DEFAULT_AUTH_PROVIDER_TIMEOUT))
+            except (TypeError, ValueError):
+                timeout_sec = _DEFAULT_AUTH_PROVIDER_TIMEOUT
+            try:
+                result = subprocess.run(
+                    [cmd, *args],
+                    capture_output=True,
+                    text=True,
+                    timeout=timeout_sec,
+                    check=False,
+                )
+            except subprocess.TimeoutExpired as exc:
+                # Learning #294: subprocess timeouts must be captured
+                # explicitly so the operator sees the helper hung instead
+                # of a generic "auth missing" downstream.
+                sys.stderr.write(
+                    f"[brain] auth_provider command timed out after {timeout_sec}s: "
+                    f"{exc}; falling back to env\n"
+                )
+            except (FileNotFoundError, PermissionError, OSError) as exc:
+                sys.stderr.write(
+                    f"[brain] auth_provider command failed: {exc}; falling back to env\n"
+                )
+            else:
+                if result.returncode == 0:
+                    token = (result.stdout or "").strip()
+                    if token:
+                        return token
+                else:
+                    stderr_excerpt = (result.stderr or "").strip()[:200]
+                    sys.stderr.write(
+                        f"[brain] auth_provider command exit={result.returncode}: "
+                        f"{stderr_excerpt}; falling back to env\n"
+                    )
+
+    return _resolve_anthropic_key()
+
 
 def _resolve_anthropic_key() -> str:
     env_key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
@@ -138,11 +339,28 @@ def _extract_openai_text(response) -> str:
         return ""
 
 
+def _resolve_override_alias(model: str, effort: str) -> str:
+    """In override mode the proxy speaks aliases, not concrete model names.
+    Translate ``(model, effort)`` into the wire alias the proxy validates.
+    Unmapped pairs fail-closed: better to surface a local config error than
+    let the proxy reject the request remotely.
+    """
+    key = (model, effort)
+    alias = _CONCRETE_TO_ALIAS.get(key)
+    if not alias:
+        raise ClassifierUnavailableError(
+            f"override mode: no alias mapped for (model={model!r}, "
+            f"effort={effort!r}); update _CONCRETE_TO_ALIAS in call_model_raw.py"
+        )
+    return alias
+
+
 def _call_anthropic_raw(
     *,
     prompt: str,
     system: str | None,
     model: str,
+    effort: str,
     max_tokens: int,
     temperature: float,
     stop_sequences: list[str],
@@ -153,13 +371,34 @@ def _call_anthropic_raw(
     except ImportError as exc:
         raise ClassifierUnavailableError(f"anthropic SDK missing: {exc}") from exc
 
-    api_key = _resolve_anthropic_key()
-    if not api_key:
-        raise ClassifierUnavailableError("anthropic: no ANTHROPIC_API_KEY found")
+    override = is_override_mode()
+    if override:
+        # Proxy mode: resolve bearer via auth_provider + env fallbacks,
+        # redirect base_url, translate concrete model to wire alias, and
+        # attach an Idempotency-Key so the proxy can dedup retries.
+        wire_model = _resolve_override_alias(model, effort)
+        base_url = resolve_api_base_url()
+        api_key = resolve_auth_token()
+        if not api_key:
+            raise ClassifierUnavailableError(
+                "anthropic override: no bearer resolved (auth_provider and env both empty)"
+            )
+        client = anthropic.Anthropic(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+    else:
+        # Standalone: behaviour identical to pre-V11. No override, no alias
+        # translation, no extra headers — direct hit to api.anthropic.com.
+        wire_model = model
+        api_key = _resolve_anthropic_key()
+        if not api_key:
+            raise ClassifierUnavailableError("anthropic: no ANTHROPIC_API_KEY found")
+        client = anthropic.Anthropic(api_key=api_key, timeout=timeout)
 
-    client = anthropic.Anthropic(api_key=api_key, timeout=timeout)
     kwargs: dict = {
-        "model": model,
+        "model": wire_model,
         "max_tokens": max_tokens,
         "temperature": temperature,
         "stop_sequences": stop_sequences,
@@ -168,6 +407,12 @@ def _call_anthropic_raw(
     if system:
         kwargs["system"] = system
 
+    if override:
+        # Idempotency-Key: opaque per-request token reused on transparent
+        # retries. Proxy dedups on (token_id + idempotency_key) for 24h, so
+        # network-level retries do not double-bill the user.
+        kwargs["extra_headers"] = {"Idempotency-Key": uuid.uuid4().hex}
+
     try:
         response = client.messages.create(**kwargs)
     except anthropic.APITimeoutError as exc:
@@ -301,7 +546,7 @@ def call_model_raw(
         raise ClassifierUnavailableError("automation_backend=none")
 
     try:
-        model, _effort = resolve_model_and_effort(
+        model, effort = resolve_model_and_effort(
             caller=caller,
             backend=backend,
             explicit_tier=tier,
@@ -320,6 +565,7 @@ def call_model_raw(
             prompt=prompt,
             system=system,
             model=model,
+            effort=effort,
             max_tokens=max_tokens,
             temperature=temperature,
             stop_sequences=stop_sequences,
@@ -339,4 +585,10 @@ def call_model_raw(
     raise ClassifierUnavailableError(f"unsupported backend: {backend}")
 
 
-__all__ = ["call_model_raw", "ClassifierUnavailableError"]
+__all__ = [
+    "call_model_raw",
+    "ClassifierUnavailableError",
+    "is_override_mode",
+    "resolve_api_base_url",
+    "resolve_auth_token",
+]