nexo-brain 7.9.5 → 7.9.7

package/src/runtime_versioning.py

@@ -0,0 +1,361 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from fastmcp.server.middleware import Middleware
+from fastmcp.tools import ToolResult
+
+import paths
+
+
+CONTINUITY_API_LEVEL = 1
+MCP_STATUS_SCHEMA_VERSION = 1
+PROCESS_VERSION = ""
+RESTART_ALLOWLIST = {
+    "nexo_status",
+    "nexo_system_catalog",
+    "nexo_tool_explain",
+    "nexo_heartbeat",
+    "nexo_stop",
+    "nexo_session_portable_context",
+    "nexo_session_export_bundle",
+    "nexo_lifecycle_event",
+    "nexo_lifecycle_status",
+    "nexo_lifecycle_complete_canonical",
+    "nexo_lifecycle_wait_for_diary",
+    "nexo_continuity_snapshot_read",
+    "nexo_continuity_resume_bundle",
+    "nexo_continuity_audit",
+}
+
+
+def _read_json_file(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _write_json_atomic(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    tmp.replace(path)
+
+
+def core_container_dir() -> Path:
+    return paths.home() / "core"
+
+
+def core_versions_dir() -> Path:
+    return core_container_dir() / "versions"
+
+
+def core_current_link() -> Path:
+    return core_container_dir() / "current"
+
+
+def active_runtime_root() -> Path:
+    current = core_current_link()
+    if current.exists():
+        try:
+            resolved = current.resolve(strict=False)
+            if resolved.exists():
+                return resolved
+        except Exception:
+            pass
+        return current
+    core_dir = core_container_dir()
+    if (core_dir / "cli.py").is_file() or (core_dir / "server.py").is_file():
+        return core_dir
+    return paths.home()
+
+
+def restart_required_marker_path() -> Path:
+    return paths.operations_dir() / "mcp-restart-required.json"
+
+
+def _candidate_version_files(base: Path) -> list[Path]:
+    return [
+        base / "version.json",
+        base / "package.json",
+    ]
+
+
+def read_version_for_path(base: Path) -> str:
+    for candidate in _candidate_version_files(base):
+        try:
+            if candidate.is_file():
+                payload = json.loads(candidate.read_text(encoding="utf-8"))
+                version = str(payload.get("version", "")).strip()
+                if version:
+                    return version
+        except Exception:
+            continue
+    return ""
+
+
+def installed_runtime_version() -> str:
+    for candidate in [active_runtime_root(), paths.home()]:
+        version = read_version_for_path(candidate)
+        if version:
+            return version
+    return ""
+
+
+def read_restart_required_marker() -> dict:
+    path = restart_required_marker_path()
+    if not path.exists():
+        return {"required": False, "path": str(path), "exists": False}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(payload, dict):
+            raise ValueError("marker is not an object")
+        payload.setdefault("required", True)
+        payload["path"] = str(path)
+        payload["exists"] = True
+        return payload
+    except Exception as exc:
+        return {
+            "required": True,
+            "exists": True,
+            "path": str(path),
+            "corrupt": True,
+            "error": str(exc),
+        }
+
+
+def write_restart_required_marker(
+    *,
+    from_version: str,
+    to_version: str,
+    reason: str = "brain_update",
+) -> dict:
+    path = restart_required_marker_path()
+    payload = {
+        "schema_version": MCP_STATUS_SCHEMA_VERSION,
+        "required": True,
+        "from_version": str(from_version or "").strip(),
+        "to_version": str(to_version or "").strip(),
+        "reason": str(reason or "brain_update"),
+        "updated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "clients": {
+            "claude_desktop": "restart_client_required",
+            "claude_code": "restart_session_required",
+            "codex": "restart_session_required",
+        },
+    }
+    _write_json_atomic(path, payload)
+    payload["path"] = str(path)
+    return payload
+
+
+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_root is None and source == container and core_current_link().exists():
+        try:
+            source = core_current_link().resolve(strict=False)
+        except Exception:
+            pass
+    resolved_version = str(version or read_version_for_path(source) or installed_runtime_version()).strip()
+    if not resolved_version:
+        return {"ok": False, "error": "missing_version", "source_root": str(source)}
+
+    versions_dir = core_versions_dir()
+    target = versions_dir / resolved_version
+    versions_dir.mkdir(parents=True, exist_ok=True)
+    target.mkdir(parents=True, exist_ok=True)
+
+    copied: list[str] = []
+    for item in source.iterdir():
+        if item.name in {"versions", "current", "__pycache__"}:
+            continue
+        dest = target / item.name
+        if dest.exists() or dest.is_symlink():
+            if dest.is_dir() and not dest.is_symlink():
+                shutil.rmtree(dest)
+            else:
+                dest.unlink()
+        if item.is_dir():
+            shutil.copytree(item, dest, symlinks=True, ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"))
+        else:
+            shutil.copy2(item, dest)
+        copied.append(item.name)
+
+    current = core_current_link()
+    tmp_link = current.with_name(f".current.{os.getpid()}.tmp")
+    if tmp_link.exists() or tmp_link.is_symlink():
+        tmp_link.unlink()
+    target_rel = Path("versions") / resolved_version
+    os.symlink(str(target_rel), str(tmp_link))
+    os.replace(str(tmp_link), str(current))
+    return {
+        "ok": True,
+        "version": resolved_version,
+        "source_root": str(source),
+        "target_root": str(target),
+        "current_link": str(current),
+        "copied": copied,
+    }
+
+
+def clear_restart_required_marker(*, client: str = "", installed_version: str = "", process_version: str = "") -> dict:
+    path = restart_required_marker_path()
+    marker = read_restart_required_marker()
+    if not marker.get("required"):
+        return {"ok": True, "cleared": False, "path": str(path)}
+    if marker.get("corrupt"):
+        try:
+            path.unlink(missing_ok=True)
+        except Exception:
+            pass
+        return {"ok": True, "cleared": True, "path": str(path), "corrupt": True}
+
+    payload = dict(marker)
+    clients = dict(payload.get("clients") or {})
+    if client:
+        clients[client] = "ok"
+        payload["clients"] = clients
+    pending_clients = {k: v for k, v in clients.items() if v != "ok"}
+    effective_installed = str(installed_version or payload.get("to_version") or "").strip()
+    effective_process = str(process_version or "").strip()
+    if pending_clients:
+        _write_json_atomic(path, payload)
+        return {"ok": True, "cleared": False, "path": str(path), "pending_clients": pending_clients}
+    if effective_installed and effective_process and effective_installed != effective_process:
+        _write_json_atomic(path, payload)
+        return {
+            "ok": True,
+            "cleared": False,
+            "path": str(path),
+            "pending_reason": "process_version_mismatch",
+        }
+    try:
+        path.unlink(missing_ok=True)
+    except Exception:
+        pass
+    return {"ok": True, "cleared": True, "path": str(path)}
+
+
+def resolve_restart_required(*, client: str = "", installed_version: str = "", process_version: str = "") -> dict:
+    marker = read_restart_required_marker()
+    installed = str(installed_version or installed_runtime_version() or "").strip()
+    process = str(process_version or PROCESS_VERSION or installed).strip()
+    restart_required = False
+    reason = ""
+    client_action = ""
+    marker_clients = dict(marker.get("clients") or {})
+
+    if marker.get("required"):
+        restart_required = True
+        reason = "marker_required"
+        client_action = str(marker_clients.get(client) or "")
+    if marker.get("corrupt"):
+        restart_required = True
+        reason = "marker_corrupt"
+    elif installed and process and installed != process:
+        restart_required = True
+        reason = reason or "version_mismatch"
+    elif client and client_action == "ok":
+        restart_required = False
+        reason = ""
+
+    return {
+        "restart_required": restart_required,
+        "reason": reason,
+        "client_action": client_action,
+        "marker": marker,
+        "installed_version": installed,
+        "process_version": process,
+    }
+
+
+def build_mcp_status(*, client: str = "") -> dict:
+    state = resolve_restart_required(client=client)
+    marker = state["marker"]
+    return {
+        "ok": True,
+        "schema_version": MCP_STATUS_SCHEMA_VERSION,
+        "client": str(client or "").strip(),
+        "installed_version": state["installed_version"],
+        "process_version": state["process_version"],
+        "active_runtime_root": str(active_runtime_root()),
+        "active_runtime_version": read_version_for_path(active_runtime_root()),
+        "restart_required": bool(state["restart_required"]),
+        "reason": state["reason"],
+        "client_action": state["client_action"],
+        "marker_path": marker.get("path", str(restart_required_marker_path())),
+        "marker_exists": bool(marker.get("exists")),
+        "marker_corrupt": bool(marker.get("corrupt")),
+        "continuity_api_level": CONTINUITY_API_LEVEL,
+        "version_match": (
+            bool(state["installed_version"])
+            and bool(state["process_version"])
+            and state["installed_version"] == state["process_version"]
+        ),
+    }
+
+
+def prime_process_version() -> str:
+    global PROCESS_VERSION
+    if PROCESS_VERSION:
+        return PROCESS_VERSION
+    for candidate in [Path(__file__).resolve().parent, active_runtime_root(), paths.home()]:
+        version = read_version_for_path(candidate)
+        if version:
+            PROCESS_VERSION = version
+            return version
+    PROCESS_VERSION = "unknown"
+    return PROCESS_VERSION
+
+
+@dataclass
+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)
+        if not state["restart_required"] or tool_name in RESTART_ALLOWLIST:
+            return await call_next(context)
+
+        payload = {
+            "ok": False,
+            "error": "mcp_restart_required",
+            "message": "NEXO Brain was updated. Restart this MCP client/session.",
+            "restart_required": True,
+            "tool": tool_name,
+            "installed_version": state["installed_version"],
+            "process_version": state["process_version"],
+            "reason": state["reason"],
+            "client_action": state["client_action"],
+        }
+        return await self._tool_result_for_restart_required(context, payload)

package/src/server.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import os
 import signal
 import sys
+import json
 
 from fastmcp import FastMCP
 from core_prompts import render_core_prompt
@@ -17,6 +18,15 @@ from tools_sessions import (
     handle_session_portable_context,
     handle_session_export_bundle,
 )
+from continuity import (
+    build_resume_bundle,
+    continuity_audit,
+    format_bundle_text,
+    json_dumps as _continuity_json_dumps,
+    read_snapshot,
+    record_compaction_event,
+    write_snapshot,
+)
 from tools_hot_context import (
     handle_recent_context_capture,
     handle_recent_context,
@@ -81,6 +91,11 @@ from plugins.workflow import (
 )
 from plugin_loader import load_all_plugins, load_plugin, remove_plugin, list_plugins
 from tools_guardian import handle_guardian_rule_override
+from runtime_versioning import (
+    RestartRequiredMiddleware,
+    build_mcp_status,
+    prime_process_version,
+)
 
 
 # ── Graceful shutdown: close DB on any termination signal ──────────
@@ -260,6 +275,29 @@ mcp = FastMCP(
         assistant_name=_get_ctx().assistant_name,
     ),
 )
+prime_process_version()
+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:
@@ -290,7 +328,7 @@ def _run_kwargs_from_env() -> dict:
 # ── Session management (3 tools) ──────────────────────────────────
 
 @mcp.tool
-def nexo_startup(task: str = "Startup", claude_session_id: str = "", session_token: str = "", session_client: str = "") -> str:
+def nexo_startup(task: str = "Startup", claude_session_id: str = "", session_token: str = "", session_client: str = "", conversation_id: str = "") -> str:
     """Register new session, clean stale ones, return active sessions + alerts.
 
     Call this ONCE at the start of every conversation.
@@ -303,12 +341,14 @@ def nexo_startup(task: str = "Startup", claude_session_id: str = "", session_tok
                       other clients may pass a synthetic durable token when useful.
                       Pass this to enable automatic inter-terminal inbox detection when available.
         session_client: Optional client label such as `claude_code` or `codex`.
+        conversation_id: Stable client-side conversation identifier when available.
     """
     return handle_startup(
         task,
         claude_session_id=claude_session_id,
         session_token=session_token,
         session_client=session_client,
+        conversation_id=conversation_id,
     )
 
 
@@ -565,6 +605,87 @@ def nexo_status(keyword: str = "") -> str:
     return handle_status(keyword if keyword else None)
 
 
+@mcp.tool
+def nexo_continuity_snapshot_write(
+    conversation_id: str,
+    session_id: str = "",
+    external_session_id: str = "",
+    client: str = "",
+    event_type: str = "turn_end",
+    payload: str = "",
+    trace_id: str = "",
+    idempotency_key: str = "",
+) -> str:
+    """Write a durable continuity snapshot for Desktop/Brain handoff."""
+    return _continuity_json_dumps(
+        write_snapshot(
+            conversation_id=conversation_id,
+            session_id=session_id,
+            external_session_id=external_session_id,
+            client=client,
+            event_type=event_type,
+            payload=payload,
+            trace_id=trace_id,
+            idempotency_key=idempotency_key,
+        )
+    )
+
+
+@mcp.tool
+def nexo_continuity_snapshot_read(conversation_id: str = "", session_id: str = "", limit: int = 20) -> str:
+    """Read recent continuity snapshots by conversation_id or session_id."""
+    return _continuity_json_dumps(
+        read_snapshot(conversation_id=conversation_id, session_id=session_id, limit=limit)
+    )
+
+
+@mcp.tool
+def nexo_continuity_resume_bundle(
+    conversation_id: str = "",
+    session_id: str = "",
+    external_session_id: str = "",
+    client: str = "",
+    token_budget: int = 2000,
+) -> str:
+    """Build the small continuity bundle Desktop injects after restore or stale resume loss."""
+    bundle = build_resume_bundle(
+        conversation_id=conversation_id,
+        session_id=session_id,
+        external_session_id=external_session_id,
+        client=client,
+        token_budget=token_budget,
+    )
+    if not bundle.get("unsafe_sid"):
+        bundle["message"] = format_bundle_text(bundle)
+    return _continuity_json_dumps(bundle)
+
+
+@mcp.tool
+def nexo_continuity_compaction_event(
+    conversation_id: str,
+    session_id: str = "",
+    payload: str = "",
+    trace_id: str = "",
+    event_type: str = "post_compact",
+) -> str:
+    """Persist a compaction-related continuity event into the canonical snapshot stream."""
+    return _continuity_json_dumps(
+        record_compaction_event(
+            conversation_id=conversation_id,
+            session_id=session_id,
+            payload=payload,
+            trace_id=trace_id,
+            event_type=event_type,
+        )
+    )
+
+
+@mcp.tool
+def nexo_continuity_audit(conversation_id: str, limit: int = 50) -> str:
+    """Return the forensic continuity timeline for a conversation."""
+    return _continuity_json_dumps(continuity_audit(conversation_id=conversation_id, limit=limit))
+
+
 @mcp.tool
 def nexo_context_packet(area: str, files: str = "") -> str:
     """Build a context packet for subagent injection. Returns learnings + changes + followups + preferences + cognitive memories for a specific area.

package/src/tools_sessions.py

@@ -198,6 +198,7 @@ def _session_portability_bundle(sid: str = "") -> dict:
             "task": session_row["task"],
             "client": session_row["session_client"],
             "external_session_id": session_row["external_session_id"],
+            "conversation_id": session_row["conversation_id"],
             "started_epoch": session_row["started_epoch"],
             "last_update_epoch": session_row["last_update_epoch"],
             "local_time": session_row["local_time"],
@@ -363,6 +364,7 @@ def handle_startup(
     claude_session_id: str = "",
     session_token: str = "",
     session_client: str = "",
+    conversation_id: str = "",
 ) -> str:
     """Full startup sequence: register, clean, report.
 
@@ -393,12 +395,28 @@ def handle_startup(
         # If we recovered the UUID from the coordination file, the only
         # client that writes there is Claude Code.
         inferred_client = "claude_code"
+    conversation = str(conversation_id or "").strip()
+    conflicts = []
+    if conversation:
+        cutoff = now_epoch() - SESSION_STALE_SECONDS
+        conn = get_db()
+        rows = conn.execute(
+            """
+            SELECT sid, task, last_update_epoch, external_session_id, session_client
+            FROM sessions
+            WHERE conversation_id = ? AND last_update_epoch > ?
+            ORDER BY last_update_epoch DESC
+            """,
+            (conversation, cutoff),
+        ).fetchall()
+        conflicts = [dict(row) for row in rows if row["sid"] != sid]
     register_session(
         sid,
         task,
         claude_session_id=linked_session_id,
         external_session_id=linked_session_id,
         session_client=inferred_client,
+        conversation_id=conversation,
     )
     # v43 hotfix: also register in session_claude_aliases so multi-
     # conversation NEXO Desktop spawns (each with its own claude UUID)
@@ -420,6 +438,8 @@ def handle_startup(
     inbox = get_inbox(sid)
 
     lines = [f"SID: {sid}"]
+    if conversation:
+        lines.append(f"CONVERSATION_ID: {conversation}")
 
     if cleaned > 0:
         lines.append(f"Cleaned {cleaned} stale sessions.")
@@ -433,6 +453,16 @@ def handle_startup(
     else:
         lines.append("No other active sessions.")
 
+    if conflicts:
+        lines.append("")
+        lines.append("CONVERSATION CONFLICT:")
+        for row in conflicts[:3]:
+            age = _format_age(row["last_update_epoch"])
+            lines.append(
+                f"  {row['sid']} ({age}) — {row['task']} "
+                f"[client={row.get('session_client') or '?'} external={row.get('external_session_id') or '?'}]"
+            )
+
     if inbox:
         lines.append("")
         lines.append("PENDING MESSAGES:")

package/tool-enforcement-map.json

@@ -838,6 +838,81 @@
       },
       "triggers_after": []
     },
+    "nexo_continuity_audit": {
+      "description": "Read the forensic continuity timeline for a conversation",
+      "category": "continuity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "continuity_timeline"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_continuity_compaction_event": {
+      "description": "Persist a compaction-related continuity event",
+      "category": "continuity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "continuity_snapshot"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_continuity_resume_bundle": {
+      "description": "Build the small continuity bundle used after restore/restart",
+      "category": "continuity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "resume_bundle"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_continuity_snapshot_read": {
+      "description": "Read recent continuity snapshots by conversation or session",
+      "category": "continuity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "continuity_snapshots"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_continuity_snapshot_write": {
+      "description": "Write a durable continuity snapshot",
+      "category": "continuity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "continuity_snapshot"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
     "nexo_cortex_check": {
       "description": "Cognitive pre-action check",
       "category": "cortex",