nexo-brain 7.9.6 → 7.9.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.6",
+  "version": "7.9.7",
   "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,7 @@
 
 [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.6` is the current packaged-runtime line. Patch release that closes continuity + MCP restart stability for installed users: Brain now persists conversation-scoped continuity snapshots and resume bundles, activates packaged runtimes atomically under `~/.nexo/core/current`, writes a durable `mcp-restart-required` marker on real version changes, and self-drains old MCP processes until the client restarts against the installed runtime. Coordinated Desktop v0.28.7 consumes the same contract so existing `brain-only` and `brain+desktop` installs reroute to the new runtime instead of running mixed old/new MCP code.
+Version `7.9.7` is the current packaged-runtime line. Patch release that hardens the installed-user MCP/update path after live Desktop validation: Brain now normalizes managed runtime configs back to the stable `~/.nexo/core` root instead of leaving clients pinned to versioned snapshots, mirrors Claude Code MCP config into `~/.claude/mcp-cortex.json`, stamps the active MCP client in generated configs, and disables the FastMCP wrapped `output_schema` that was making Claude Code reject plain-text `nexo_*` tool results. Coordinated Desktop v0.28.8 consumes the same contract so archive/reopen/app-quit flows recover cleanly without reviving stale sessions.
 
 Previously in `7.9.5`: patch release that fixes canonical diary confirmation for Desktop: Brain resolves the Desktop/Claude session UUID through NEXO SID aliases before checking `session_diary`, so archive/delete/app-exit can confirm diaries written by `nexo_session_diary_write` under the active `nexo-...` SID. Verification: `pytest tests/test_lifecycle_events.py` (28 passing) plus coordinated Desktop v0.28.6 shutdown/archive/delete/app-exit checks.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.9.6",
+  "version": "7.9.7",
   "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/auto_update.py

@@ -2262,19 +2262,20 @@ def _maybe_backfill_task_owner() -> None:
 
 
 def _f06_legacy_shim_map() -> list[tuple[str, Path]]:
+    core_root = NEXO_HOME / "core"
     return [
-        ("scripts", NEXO_HOME / "core" / "scripts"),
-        ("skills-core", paths.core_skills_dir(allow_legacy_fallback=False)),
-        ("db", paths.core_db_dir(allow_legacy_fallback=False)),
-        ("cognitive", paths.core_cognitive_dir(allow_legacy_fallback=False)),
-        ("doctor", paths.core_doctor_dir(allow_legacy_fallback=False)),
-        ("dashboard", paths.core_dashboard_dir(allow_legacy_fallback=False)),
+        ("scripts", core_root / "scripts"),
+        ("skills-core", core_root / "skills"),
+        ("db", core_root / "db"),
+        ("cognitive", core_root / "cognitive"),
+        ("doctor", core_root / "doctor"),
+        ("dashboard", core_root / "dashboard"),
         ("brain", NEXO_HOME / "personal" / "brain"),
         ("config", NEXO_HOME / "personal" / "config"),
         ("skills", NEXO_HOME / "personal" / "skills"),
-        ("plugins", NEXO_HOME / "core" / "plugins"),
-        ("hooks", NEXO_HOME / "core" / "hooks"),
-        ("rules", NEXO_HOME / "core" / "rules"),
+        ("plugins", core_root / "plugins"),
+        ("hooks", core_root / "hooks"),
+        ("rules", core_root / "rules"),
         ("data", NEXO_HOME / "runtime" / "data"),
         ("logs", NEXO_HOME / "runtime" / "logs"),
         ("operations", NEXO_HOME / "runtime" / "operations"),
@@ -2300,7 +2301,7 @@ def _f06_legacy_file_shim_map() -> list[tuple[str, Path]]:
 def _f06_packaged_code_file_targets() -> list[tuple[str, Path]]:
     names = list(_discover_runtime_root_python_modules(NEXO_HOME))
     names.extend(_discover_runtime_root_python_modules(NEXO_HOME / "core"))
-    for extra in ("requirements.txt", "model_defaults.json"):
+    for extra in ("requirements.txt", "model_defaults.json", "package.json", "version.json"):
         candidate = NEXO_HOME / extra
         canonical_candidate = NEXO_HOME / "core" / extra
         if candidate.exists() or canonical_candidate.exists():
@@ -2422,12 +2423,13 @@ def _promote_packaged_runtime_code_to_core() -> None:
             return resolved
         return path
 
+    core_root = NEXO_HOME / "core"
     dir_targets = [
-        ("db", paths.core_db_dir(allow_legacy_fallback=False)),
-        ("cognitive", paths.core_cognitive_dir(allow_legacy_fallback=False)),
-        ("doctor", paths.core_doctor_dir(allow_legacy_fallback=False)),
-        ("dashboard", paths.core_dashboard_dir(allow_legacy_fallback=False)),
-        ("skills-core", paths.core_skills_dir(allow_legacy_fallback=False)),
+        ("db", core_root / "db"),
+        ("cognitive", core_root / "cognitive"),
+        ("doctor", core_root / "doctor"),
+        ("dashboard", core_root / "dashboard"),
+        ("skills-core", core_root / "skills"),
     ]
 
     for legacy_name, canonical in dir_targets:
@@ -2904,11 +2906,11 @@ def _maybe_migrate_to_f06_layout() -> None:
             ("state", NEXO_HOME / "runtime" / "state"),
             ("backups", NEXO_HOME / "runtime" / "backups"),
             ("memory", NEXO_HOME / "runtime" / "memory"),
-            ("cognitive", paths.core_cognitive_dir(allow_legacy_fallback=False)),
+            ("cognitive", NEXO_HOME / "core" / "cognitive"),
             ("coordination", NEXO_HOME / "runtime" / "coordination"),
             ("exports", NEXO_HOME / "runtime" / "exports"),
             ("nexo-email", NEXO_HOME / "runtime" / "nexo-email"),
-            ("doctor", paths.core_doctor_dir(allow_legacy_fallback=False)),
+            ("doctor", NEXO_HOME / "core" / "doctor"),
             ("snapshots", NEXO_HOME / "runtime" / "snapshots"),
             ("crons", NEXO_HOME / "runtime" / "crons"),
             ("skills", NEXO_HOME / "personal" / "skills"),
@@ -3955,19 +3957,19 @@ def _resolve_sync_source() -> tuple[Path | None, Path | None]:
     dest = NEXO_HOME
 
     def _runtime_version_source() -> Path | None:
-        version_file = NEXO_HOME / "version.json"
-        if not version_file.is_file():
-            return None
-        try:
-            data = json.loads(version_file.read_text())
-        except Exception:
-            return None
-        source = str(data.get("source", "")).strip()
-        if not source:
-            return None
-        candidate = Path(source).expanduser()
-        if (candidate / "src").is_dir() and (candidate / "package.json").is_file():
-            return candidate
+        for version_file in (NEXO_HOME / "version.json", NEXO_HOME / "core" / "version.json"):
+            if not version_file.is_file():
+                continue
+            try:
+                data = json.loads(version_file.read_text())
+            except Exception:
+                continue
+            source = str(data.get("source", "")).strip()
+            if not source:
+                continue
+            candidate = Path(source).expanduser()
+            if (candidate / "src").is_dir() and (candidate / "package.json").is_file():
+                return candidate
         return None
 
     try:

package/src/bootstrap_docs.py

@@ -27,6 +27,14 @@ def _resolve_templates_dir(module_file: str | os.PathLike[str]) -> Path:
     parent = module_dir.parent / "templates"
     if parent.is_dir():
         return parent
+    try:
+        nexo_home_templates = resolve_nexo_home(
+            os.environ.get("NEXO_HOME", str(_user_home() / ".nexo"))
+        ) / "templates"
+    except Exception:
+        nexo_home_templates = Path(os.environ.get("NEXO_HOME", str(_user_home() / ".nexo"))).expanduser() / "templates"
+    if nexo_home_templates.is_dir():
+        return nexo_home_templates
     return direct
 
 

package/src/client_sync.py

@@ -143,6 +143,45 @@ def _resolve_operator_name(nexo_home: Path, explicit: str = "") -> str:
     return DEFAULT_ASSISTANT_NAME
 
 
+def _is_relative_to(path: Path, base: Path) -> bool:
+    try:
+        path.relative_to(base)
+        return True
+    except Exception:
+        return False
+
+
+def _normalize_managed_runtime_root(nexo_home: Path, candidate: Path) -> Path:
+    raw = candidate.expanduser()
+    if raw.name == "server.py":
+        raw = raw.parent
+    try:
+        resolved = raw.resolve()
+    except Exception:
+        resolved = raw.absolute()
+    core_root = (nexo_home / "core").expanduser()
+    current_root = core_root / "current"
+    preferred_targets = []
+    if (core_root / "server.py").is_file():
+        preferred_targets.append(core_root)
+    if (current_root / "server.py").is_file():
+        preferred_targets.append(current_root)
+    if not preferred_targets:
+        return resolved
+    try:
+        core_resolved = core_root.resolve()
+    except Exception:
+        core_resolved = core_root.absolute()
+    version_root = core_resolved / "versions"
+    try:
+        current_resolved = current_root.resolve()
+    except Exception:
+        current_resolved = current_root.absolute()
+    if resolved == current_resolved or _is_relative_to(resolved, version_root):
+        return preferred_targets[0]
+    return resolved
+
+
 def _resolve_runtime_root(nexo_home: Path, runtime_root: str | os.PathLike[str] | None = None) -> Path:
     candidates: list[Path] = []
     if runtime_root:
@@ -155,12 +194,13 @@ def _resolve_runtime_root(nexo_home: Path, runtime_root: str | os.PathLike[str]
 
     seen: set[Path] = set()
     for candidate in candidates:
-        resolved = candidate.resolve()
+        normalized = _normalize_managed_runtime_root(nexo_home, candidate)
+        resolved = normalized.resolve()
         if resolved in seen:
             continue
         seen.add(resolved)
-        if (resolved / "server.py").is_file():
-            return resolved
+        if (normalized / "server.py").is_file():
+            return normalized
     raise FileNotFoundError(f"Could not locate runtime root with server.py (tried {len(seen)} locations)")
 
 
@@ -409,6 +449,7 @@ def build_server_config(
     runtime_root: str | os.PathLike[str] | None = None,
     python_path: str = "",
     operator_name: str = "",
+    client: str = "",
 ) -> dict:
     nexo_home_path = Path(nexo_home).expanduser() if nexo_home else _default_nexo_home()
     runtime_root_path = _resolve_runtime_root(nexo_home_path, runtime_root)
@@ -423,6 +464,9 @@ def build_server_config(
     resolved_name = _resolve_operator_name(nexo_home_path, explicit=operator_name)
     if resolved_name:
         config["env"]["NEXO_NAME"] = resolved_name
+    resolved_client = normalize_client_key(client)
+    if resolved_client:
+        config["env"]["NEXO_MCP_CLIENT"] = resolved_client
     return config
 
 
@@ -436,6 +480,11 @@ def _claude_code_mcp_path(home: Path | None = None) -> Path:
     return base / ".claude.json"
 
 
+def _claude_code_cortex_path(home: Path | None = None) -> Path:
+    base = home or _user_home()
+    return base / ".claude" / "mcp-cortex.json"
+
+
 def _claude_desktop_config_path(home: Path | None = None) -> Path:
     base = home or _user_home()
     if sys.platform == "darwin":
@@ -1022,6 +1071,7 @@ def sync_claude_code(
         runtime_root=runtime_root,
         python_path=python_path,
         operator_name=operator_name,
+        client="claude_code",
     )
     home_path = Path(user_home).expanduser() if user_home else None
     result = _sync_claude_code_settings(
@@ -1039,6 +1089,13 @@ def sync_claude_code(
     )
     result["mcp"] = mcp_result
     result["mcp_path"] = mcp_result.get("path", "")
+    cortex_result = _sync_json_client(
+        _claude_code_cortex_path(home_path),
+        server_config,
+        "claude_code",
+    )
+    result["cortex_mcp"] = cortex_result
+    result["cortex_mcp_path"] = cortex_result.get("path", "")
     bootstrap_result = sync_client_bootstrap(
         "claude_code",
         nexo_home=nexo_home,
@@ -1066,6 +1123,7 @@ def sync_claude_desktop(
         runtime_root=runtime_root,
         python_path=python_path,
         operator_name=operator_name,
+        client="claude_desktop",
     )
     resolved_name = server_config.get("env", {}).get("NEXO_NAME", "") or _resolve_operator_name(
         Path(nexo_home).expanduser() if nexo_home else _default_nexo_home(),
@@ -1097,6 +1155,7 @@ def sync_codex(
         runtime_root=runtime_root,
         python_path=python_path,
         operator_name=operator_name,
+        client="codex",
     )
     codex_bin = shutil.which("codex")
     config_path = _codex_config_path(home_path)

package/src/core_prompts.py

@@ -10,15 +10,27 @@ from pathlib import Path
 _TOKEN_RE = re.compile(r"\[\[([a-zA-Z0-9_]+)\]\]")
 
 
+def _find_templates_root(start: Path) -> Path | None:
+    current = start.expanduser()
+    try:
+        current = current.resolve()
+    except Exception:
+        current = current.absolute()
+    if current.is_file():
+        current = current.parent
+    for candidate in (current, *current.parents):
+        if (candidate / "templates" / "core-prompts").is_dir():
+            return candidate
+    return None
+
+
 def _resolve_repo_root() -> Path:
-    candidate = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent))).expanduser().resolve()
-    if candidate.name == "src":
-        return candidate.parent
-    if (candidate / "templates").is_dir():
-        return candidate
-    if (candidate.parent / "templates").is_dir():
-        return candidate.parent
-    return Path(__file__).resolve().parents[1]
+    configured = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
+    resolved = _find_templates_root(configured)
+    if resolved is not None:
+        return resolved
+    fallback = Path(__file__).resolve().parents[1]
+    return _find_templates_root(fallback) or fallback
 
 
 PROMPTS_DIR = _resolve_repo_root() / "templates" / "core-prompts"

package/src/lifecycle_events.py

@@ -75,6 +75,7 @@ TERMINAL_STATUSES = {
     "rejected",
 }
 _DIARY_TRIGGERING = lifecycle_prompts.DIARY_TRIGGERING_ACTIONS
+SESSION_NOT_LINKED_REASON = "session-not-linked-to-nexo"
 
 
 def _normalise_payload(obj: Any) -> str:
@@ -125,6 +126,34 @@ def _session_diary_session_ids(conn, session_id: str) -> List[str]:
     return deduped
 
 
+def _session_is_linked_to_nexo(conn, session_id: str) -> bool:
+    """True when the external Claude/Desktop session is linked to a NEXO SID."""
+    raw = str(session_id or "").strip()
+    if not raw:
+        return False
+    if raw.startswith("nexo-"):
+        return True
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM session_claude_aliases WHERE claude_session_id = ? LIMIT 1",
+            (raw,),
+        ).fetchone()
+        if row is not None:
+            return True
+    except Exception:
+        pass
+    try:
+        row = conn.execute(
+            "SELECT 1 FROM sessions "
+            "WHERE external_session_id = ? OR claude_session_id = ? "
+            "LIMIT 1",
+            (raw, raw),
+        ).fetchone()
+        return row is not None
+    except Exception:
+        return False
+
+
 def _max_session_diary_id(conn, session_id: str) -> int:
     session_ids = _session_diary_session_ids(conn, session_id)
     if not session_ids:
@@ -510,10 +539,14 @@ def record_complete_canonical(
     )
     diary_evidence = _session_diary_evidence(conn, session_id, dispatched_at, actions_json)
     diary_required = action in _DIARY_TRIGGERING and bool(session_id)
+    session_registered = _session_is_linked_to_nexo(conn, session_id) if diary_required else bool(session_id)
+    session_unregistered = diary_required and not session_registered
     diary_missing = diary_required and diary_evidence is None
     effective = "retryable_error" if (any_failure or diary_missing) else "canonical_done"
     last_error = None
-    if any_failure:
+    if session_unregistered:
+        last_error = SESSION_NOT_LINKED_REASON
+    elif any_failure:
         last_error = "one-or-more-actions-failed"
     elif diary_missing:
         last_error = "canonical-diary-not-confirmed"
@@ -540,8 +573,9 @@ def record_complete_canonical(
         "failed_actions": any_failure,
         "diary_confirmed": diary_evidence is not None,
         "diary_required": diary_required,
+        "session_registered": session_registered,
         "session_diary_id": diary_evidence.get("session_diary_id") if diary_evidence else None,
-        "reason": "canonical-diary-not-confirmed" if diary_missing else None,
+        "reason": last_error if effective == "retryable_error" else None,
     }
 
 
@@ -570,6 +604,15 @@ def wait_for_canonical_diary(
         session_id = str(row[0] or "")
         if not session_id:
             return {"status": "rejected", "reason": "missing-session-id", "event_id": event_id}
+        if not _session_is_linked_to_nexo(conn, session_id):
+            return {
+                "status": "retryable_error",
+                "event_id": event_id,
+                "session_id": session_id,
+                "diary_confirmed": False,
+                "session_registered": False,
+                "reason": SESSION_NOT_LINKED_REASON,
+            }
         evidence = _session_diary_evidence(conn, session_id, row[1], row[2])
         if evidence is not None:
             return {
@@ -577,6 +620,7 @@ def wait_for_canonical_diary(
                 "event_id": event_id,
                 "session_id": session_id,
                 "diary_confirmed": True,
+                "session_registered": True,
                 **evidence,
             }
         if time.monotonic() >= deadline:
@@ -585,6 +629,7 @@ def wait_for_canonical_diary(
                 "event_id": event_id,
                 "session_id": session_id,
                 "diary_confirmed": False,
+                "session_registered": True,
                 "reason": last_error or "diary-confirm-timeout",
             }
         time.sleep(min(poll_s, max(0.0, deadline - time.monotonic())))

package/src/paths.py

@@ -71,6 +71,19 @@ def home() -> Path:
 # ---------------------------------------------------------------------------
 def core_dir() -> Path:
     container = home() / "core"
+    live_markers = (
+        "cli.py",
+        "server.py",
+        "db",
+        "hooks",
+        "plugins",
+        "rules",
+        "scripts",
+        "package.json",
+        "version.json",
+    )
+    if any((container / marker).exists() for marker in live_markers):
+        return container
     current = container / "current"
     if current.exists():
         try:

package/src/plugin_loader.py

@@ -290,7 +290,13 @@ def load_plugin(mcp, filename: str, plugins_dir: str | None = None) -> int:
             mcp.local_provider.remove_tool(name)
         except Exception:
             pass
-        t = Tool.from_function(func, name=name, description=description)
+        # output_schema=None disables FastMCP's auto-generated
+        # `x-fastmcp-wrap-result` wrapper that otherwise makes str-returning
+        # plugin tools unexecutable in Claude Code. See server.py and
+        # followup NF-FASTMCP-OUTPUT-SCHEMA-1776969764.
+        t = Tool.from_function(
+            func, name=name, description=description, output_schema=None
+        )
         mcp.add_tool(t)
         tool_names.append(name)
 

package/src/runtime_versioning.py

@@ -158,7 +158,7 @@ def write_restart_required_marker(
 def activate_versioned_runtime_snapshot(*, source_root: Path | None = None, version: str = "") -> dict:
     container = core_container_dir()
     source = Path(source_root or container)
-    if source == container and core_current_link().exists():
+    if source_root is None and source == container and core_current_link().exists():
         try:
             source = core_current_link().resolve(strict=False)
         except Exception:
@@ -319,6 +319,28 @@ def prime_process_version() -> str:
 class RestartRequiredMiddleware(Middleware):
     client: str = ""
 
+    async def _tool_result_for_restart_required(self, context, payload: dict) -> ToolResult:
+        payload_text = json.dumps(payload, ensure_ascii=False)
+        tool = None
+        try:
+            fastmcp_context = getattr(context, "fastmcp_context", None)
+            fastmcp_server = getattr(fastmcp_context, "fastmcp", None)
+            if fastmcp_server is not None:
+                tool = await fastmcp_server.get_tool(str(getattr(context.message, "name", "") or "").strip())
+        except Exception:
+            tool = None
+
+        output_schema = getattr(tool, "output_schema", None)
+        if isinstance(output_schema, dict) and output_schema.get("x-fastmcp-wrap-result"):
+            return ToolResult(
+                content=payload_text,
+                structured_content={"result": payload_text},
+            )
+        return ToolResult(
+            content=payload_text,
+            structured_content=payload,
+        )
+
     async def on_call_tool(self, context, call_next):
         tool_name = str(getattr(context.message, "name", "") or "").strip()
         state = resolve_restart_required(client=self.client)
@@ -336,7 +358,4 @@ class RestartRequiredMiddleware(Middleware):
             "reason": state["reason"],
             "client_action": state["client_action"],
         }
-        return ToolResult(
-            content=json.dumps(payload, ensure_ascii=False),
-            structured_content=payload,
-        )
+        return await self._tool_result_for_restart_required(context, payload)

package/src/server.py

@@ -280,6 +280,25 @@ mcp.add_middleware(
     RestartRequiredMiddleware(client=str(os.environ.get("NEXO_MCP_CLIENT", "") or "").strip())
 )
 
+# FastMCP (both 2.14.7 and 3.2.4) auto-generates an outputSchema wrapper
+# (`{required: [result], x-fastmcp-wrap-result: true}`) for every tool whose
+# return annotation is a non-object type such as `str`. Claude Code validates
+# MCP tool responses strictly against outputSchema and rejects our plain-text
+# replies with `Output validation error: result is a required property`,
+# which makes every `nexo_*` tool inexecutable from Claude Code. We opt out
+# of output_schema globally by wrapping `mcp.tool` so every decorator here
+# and in plugins defaults to `output_schema=None` unless the caller passes
+# something explicit. See followup NF-FASTMCP-OUTPUT-SCHEMA-1776969764.
+_mcp_tool_original = mcp.tool
+
+
+def _mcp_tool_without_output_schema(name_or_fn=None, **kwargs):
+    kwargs.setdefault("output_schema", None)
+    return _mcp_tool_original(name_or_fn, **kwargs)
+
+
+mcp.tool = _mcp_tool_without_output_schema  # type: ignore[method-assign]
+
 
 def _run_kwargs_from_env() -> dict:
     transport = str(os.environ.get("NEXO_MCP_TRANSPORT", "stdio") or "stdio").strip().lower()