nexo-brain 5.3.28 → 5.4.0

package/src/events_bus.py

@@ -0,0 +1,155 @@
+"""Runtime events bus — append-only NDJSON stream at ~/.nexo/runtime/events.ndjson.
+
+NEXO Brain writes events that external UIs (NEXO Desktop, mobile, web)
+can tail for real-time attention signals, proactive messages, health
+alerts, and general notifications.
+
+Contract:
+  - One JSON object per line. No multi-line JSON.
+  - Monotonic `id` (integer) and `ts` (unix seconds, float).
+  - Stable event envelope keys: id, ts, type, priority, text, reason,
+    source, extra. Unknown keys are preserved.
+  - File is append-only. Rotation happens at 5 MB: current file is
+    renamed to events-<ts>.ndjson and a fresh empty file is created.
+  - Readers tail the current file; rotation is transparent because the
+    file is reopened after rename detection.
+
+Event types (stable):
+  attention_required  — user should look at something
+  proactive_message   — Brain wants to initiate dialogue
+  followup_alert      — overdue or urgent followup
+  health_alert        — a core system is degraded
+  info                — general update, no attention needed
+
+Priorities: "low" | "normal" | "high" | "urgent"
+"""
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+EVENT_TYPES = {
+    "attention_required",
+    "proactive_message",
+    "followup_alert",
+    "health_alert",
+    "info",
+}
+PRIORITIES = {"low", "normal", "high", "urgent"}
+ROTATION_BYTES = 5 * 1024 * 1024  # 5 MB
+
+
+def _nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+
+
+def events_path() -> Path:
+    return _nexo_home() / "runtime" / "events.ndjson"
+
+
+def _next_id(path: Path) -> int:
+    """Return the next monotonic id by reading the last line's id, or 1."""
+    if not path.is_file():
+        return 1
+    try:
+        # Read last 4 KB — more than enough for the tail line
+        with path.open("rb") as fh:
+            fh.seek(0, os.SEEK_END)
+            size = fh.tell()
+            fh.seek(max(0, size - 4096))
+            tail = fh.read().decode("utf-8", errors="ignore")
+        lines = [ln for ln in tail.splitlines() if ln.strip()]
+        if not lines:
+            return 1
+        last = json.loads(lines[-1])
+        return int(last.get("id", 0)) + 1
+    except Exception:
+        return int(time.time())
+
+
+def _rotate_if_needed(path: Path) -> None:
+    try:
+        if path.is_file() and path.stat().st_size > ROTATION_BYTES:
+            stamp = int(time.time())
+            rotated = path.with_name(f"events-{stamp}.ndjson")
+            path.rename(rotated)
+    except Exception:
+        # Rotation failure is non-fatal; worst case the file grows
+        pass
+
+
+def emit(
+    event_type: str,
+    *,
+    text: str = "",
+    reason: str = "",
+    priority: str = "normal",
+    source: str = "nexo-brain",
+    extra: dict[str, Any] | None = None,
+) -> dict:
+    """Append a new event to the bus. Returns the full event dict."""
+    if event_type not in EVENT_TYPES:
+        raise ValueError(f"unknown event_type: {event_type}")
+    if priority not in PRIORITIES:
+        raise ValueError(f"unknown priority: {priority}")
+
+    path = events_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    _rotate_if_needed(path)
+
+    event = {
+        "id": _next_id(path),
+        "ts": time.time(),
+        "type": event_type,
+        "priority": priority,
+        "text": text,
+        "reason": reason,
+        "source": source,
+        "extra": extra or {},
+    }
+
+    line = json.dumps(event, ensure_ascii=False) + "\n"
+    # fcntl flock for cross-process safety on macOS/Linux
+    with path.open("a", encoding="utf-8") as fh:
+        try:
+            fcntl.flock(fh, fcntl.LOCK_EX)
+            fh.write(line)
+            fh.flush()
+        finally:
+            try:
+                fcntl.flock(fh, fcntl.LOCK_UN)
+            except Exception:
+                pass
+
+    return event
+
+
+def tail(lines: int = 50, since_id: int | None = None) -> list[dict]:
+    """Return the most recent events, newest last. Optionally filter by id."""
+    path = events_path()
+    if not path.is_file():
+        return []
+    try:
+        with path.open("r", encoding="utf-8", errors="ignore") as fh:
+            raw = fh.readlines()
+    except Exception:
+        return []
+
+    events: list[dict] = []
+    for ln in raw[-max(lines, 1) * 4:]:  # generous buffer for malformed lines
+        ln = ln.strip()
+        if not ln:
+            continue
+        try:
+            evt = json.loads(ln)
+        except Exception:
+            continue
+        if since_id is not None and int(evt.get("id", 0)) <= since_id:
+            continue
+        events.append(evt)
+
+    return events[-lines:]

package/src/health_check.py

@@ -0,0 +1,195 @@
+"""Health check — one-shot snapshot of NEXO Brain subsystems.
+
+Output is stable JSON consumable by any UI or monitoring tool.
+No side effects, no network, no mutation.
+
+Subsystems reported:
+  - runtime     : NEXO_HOME exists, version.json readable, version string
+  - database    : SQLite reachable, integrity check, basic row counts
+  - crons       : count of active personal LaunchAgents (macOS) or unknown
+  - mcp         : Claude Code MCP config present and mentions nexo-brain
+  - errors      : count of recent errors in ~/.nexo/operations/*.log (24h)
+  - events      : count of events emitted in last 24h
+
+Top-level `status` is "ok" | "degraded" | "error".
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+
+def _nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+
+
+def _check_runtime() -> dict:
+    home = _nexo_home()
+    ver_file = home / "version.json"
+    out: dict[str, Any] = {"nexo_home": str(home), "exists": home.is_dir()}
+    if ver_file.is_file():
+        try:
+            payload = json.loads(ver_file.read_text())
+            out["version"] = payload.get("version", "unknown")
+        except Exception as exc:
+            out["version"] = "unreadable"
+            out["error"] = str(exc)
+    else:
+        out["version"] = "missing"
+    out["status"] = "ok" if out["exists"] and out.get("version") not in ("missing", "unreadable") else "degraded"
+    return out
+
+
+def _check_database() -> dict:
+    db_path = _nexo_home() / "data" / "nexo.db"
+    out: dict[str, Any] = {"path": str(db_path), "exists": db_path.is_file()}
+    if not out["exists"]:
+        out["status"] = "error"
+        return out
+    try:
+        conn = sqlite3.connect(str(db_path), timeout=2.0)
+        try:
+            cur = conn.execute("PRAGMA integrity_check")
+            row = cur.fetchone()
+            out["integrity"] = row[0] if row else "unknown"
+        finally:
+            conn.close()
+        out["status"] = "ok" if out["integrity"] == "ok" else "degraded"
+    except Exception as exc:
+        out["status"] = "error"
+        out["error"] = str(exc)
+    return out
+
+
+def _check_crons() -> dict:
+    out: dict[str, Any] = {}
+    # macOS LaunchAgents
+    agents_dir = Path.home() / "Library" / "LaunchAgents"
+    if agents_dir.is_dir():
+        try:
+            plists = [p for p in agents_dir.glob("com.nexo.*.plist")]
+            out["launch_agents"] = len(plists)
+            out["platform"] = "macos"
+        except Exception as exc:
+            out["error"] = str(exc)
+    else:
+        out["platform"] = "unknown"
+    out["status"] = "ok"
+    return out
+
+
+def _check_mcp() -> dict:
+    out: dict[str, Any] = {}
+    candidates = [
+        Path.home() / ".claude.json",
+        Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+    ]
+    found = []
+    for path in candidates:
+        if not path.is_file():
+            continue
+        try:
+            text = path.read_text(errors="ignore")
+        except Exception:
+            continue
+        if "nexo" in text.lower():
+            found.append(str(path))
+    out["configs_with_nexo"] = found
+    out["status"] = "ok" if found else "degraded"
+    if not found:
+        out["reason"] = "no client config mentions nexo-brain"
+    return out
+
+
+def _check_errors(hours: int = 24) -> dict:
+    ops_dir = _nexo_home() / "operations"
+    out: dict[str, Any] = {"dir": str(ops_dir)}
+    if not ops_dir.is_dir():
+        out["recent_errors"] = 0
+        out["status"] = "ok"
+        return out
+
+    cutoff = time.time() - hours * 3600
+    recent = 0
+    sample: list[str] = []
+    error_re = re.compile(r"(?i)\b(error|traceback|exception|fail(ed)?)\b")
+
+    for log in ops_dir.glob("*.log"):
+        try:
+            if log.stat().st_mtime < cutoff:
+                continue
+            with log.open("r", errors="ignore") as fh:
+                for line in fh:
+                    if error_re.search(line):
+                        recent += 1
+                        if len(sample) < 5:
+                            sample.append(line.strip()[:200])
+        except Exception:
+            continue
+
+    out["recent_errors"] = recent
+    out["sample"] = sample
+    out["status"] = "ok" if recent < 20 else "degraded"
+    return out
+
+
+def _check_events(hours: int = 24) -> dict:
+    events_file = _nexo_home() / "runtime" / "events.ndjson"
+    out: dict[str, Any] = {"path": str(events_file), "exists": events_file.is_file()}
+    if not events_file.is_file():
+        out["recent_events"] = 0
+        out["status"] = "ok"
+        return out
+    cutoff = time.time() - hours * 3600
+    count = 0
+    urgent = 0
+    try:
+        with events_file.open("r", errors="ignore") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    evt = json.loads(line)
+                except Exception:
+                    continue
+                if float(evt.get("ts", 0)) < cutoff:
+                    continue
+                count += 1
+                if evt.get("priority") == "urgent":
+                    urgent += 1
+    except Exception as exc:
+        out["error"] = str(exc)
+    out["recent_events"] = count
+    out["urgent"] = urgent
+    out["status"] = "degraded" if urgent > 0 else "ok"
+    return out
+
+
+def collect() -> dict:
+    """Run every subsystem check and return a unified report."""
+    report: dict[str, Any] = {
+        "ts": time.time(),
+        "subsystems": {
+            "runtime": _check_runtime(),
+            "database": _check_database(),
+            "crons": _check_crons(),
+            "mcp": _check_mcp(),
+            "errors": _check_errors(),
+            "events": _check_events(),
+        },
+    }
+    statuses = [sub.get("status", "unknown") for sub in report["subsystems"].values()]
+    if "error" in statuses:
+        report["status"] = "error"
+    elif "degraded" in statuses:
+        report["status"] = "degraded"
+    else:
+        report["status"] = "ok"
+    return report

package/src/plugin_loader.py

@@ -10,6 +10,7 @@ import time
 
 from db import get_db
 from fastmcp.tools import Tool
+from tree_hygiene import is_duplicate_artifact_name
 
 SERVER_DIR = os.path.dirname(os.path.abspath(__file__))
 PLUGINS_DIR = os.path.join(SERVER_DIR, "plugins")
@@ -47,12 +48,16 @@ def load_all_plugins(mcp) -> int:
     if os.path.isdir(PLUGINS_DIR):
         for f in sorted(os.listdir(PLUGINS_DIR)):
             if f.endswith(".py") and f != "__init__.py":
+                if is_duplicate_artifact_name(os.path.join(PLUGINS_DIR, f)):
+                    continue
                 plugin_map[f] = (PLUGINS_DIR, "repo")
 
     # 2. Personal plugins (override if same filename)
     if os.path.isdir(PERSONAL_PLUGINS_DIR):
         for f in sorted(os.listdir(PERSONAL_PLUGINS_DIR)):
             if f.endswith(".py") and f != "__init__.py":
+                if is_duplicate_artifact_name(os.path.join(PERSONAL_PLUGINS_DIR, f)):
+                    continue
                 source = "personal (override)" if f in plugin_map else "personal"
                 plugin_map[f] = (PERSONAL_PLUGINS_DIR, source)
 

package/src/plugins/update.py

@@ -10,6 +10,7 @@ import time
 from pathlib import Path
 
 from runtime_home import export_resolved_nexo_home
+from tree_hygiene import is_duplicate_artifact_name
 
 # Code root is the parent of plugins/:
 # - source checkout: <repo>/src
@@ -100,7 +101,7 @@ def _refresh_installed_manifest():
         if src_crons.exists():
             dst_crons.mkdir(parents=True, exist_ok=True)
             for f in src_crons.iterdir():
-                if f.is_file():
+                if f.is_file() and not is_duplicate_artifact_name(f):
                     dest = dst_crons / f.name
                     if _paths_match(f, dest):
                         continue
@@ -111,11 +112,11 @@ def _refresh_installed_manifest():
             "generated_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
             "script_names": sorted(
                 f.name for f in (artifact_src / "scripts").iterdir()
-                if f.is_file()
+                if f.is_file() and not is_duplicate_artifact_name(f)
             ) if (artifact_src / "scripts").is_dir() else [],
             "hook_names": sorted(
                 f.name for f in (artifact_src / "hooks").iterdir()
-                if f.is_file()
+                if f.is_file() and not is_duplicate_artifact_name(f)
             ) if (artifact_src / "hooks").is_dir() else [],
         }
         (config_dir / "runtime-core-artifacts.json").write_text(
@@ -368,7 +369,7 @@ def _sync_hooks_to_home():
     hooks_dest.mkdir(parents=True, exist_ok=True)
     synced = 0
     for f in hooks_src.iterdir():
-        if f.is_file() and f.suffix == ".sh":
+        if f.is_file() and f.suffix == ".sh" and not is_duplicate_artifact_name(f):
             dest = hooks_dest / f.name
             if not _paths_match(f, dest):
                 shutil.copy2(str(f), str(dest))

package/src/scripts/nexo-cron-wrapper.sh

@@ -13,6 +13,7 @@ shift
 
 NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
 DB="$NEXO_HOME/data/nexo.db"
+SPOOL_DIR="$NEXO_HOME/operations/cron-spool"
 
 # Unlock macOS Keychain so headless Claude Code can read auth tokens.
 # Claude Code stores its API key in the login keychain which auto-locks.
@@ -21,40 +22,95 @@ if [ -f "$KEYCHAIN_PASS_FILE" ] && [ "$(uname)" = "Darwin" ]; then
     security unlock-keychain -p "$(cat "$KEYCHAIN_PASS_FILE")" ~/Library/Keychains/login.keychain-db 2>/dev/null || true
 fi
 
-# Record start
-RUN_ID=$(sqlite3 "$DB" "INSERT INTO cron_runs (cron_id) VALUES ('$CRON_ID'); SELECT last_insert_rowid();" 2>/dev/null)
-
-if [ -z "$RUN_ID" ]; then
-    # DB not ready — run without tracking
-    exec "$@"
-fi
+START_EPOCH=$(python3 - <<'PY'
+import time
+print(f"{time.time():.6f}")
+PY
+)
+STARTED_AT=$(python3 - <<'PY'
+from datetime import datetime, timezone
+print(datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S"))
+PY
+)
 
 # Run the actual command, capture output
 OUTPUT_FILE=$(mktemp)
+trap 'rm -f "$OUTPUT_FILE"' EXIT
 "$@" > "$OUTPUT_FILE" 2>&1
 EXIT_CODE=$?
+ENDED_AT=$(python3 - <<'PY'
+from datetime import datetime, timezone
+print(datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S"))
+PY
+)
+DURATION_SECS=$(python3 - <<PY
+start = float("$START_EPOCH")
+import time
+print(round(time.time() - start, 1))
+PY
+)
 
 # Extract summary (last meaningful line, max 500 chars)
-SUMMARY=$(tail -5 "$OUTPUT_FILE" | grep -v "^$" | tail -1 | head -c 500 | sed "s/'/''/g")
+SUMMARY=$(tail -5 "$OUTPUT_FILE" | grep -v "^$" | tail -1 | head -c 500)
 
 # Extract error if failed
 ERROR=""
 if [ $EXIT_CODE -ne 0 ]; then
-    ERROR=$(grep -i "error\|exception\|fail\|traceback" "$OUTPUT_FILE" | tail -1 | head -c 500 | sed "s/'/''/g")
+    ERROR=$(grep -i "error\|exception\|fail\|traceback" "$OUTPUT_FILE" | tail -1 | head -c 500)
 fi
 
-# Record end
-sqlite3 "$DB" "
-    UPDATE cron_runs SET
-        ended_at = datetime('now'),
-        exit_code = $EXIT_CODE,
-        summary = '$SUMMARY',
-        error = '$ERROR',
-        duration_secs = ROUND((julianday(datetime('now')) - julianday(started_at)) * 86400, 1)
-    WHERE id = $RUN_ID;
-" 2>/dev/null
-
-# Clean output
-rm -f "$OUTPUT_FILE"
+if ! python3 - "$DB" "$CRON_ID" "$STARTED_AT" "$ENDED_AT" "$EXIT_CODE" "$SUMMARY" "$ERROR" "$DURATION_SECS" <<'PY'
+from __future__ import annotations
+
+import sqlite3
+import sys
+
+db_path, cron_id, started_at, ended_at, exit_code, summary, error, duration_secs = sys.argv[1:]
+conn = sqlite3.connect(db_path)
+try:
+    conn.execute(
+        """
+        INSERT INTO cron_runs (
+            cron_id, started_at, ended_at, exit_code, summary, error, duration_secs
+        ) VALUES (?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            cron_id,
+            started_at,
+            ended_at,
+            int(exit_code),
+            summary,
+            error,
+            float(duration_secs),
+        ),
+    )
+    conn.commit()
+finally:
+    conn.close()
+PY
+then
+    mkdir -p "$SPOOL_DIR"
+    SPOOL_FILE="$SPOOL_DIR/${CRON_ID}-$(date +%Y%m%d-%H%M%S)-$$.json"
+    python3 - "$SPOOL_FILE" "$CRON_ID" "$STARTED_AT" "$ENDED_AT" "$EXIT_CODE" "$SUMMARY" "$ERROR" "$DURATION_SECS" <<'PY'
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+spool_file, cron_id, started_at, ended_at, exit_code, summary, error, duration_secs = sys.argv[1:]
+payload = {
+    "cron_id": cron_id,
+    "started_at": started_at,
+    "ended_at": ended_at,
+    "exit_code": int(exit_code),
+    "summary": summary,
+    "error": error,
+    "duration_secs": float(duration_secs),
+}
+Path(spool_file).write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+PY
+    echo "[nexo-cron-wrapper] DB write failed; spooled run to $SPOOL_FILE" >&2
+fi
 
 exit $EXIT_CODE