nexo-brain 7.20.19 → 7.20.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.20.19",
+  "version": "7.20.21",
   "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/cli.py

@@ -140,6 +140,166 @@ def _mcp_status(args) -> int:
     )
 
 
+def _mcp_write_message(stdin, payload: dict) -> None:
+    raw = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    stdin.write(raw + b"\n")
+    stdin.flush()
+
+
+def _mcp_reader(stdout, queue) -> None:
+    while True:
+        try:
+            line = stdout.readline()
+            if not line:
+                return
+            text = line.decode("utf-8", errors="replace").strip()
+            if not text:
+                continue
+            queue.put(json.loads(text))
+        except Exception as exc:
+            queue.put({"_reader_error": str(exc)})
+            return
+
+
+def _stderr_reader(stderr, lines: list[str]) -> None:
+    while True:
+        chunk = stderr.readline()
+        if not chunk:
+            return
+        try:
+            lines.append(chunk.decode("utf-8", errors="replace").rstrip())
+        except Exception:
+            lines.append(repr(chunk))
+        del lines[:-80]
+
+
+def _mcp_wait_for_response(queue, request_id: int, timeout_seconds: float) -> dict:
+    import queue as queue_module
+
+    deadline = time.monotonic() + max(timeout_seconds, 0.1)
+    while time.monotonic() < deadline:
+        remaining = max(deadline - time.monotonic(), 0.05)
+        try:
+            message = queue.get(timeout=remaining)
+        except queue_module.Empty:
+            break
+        if message.get("_reader_error"):
+            raise RuntimeError(message["_reader_error"])
+        if message.get("id") == request_id:
+            return message
+    raise TimeoutError(f"MCP response {request_id} timed out")
+
+
+def _mcp_probe(args) -> int:
+    import queue as queue_module
+    import threading
+
+    timeout_ms = int(getattr(args, "timeout_ms", 8000) or 8000)
+    timeout_seconds = max(timeout_ms / 1000.0, 1.0)
+    started_at = time.monotonic()
+    server_path = NEXO_CODE / "server.py"
+    env = os.environ.copy()
+    env["NEXO_MCP_PROBE"] = "1"
+    env.setdefault("NEXO_MCP_PLUGIN_MODE", getattr(args, "plugin_mode", None) or "none")
+    env.setdefault("NEXO_MCP_RUN_STARTUP_PREFLIGHT", "0")
+    client = str(getattr(args, "client", "") or "").strip()
+    if client:
+        env["NEXO_MCP_CLIENT"] = client
+
+    proc = None
+    stderr_lines: list[str] = []
+    try:
+        proc = subprocess.Popen(
+            [sys.executable, str(server_path)],
+            cwd=str(NEXO_CODE),
+            env=env,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=False,
+        )
+        responses = queue_module.Queue()
+        threading.Thread(target=_mcp_reader, args=(proc.stdout, responses), daemon=True).start()
+        threading.Thread(target=_stderr_reader, args=(proc.stderr, stderr_lines), daemon=True).start()
+
+        _mcp_write_message(proc.stdin, {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "nexo-mcp-probe", "version": _get_version()},
+            },
+        })
+        init_response = _mcp_wait_for_response(responses, 1, timeout_seconds)
+        if init_response.get("error"):
+            raise RuntimeError(f"MCP initialize failed: {init_response['error']}")
+
+        _mcp_write_message(proc.stdin, {
+            "jsonrpc": "2.0",
+            "method": "notifications/initialized",
+            "params": {},
+        })
+        _mcp_write_message(proc.stdin, {
+            "jsonrpc": "2.0",
+            "id": 2,
+            "method": "tools/list",
+            "params": {},
+        })
+        tools_response = _mcp_wait_for_response(responses, 2, timeout_seconds)
+        if tools_response.get("error"):
+            raise RuntimeError(f"MCP tools/list failed: {tools_response['error']}")
+        tools = ((tools_response.get("result") or {}).get("tools") or [])
+        tool_names = [
+            str(tool.get("name") or "")
+            for tool in tools
+            if isinstance(tool, dict) and tool.get("name")
+        ]
+        required = ["nexo_startup", "nexo_heartbeat", "nexo_task_open", "nexo_guard_check"]
+        missing = [name for name in required if name not in tool_names]
+        ok = not missing and len(tool_names) > 0
+        payload = {
+            "ok": ok,
+            "mcp_ready": ok,
+            "probe_ok": ok,
+            "tools_available": len(tool_names) > 0,
+            "tool_count": len(tool_names),
+            "required_tools_present": not missing,
+            "missing_required_tools": missing,
+            "client": client,
+            "plugin_mode": env.get("NEXO_MCP_PLUGIN_MODE"),
+            "elapsed_ms": int((time.monotonic() - started_at) * 1000),
+            "stderr_tail": "\n".join(stderr_lines[-12:]),
+        }
+        return _print_json_or_text(payload, as_json=bool(getattr(args, "json", False)))
+    except Exception as exc:
+        payload = {
+            "ok": False,
+            "mcp_ready": False,
+            "probe_ok": False,
+            "error": "mcp_probe_failed",
+            "message": str(exc),
+            "client": client,
+            "elapsed_ms": int((time.monotonic() - started_at) * 1000),
+            "stderr_tail": "\n".join(stderr_lines[-20:]),
+        }
+        return _print_json_or_text(payload, as_json=bool(getattr(args, "json", False)))
+    finally:
+        if proc is not None:
+            try:
+                proc.terminate()
+            except Exception:
+                pass
+            try:
+                proc.wait(timeout=2)
+            except Exception:
+                try:
+                    proc.kill()
+                except Exception:
+                    pass
+
+
 def _mcp_clear_restart(args) -> int:
     return _print_json_or_text(
         clear_restart_required_marker(
@@ -3562,6 +3722,11 @@ def main():
     mcp_status_p = mcp_sub.add_parser("status", help="Read the current runtime/MCP alignment state")
     mcp_status_p.add_argument("--client", default="", help="Optional client label such as claude_desktop or codex")
     mcp_status_p.add_argument("--json", action="store_true", help="JSON output")
+    mcp_probe_p = mcp_sub.add_parser("probe", help="Launch the MCP server and verify initialize + tools/list")
+    mcp_probe_p.add_argument("--client", default="", help="Optional client label such as claude_desktop or codex")
+    mcp_probe_p.add_argument("--timeout-ms", type=int, default=8000)
+    mcp_probe_p.add_argument("--plugin-mode", default="none", choices=["essential", "none", "full"])
+    mcp_probe_p.add_argument("--json", action="store_true", help="JSON output")
     mcp_clear_p = mcp_sub.add_parser("clear-restart", help="Acknowledge that a client/session reloaded the new runtime")
     mcp_clear_p.add_argument("--client", default="", help="Client label such as claude_desktop or codex")
     mcp_clear_p.add_argument("--installed-version", default="")
@@ -3865,6 +4030,8 @@ def main():
     elif args.command == "mcp":
         if args.mcp_command == "status":
             return _mcp_status(args)
+        if args.mcp_command == "probe":
+            return _mcp_probe(args)
         if args.mcp_command == "clear-restart":
             return _mcp_clear_restart(args)
         mcp_parser.print_help()

package/src/server.py

@@ -259,8 +259,56 @@ def _run_startup_preflight_sync() -> None:
         print(f"[NEXO auto-update] error: {e}", file=sys.stderr)
 
 
+_ESSENTIAL_MCP_STARTUP_PLUGINS = (
+    "cards.py",
+    "doctor.py",
+    "episodic_memory.py",
+    "evolution.py",
+    "lifecycle_events.py",
+    "outcomes.py",
+    "preferences.py",
+    "protocol.py",
+    "recover.py",
+    "skills.py",
+    "user_state_tools.py",
+    "workflow.py",
+)
+
+
+def _env_flag(name: str, *, default: bool = False) -> bool:
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    return str(value).strip().lower() in {"1", "true", "yes", "on", "y", "si"}
+
+
+def _mcp_startup_plugin_mode() -> str:
+    return str(os.environ.get("NEXO_MCP_PLUGIN_MODE", "none") or "none").strip().lower()
+
+
+def _load_startup_plugins() -> None:
+    mode = _mcp_startup_plugin_mode()
+    if mode in {"none", "off", "0", "false"}:
+        print("[NEXO] MCP dynamic plugin loading skipped.", file=sys.stderr)
+        return
+    if mode in {"full", "all", "legacy"}:
+        load_all_plugins(mcp)
+        return
+
+    if mode not in {"essential", "fast", "default"}:
+        print(f"[NEXO] Unknown NEXO_MCP_PLUGIN_MODE={mode!r}; using essential plugins.", file=sys.stderr)
+
+    loaded = 0
+    for filename in _ESSENTIAL_MCP_STARTUP_PLUGINS:
+        try:
+            loaded += int(load_plugin(mcp, filename) or 0)
+        except Exception as exc:
+            print(f"[PLUGIN ERROR] {filename}: {exc}", file=sys.stderr)
+    print(f"[NEXO] MCP essential plugins ready: {loaded} tools.", file=sys.stderr)
+
+
 def _server_init():
-    """Run all side effects: signals, PID, DB, auto-update, plugins.
+    """Run side effects needed by the MCP server.
 
     Called only when the server is actually started (not on import).
     """
@@ -268,20 +316,26 @@ def _server_init():
     signal.signal(signal.SIGINT, _shutdown_handler)
 
     # ── Write PID file for stale process detection ─────────────────
-    data_dir = _data_dir()
-    os.makedirs(data_dir, exist_ok=True)
-    _pid_file = os.path.join(data_dir, "nexo.pid")
-    with open(_pid_file, "w") as f:
-        f.write(str(os.getpid()))
+    if not _env_flag("NEXO_MCP_PROBE"):
+        data_dir = _data_dir()
+        os.makedirs(data_dir, exist_ok=True)
+        _pid_file = os.path.join(data_dir, "nexo.pid")
+        with open(_pid_file, "w") as f:
+            f.write(str(os.getpid()))
 
     # ── Database initialization with recovery ─────────────────────
     _init_db_or_exit()
 
-    # ── Auto-update / startup preflight (synchronous) ─────────────
-    _run_startup_preflight_sync()
+    # ── Auto-update / startup preflight ───────────────────────────
+    # The MCP client waits for an immediate JSON-RPC handshake. Running update
+    # checks here can block the transport and make clients start without NEXO.
+    if _env_flag("NEXO_MCP_RUN_STARTUP_PREFLIGHT"):
+        _run_startup_preflight_sync()
+    else:
+        print("[NEXO] MCP startup preflight deferred.", file=sys.stderr)
 
     # ── Load plugins ───────────────────────────────────────────────
-    load_all_plugins(mcp)
+    _load_startup_plugins()
 
 
 mcp = FastMCP(

package/src/tools_sessions.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import json
 import os
 import paths
+import sqlite3
 import time
 import secrets
 import threading
@@ -81,6 +82,45 @@ def _env_flag(name: str, default: bool = False) -> bool:
     return raw.strip().lower() not in {"", "0", "false", "no", "off"}
 
 
+def _interactive_db_timeout_ms() -> int:
+    """Short DB wait for interactive MCP tools.
+
+    Long waits make Desktop look frozen when a background cron briefly owns
+    the SQLite writer lock. Interactive tools should degrade and let the chat
+    continue instead of waiting 30s per query.
+    """
+    try:
+        return max(50, min(int(os.environ.get("NEXO_MCP_DB_BUSY_TIMEOUT_MS", "250")), 10000))
+    except Exception:
+        return 250
+
+
+def _set_interactive_db_timeout() -> None:
+    try:
+        conn = get_db()
+        conn.execute(f"PRAGMA busy_timeout={_interactive_db_timeout_ms()}")
+    except Exception:
+        pass
+
+
+def _is_db_busy(exc: BaseException) -> bool:
+    if isinstance(exc, sqlite3.OperationalError) and "database is locked" in str(exc).lower():
+        return True
+    return "database is locked" in str(exc).lower()
+
+
+def _safe_interactive(label: str, fn, default=None, warnings: list[str] | None = None):
+    try:
+        return fn()
+    except Exception as exc:
+        if warnings is not None:
+            if _is_db_busy(exc):
+                warnings.append(f"{label}: skipped because the local brain database is busy")
+            else:
+                warnings.append(f"{label}: skipped ({type(exc).__name__})")
+        return default
+
+
 def _keepalive_loop(sid: str, stop_event: threading.Event) -> None:
     """Periodically touch the session's last_update_epoch until stopped."""
     while not stop_event.wait(KEEPALIVE_INTERVAL):
@@ -381,8 +421,21 @@ def handle_startup(
                       Enables automatic inbox detection when hook-backed clients provide one.
         session_client: Optional client label such as `claude_code` or `codex`.
     """
+    _set_interactive_db_timeout()
     sid = _generate_sid()
-    cleaned = clean_stale_sessions()
+    startup_warnings: list[str] = []
+    cleaned = _safe_interactive("stale-session cleanup", clean_stale_sessions, 0, startup_warnings)
+    if startup_warnings:
+        lines = [f"SID: {sid}"]
+        conversation = str(conversation_id or "").strip()
+        if conversation:
+            lines.append(f"CONVERSATION_ID: {conversation}")
+        lines.append("")
+        lines.append("STARTUP DEGRADED:")
+        for warning in startup_warnings[:4]:
+            lines.append(f"  {warning}")
+        lines.append("  Continue responding; retry nexo_heartbeat shortly for full context.")
+        return "\n".join(lines)
     linked_session_id = (session_token or claude_session_id or "").strip()
     # v6.0.7 hotfix: when the caller did not pass an explicit UUID, fall back to
     # the Claude Code SessionStart UUID written by the SessionStart hook to
@@ -403,36 +456,47 @@ def handle_startup(
     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,
+        def _load_conflicts():
+            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()
+            return [dict(row) for row in rows if row["sid"] != sid]
+
+        conflicts = _safe_interactive("conversation conflict lookup", _load_conflicts, [], startup_warnings)
+    registered = _safe_interactive(
+        "session registration",
+        lambda: register_session(
+            sid,
+            task,
+            claude_session_id=linked_session_id,
+            external_session_id=linked_session_id,
+            session_client=inferred_client,
+            conversation_id=conversation,
+        ),
+        None,
+        startup_warnings,
     )
     memory_maintenance = None
-    try:
-        backfill_limit = int(os.environ.get("NEXO_MEMORY_STARTUP_BACKFILL_LIMIT", "250") or "250")
-        memory_maintenance = maintain_memory_observations(
-            process_limit=100,
-            retry_failed=True,
-            backfill_limit=backfill_limit,
-        )
-    except Exception as exc:
-        memory_maintenance = {"ok": False, "error": str(exc)}
+    if _env_flag("NEXO_MEMORY_MAINTENANCE_IN_STARTUP", default=False):
+        try:
+            backfill_limit = int(os.environ.get("NEXO_MEMORY_STARTUP_BACKFILL_LIMIT", "0") or "0")
+            memory_maintenance = maintain_memory_observations(
+                process_limit=int(os.environ.get("NEXO_MEMORY_STARTUP_PROCESS_LIMIT", "20") or "20"),
+                retry_failed=True,
+                backfill_limit=backfill_limit,
+            )
+        except Exception as exc:
+            memory_maintenance = {"ok": False, "error": str(exc)}
+    else:
+        memory_maintenance = {"ok": True, "skipped": True}
     # v43 hotfix: also register in session_claude_aliases so multi-
     # conversation NEXO Desktop spawns (each with its own claude UUID)
     # resolve to the same NEXO sid on every PreToolUse hook lookup.
@@ -447,10 +511,11 @@ def handle_startup(
         except Exception:
             # Never let alias registration failures block startup.
             pass
-    _start_keepalive(sid)
-    active = get_active_sessions()
+    if registered:
+        _start_keepalive(sid)
+    active = _safe_interactive("active-session lookup", get_active_sessions, [], startup_warnings)
     other_sessions = [s for s in active if s["sid"] != sid]
-    inbox = get_inbox(sid)
+    inbox = _safe_interactive("inbox lookup", lambda: get_inbox(sid), [], startup_warnings)
 
     lines = [f"SID: {sid}"]
     if conversation:
@@ -459,6 +524,13 @@ def handle_startup(
     if cleaned > 0:
         lines.append(f"Cleaned {cleaned} stale sessions.")
 
+    if startup_warnings:
+        lines.append("")
+        lines.append("STARTUP DEGRADED:")
+        for warning in startup_warnings[:4]:
+            lines.append(f"  {warning}")
+        lines.append("  Continue responding; retry nexo_heartbeat shortly for full context.")
+
     if other_sessions:
         lines.append("")
         lines.append("ACTIVE SESSIONS:")
@@ -649,6 +721,8 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
     """Inner body of handle_heartbeat — wrapped by tool_span above."""
     from db import get_db, update_last_heartbeat_ts
 
+    _set_interactive_db_timeout()
+    heartbeat_warnings: list[str] = []
     mandate_state = None
     if context_hint:
         try:
@@ -658,6 +732,7 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
                 context_hint,
                 session_id=sid,
                 source="heartbeat",
+                classifier=(lambda **_: False),
             )
         except Exception:
             mandate_state = None
@@ -669,7 +744,7 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
         except Exception:
             mandate_state = None
 
-    update_session(sid, task)
+    _safe_interactive("session heartbeat update", lambda: update_session(sid, task), None, heartbeat_warnings)
     # v6.0.1 — stamp last_heartbeat_ts so the PostToolUse hook can
     # decide whether to surface a pending-inbox reminder on autopilot
     # sessions. Best-effort: never break the heartbeat on failure.
@@ -683,8 +758,15 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
     # no timezone assumption: clients format per operator preferences.
     _now_iso = datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
     parts = [f"NOW_UTC: {_now_iso}", f"OK: {sid} — {task}"]
+    if heartbeat_warnings:
+        parts.append("")
+        parts.append("HEARTBEAT DEGRADED:")
+        for warning in heartbeat_warnings[:3]:
+            parts.append(f"  {warning}")
+        parts.append("  Continue with the user request; context will catch up on a later heartbeat.")
+        return "\n".join(parts)
 
-    inbox = get_inbox(sid)
+    inbox = _safe_interactive("inbox lookup", lambda: get_inbox(sid), [], heartbeat_warnings)
     if inbox:
         parts.append("")
         parts.append("MESSAGES:")
@@ -692,7 +774,7 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
             age = _format_age(m["created_epoch"])
             parts.append(f"  [{m['from_sid']}] ({age}): {m['text']}")
 
-    questions = get_pending_questions(sid)
+    questions = _safe_interactive("pending-question lookup", lambda: get_pending_questions(sid), [], heartbeat_warnings)
     if questions:
         parts.append("")
         parts.append("PENDING QUESTIONS (respond with nexo_answer):")
@@ -712,7 +794,7 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
             if bundle.get("has_matches"):
                 parts.append("")
                 parts.append(format_pre_action_context_bundle(bundle, compact=True))
-            if append_local_context_evidence is not None:
+            if _env_flag("NEXO_HEARTBEAT_LOCAL_CONTEXT", default=False) and append_local_context_evidence is not None:
                 local_rendered = append_local_context_evidence("", recent_query, limit=4).strip()
                 if local_rendered:
                     parts.append("")
@@ -813,7 +895,7 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
 
     # ── Drive/Curiosity: detect signals from context_hint (best-effort) ──
     try:
-        if context_hint and len(context_hint.strip()) >= 15:
+        if _env_flag("NEXO_DRIVE_IN_HEARTBEAT", default=False) and context_hint and len(context_hint.strip()) >= 15:
             from tools_drive import detect_drive_signal as _detect_drive
             _drive_allow_llm = _env_flag("NEXO_DRIVE_LLM_IN_HEARTBEAT", default=False)
             _drive_result = _detect_drive(
@@ -835,11 +917,16 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
         pass  # Drive detection is best-effort, never block heartbeat
 
     # ── Layer 3: DIARY_OVERDUE signal based on heartbeat count + time ──
-    conn = get_db()
-    row = conn.execute("SELECT started_epoch FROM sessions WHERE sid = ?", (sid,)).fetchone()
+    conn = None
+    row = _safe_interactive(
+        "session age lookup",
+        lambda: get_db().execute("SELECT started_epoch FROM sessions WHERE sid = ?", (sid,)).fetchone(),
+        None,
+        None,
+    )
     if row:
         age_seconds = now_epoch() - row["started_epoch"]
-        has_diary = check_session_has_diary(sid)
+        has_diary = _safe_interactive("diary lookup", lambda: check_session_has_diary(sid), True, None)
 
         # DIARY_OVERDUE: >10 heartbeats OR >30 minutes, without a diary
         if not has_diary and (_hb_count > 10 or age_seconds >= 1800):
@@ -855,6 +942,7 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
     # Guard check reminder: if context_hint mentions code editing and no guard_check this session
     if context_hint and _hint_suggests_code_edit(context_hint):
         try:
+            conn = conn or get_db()
             guard_used = conn.execute(
                 "SELECT COUNT(*) FROM guard_log WHERE session_id = ?", (sid,)
             ).fetchone()[0]
@@ -913,7 +1001,7 @@ def _handle_heartbeat_inner(sid: str, task: str, context_hint: str = '') -> str:
     # adaptive_log row per heartbeat. Wrapped in best-effort try/except so
     # a failure here cannot block the heartbeat itself.
     try:
-        if context_hint and len(context_hint.strip()) >= 5:
+        if _env_flag("NEXO_HEARTBEAT_ADAPTIVE_MODE", default=False) and context_hint and len(context_hint.strip()) >= 5:
             from plugins.adaptive_mode import compute_mode
             from cognitive._trust import detect_sentiment
             sentiment = detect_sentiment(context_hint)
@@ -1257,7 +1345,9 @@ def _hint_suggests_correction(hint: str, *, correction_detector=None) -> bool:
     text = (hint or "").strip()
     if not text:
         return False
-    detector = correction_detector if correction_detector is not None else _detect_correction_semantic
+    detector = correction_detector if correction_detector is not None else (
+        _detect_correction_semantic if _env_flag("NEXO_HEARTBEAT_SEMANTIC_DETECTORS", default=False) else None
+    )
     if detector is not None:
         try:
             if bool(detector(text)):