nexo-brain 5.0.3 → 5.0.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.0.3",
+  "version": "5.0.4",
   "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

@@ -87,6 +87,12 @@ Versions `3.1.7` through `3.2.0` close the recent-memory gap:
 - when even that misses, NEXO now exposes raw transcript fallback tools for Claude Code and Codex session stores
 - NEXO can now inspect itself through a live system catalog derived from canonical sources instead of relying only on stale docs or operator memory
 
+Version `5.0.4` tightens the local runtime bridge and trims false-positive doctor noise:
+
+- vendorable `nexo_helper.py` now resolves `NEXO_HOME` and the `nexo` CLI path robustly, so personal scripts and subprocess flows stop depending on a lucky PATH
+- doctor no longer degrades because of advisory-only self-audit warnings or a single missing usage-telemetry row
+- managed Claude Code and Codex bootstraps now force an immediate first answer after simple email/diary/reminder/followup reads instead of feeling hung while chaining extra lookups
+
 Version `5.0.3` closes the next post-5.0 runtime gap:
 
 - `nexo chat` now boots Claude Code and Codex with an explicit NEXO startup prompt instead of opening cold or leaking the target path as a fake prompt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.0.3",
+  "version": "5.0.4",
   "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/doctor/providers/deep.py

@@ -65,9 +65,6 @@ def check_self_audit_summary() -> DoctorCheck:
         if error_count > 0:
             status = "critical"
             severity = "error"
-        elif warn_count > 0:
-            status = "degraded"
-            severity = "warn"
         else:
             status = "healthy"
             severity = "info"

package/src/doctor/providers/runtime.py

@@ -2491,7 +2491,7 @@ def check_protocol_compliance() -> DoctorCheck:
                             if str(row["opened_at"] or "") >= first_cortex_eval_at
                         ]
                     decision_ok = [row for row in decision_eligible if row["task_id"] in covered_tasks]
-                    decision_metric_ready = len(decision_eligible) >= 3
+                    decision_metric_ready = bool(first_cortex_eval_at) and len(decision_eligible) >= 3
 
                     score_parts = []
                     if verify_required:
@@ -2922,6 +2922,7 @@ def check_automation_telemetry(days: int = 7) -> DoctorCheck:
     pricing_gaps = int((row["pricing_gaps"] if row else 0) or 0)
     usage_denominator = successful_runs or total_runs
     cost_denominator = successful_runs or total_runs
+    missing_usage_runs = max(0, usage_denominator - usage_runs) if usage_denominator else 0
     usage_coverage = round((usage_runs / usage_denominator) * 100, 1) if usage_denominator else 100.0
     cost_coverage = round((cost_runs / cost_denominator) * 100, 1) if cost_denominator else 100.0
     evidence = [
@@ -2933,6 +2934,8 @@ def check_automation_telemetry(days: int = 7) -> DoctorCheck:
         f"cost_coverage={cost_coverage}%",
         f"pricing_gaps={pricing_gaps}",
     ]
+    if missing_usage_runs:
+        evidence.append(f"missing_usage_runs={missing_usage_runs}")
     backends = str((row["backends"] if row else "") or "").strip()
     if backends:
         evidence.append(f"backends={backends}")
@@ -2940,7 +2943,7 @@ def check_automation_telemetry(days: int = 7) -> DoctorCheck:
     status = "healthy"
     severity = "info"
     repair_plan: list[str] = []
-    if usage_coverage < 100.0:
+    if usage_coverage < 100.0 and missing_usage_runs > 1:
         status = "degraded"
         severity = "warn"
         repair_plan.append("Restore backend usage parsing so automation runs always emit token telemetry")

package/templates/CLAUDE.md.template

@@ -32,6 +32,8 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 - After the first relevant tool or artifact result, reply with the answer immediately instead of silently chaining more investigation.
 - Only continue into deeper investigation before the first visible answer if the user explicitly asked for a deep investigation or the situation is urgent/high-risk.
 - For single-artifact asks (email, message, diary item, reminder, prior fact), retrieve the artifact, summarize it, then decide whether further action is needed.
+- For single-artifact asks, the default cap before the first visible answer is one lookup plus one detail read. Do not keep chaining tools before answering unless the user explicitly asked for more depth.
+- After `nexo_email_read`, `nexo_session_diary_read`, `nexo_reminders`, `nexo_followups`, or equivalent single-artifact retrieval, answer immediately. Do not launch another search, another read, or background analysis before the first user-visible answer unless the user explicitly asked for it.
 
 <!-- nexo:start:profile -->
 ## User Profile

package/templates/CODEX.AGENTS.md.template

@@ -29,6 +29,8 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 - After the first relevant tool or artifact result, answer immediately instead of silently chaining more investigation.
 - Only keep investigating before the first visible answer if the user explicitly requested deep investigation or the situation is urgent/high-risk.
 - For single-artifact asks (email, message, diary item, reminder, prior fact), retrieve it, summarize it, then decide if more work is needed.
+- For single-artifact asks, the default cap before the first visible answer is one lookup plus one detail read. Do not keep chaining tools before answering unless the user explicitly asked for more depth.
+- After `nexo_email_read`, `nexo_session_diary_read`, `nexo_reminders`, `nexo_followups`, or equivalent single-artifact retrieval, answer immediately. Do not launch another search, another read, or background analysis before the first visible answer unless the user explicitly asked for it.
 
 ## Codex Runtime Notes
 - Codex does not provide Claude Code hooks, so protocol discipline must be explicit.

package/templates/nexo_helper.py

@@ -10,12 +10,34 @@ from __future__ import annotations
 
 import json
 import os
+import shutil
 import subprocess
 import sys
 from pathlib import Path
 
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+def _detect_nexo_home() -> Path:
+    env_home = os.environ.get("NEXO_HOME", "").strip()
+    if env_home:
+        return Path(env_home).expanduser()
+
+    helper_path = Path(__file__).resolve()
+    inferred_home = helper_path.parent.parent
+    if (
+        helper_path.parent.name == "templates"
+        and (inferred_home / "scripts").is_dir()
+        and (inferred_home / "config").is_dir()
+    ):
+        return inferred_home
+
+    claude_home = Path.home() / "claude"
+    if claude_home.is_dir():
+        return claude_home
+
+    return Path.home() / ".nexo"
+
+
+NEXO_HOME = _detect_nexo_home()
 DEFAULT_ALLOWED_TOOLS = "Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*"
 DEFAULT_NEXO_TIMEOUT_SECONDS = max(15, int(os.environ.get("NEXO_HELPER_TIMEOUT", "90")))
 
@@ -49,16 +71,44 @@ def _load_bootstrap_prompt() -> str:
         return ""
 
 
+def _resolve_nexo_cli() -> str:
+    candidates = []
+
+    env_cli = os.environ.get("NEXO_BIN", "").strip()
+    if env_cli:
+        candidates.append(Path(env_cli).expanduser())
+
+    candidates.extend(
+        [
+            NEXO_HOME / "bin" / "nexo",
+            Path.home() / ".local" / "bin" / "nexo",
+            Path.home() / "bin" / "nexo",
+        ]
+    )
+
+    for candidate in candidates:
+        try:
+            if candidate.is_file() and os.access(candidate, os.X_OK):
+                return str(candidate)
+        except OSError:
+            continue
+
+    return shutil.which("nexo") or "nexo"
+
+
 def run_nexo(args: list[str]) -> str:
     """Run a nexo CLI command and return stdout.
 
     Raises RuntimeError on non-zero exit.
     """
+    env = os.environ.copy()
+    env.setdefault("NEXO_HOME", str(NEXO_HOME))
     result = subprocess.run(
-        ["nexo", *args],
+        [_resolve_nexo_cli(), *args],
         capture_output=True,
         text=True,
         timeout=DEFAULT_NEXO_TIMEOUT_SECONDS,
+        env=env,
     )
     if result.returncode != 0:
         raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"nexo exited {result.returncode}")
@@ -83,12 +133,72 @@ def call_tool_json(name: str, payload: dict | None = None) -> dict:
     return json.loads(out)
 
 
+def _extract_json_object(text: str) -> dict:
+    raw = str(text or "").strip()
+    if not raw:
+        raise RuntimeError("Automation backend returned empty output.")
+
+    if raw.startswith("```"):
+        lines = raw.splitlines()
+        if len(lines) >= 2:
+            end = len(lines)
+            for i in range(len(lines) - 1, 0, -1):
+                if lines[i].strip() == "```":
+                    end = i
+                    break
+            raw = "\n".join(lines[1:end]).strip()
+
+    try:
+        parsed = json.loads(raw)
+        if isinstance(parsed, dict):
+            return parsed
+    except Exception:
+        pass
+
+    start = raw.find("{")
+    if start < 0:
+        raise RuntimeError("Automation backend did not return a JSON object.")
+
+    depth = 0
+    in_string = False
+    escape = False
+    for idx in range(start, len(raw)):
+        ch = raw[idx]
+        if in_string:
+            if escape:
+                escape = False
+            elif ch == "\\":
+                escape = True
+            elif ch == '"':
+                in_string = False
+            continue
+
+        if ch == '"':
+            in_string = True
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                candidate = raw[start : idx + 1]
+                try:
+                    parsed = json.loads(candidate)
+                except Exception as exc:
+                    raise RuntimeError(f"Automation backend returned invalid JSON object: {exc}") from exc
+                if isinstance(parsed, dict):
+                    return parsed
+                break
+
+    raise RuntimeError("Automation backend did not return a parseable JSON object.")
+
+
 def run_automation_text(
     prompt: str,
     *,
     model: str = "",
     reasoning_effort: str = "",
     cwd: str = "",
+    timeout: int | None = None,
     allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
     append_system_prompt: str = "",
     include_bootstrap: bool = True,
@@ -130,7 +240,58 @@ def run_automation_text(
         capture_output=True,
         text=True,
         env=env,
+        timeout=(int(timeout) if timeout else None),
     )
     if result.returncode != 0:
         raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"automation backend exited {result.returncode}")
     return result.stdout
+
+
+def run_automation_json(
+    prompt: str,
+    *,
+    model: str = "",
+    reasoning_effort: str = "",
+    cwd: str = "",
+    timeout: int | None = None,
+    allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
+    append_system_prompt: str = "",
+    include_bootstrap: bool = True,
+) -> dict:
+    """Run the configured backend and return a parsed JSON object."""
+    runner = NEXO_HOME / "scripts" / "nexo-agent-run.py"
+    if not runner.exists():
+        raise RuntimeError(f"Automation runner not found: {runner}")
+
+    cmd = [sys.executable, str(runner), "--prompt", prompt, "--output-format", "json"]
+    if model:
+        cmd.extend(["--model", model])
+    if reasoning_effort:
+        cmd.extend(["--reasoning-effort", reasoning_effort])
+    if cwd:
+        cmd.extend(["--cwd", cwd])
+    merged_system_prompt = []
+    if include_bootstrap:
+        bootstrap = _load_bootstrap_prompt()
+        if bootstrap:
+            merged_system_prompt.append(bootstrap)
+    if append_system_prompt:
+        merged_system_prompt.append(append_system_prompt)
+    if merged_system_prompt:
+        cmd.extend(["--append-system-prompt", "\n\n".join(merged_system_prompt)])
+    if allowed_tools:
+        cmd.extend(["--allowed-tools", allowed_tools])
+
+    env = os.environ.copy()
+    env.setdefault("NEXO_HOME", str(NEXO_HOME))
+    env.setdefault("NEXO_CODE", env.get("NEXO_CODE", str(NEXO_HOME)))
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=(int(timeout) if timeout else None),
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"automation backend exited {result.returncode}")
+    return _extract_json_object(result.stdout)