nexo-brain 5.4.8 → 5.5.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.4.8",
+  "version": "5.5.0",
   "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 `5.4.8` is the current packaged-runtime line: tool-enforcement-map v2.0 — multi-dimensional enforcement with dependency chains, internal_calls, provides/requires, and 3-level enforcement (must/should/none).
+Version `5.5.0` is the current packaged-runtime line: headless Protocol Enforcer — all crons get enforcement rules automatically.
 
 Previously in `5.4.6`: runtime dependency management in `nexo update` + daily auto-update cron.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.4.8",
+  "version": "5.5.0",
   "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",
@@ -61,7 +61,11 @@
     "postinstall": "node bin/postinstall.js"
   },
   "runtimeDependencies": [
-    {"name": "@anthropic-ai/claude-code", "type": "npm-global", "optional": false}
+    {
+      "name": "@anthropic-ai/claude-code",
+      "type": "npm-global",
+      "optional": false
+    }
   ],
   "engines": {
     "node": ">=18"

package/src/agent_runner.py

@@ -56,7 +56,6 @@ class TerminalClientUnavailableError(AgentRunnerError):
 class AutomationBackendUnavailableError(AgentRunnerError):
     """Raised when the configured automation backend is unavailable."""
 
-
 def _canonical_pricing_model(model: str) -> str:
     lowered = str(model or "").strip().lower()
     lowered = lowered.split("[", 1)[0]
@@ -533,6 +532,63 @@ def _build_codex_prompt(
     return prompt
 
 
+def _build_enforcement_system_prompt() -> str:
+    """Build a system prompt fragment from tool-enforcement-map.json for headless sessions.
+
+    Reads the map and generates concise enforcement rules that the model must follow.
+    Only includes 'must' and 'should' level tools — 'none' tools are omitted.
+    """
+    map_path = NEXO_HOME / "tool-enforcement-map.json"
+    if not map_path.exists():
+        for candidate in [
+            Path(__file__).parent.parent / "tool-enforcement-map.json",
+        ]:
+            if candidate.exists():
+                map_path = candidate
+                break
+        else:
+            return ""
+    try:
+        data = json.loads(map_path.read_text())
+    except Exception:
+        return ""
+
+    lines = ["[PROTOCOL ENFORCEMENT — these rules are mandatory]"]
+    must_rules = []
+    should_rules = []
+
+    for tool_name, tool in data.get("tools", {}).items():
+        enf = tool.get("enforcement", {})
+        level = enf.get("level", "none")
+        if level == "none":
+            continue
+        rules = enf.get("rules", [])
+        rule_descs = [r.get("description", "") for r in rules if r.get("description")]
+        notes = enf.get("notes", "")
+        if rule_descs:
+            desc = f"{tool_name}: {'; '.join(rule_descs)}"
+        elif notes:
+            desc = f"{tool_name}: {notes[:120]}"
+        else:
+            rule_types = [r.get("type", "") for r in rules]
+            desc = f"{tool_name} ({', '.join(rule_types)})" if rule_types else tool_name
+        if level == "must":
+            must_rules.append(desc)
+        elif level == "should":
+            should_rules.append(desc)
+
+    if must_rules:
+        lines.append("MUST (violation creates protocol debt):")
+        for r in must_rules:
+            lines.append(f"  - {r}")
+    if should_rules:
+        lines.append("SHOULD (recommended, check if relevant):")
+        for r in should_rules:
+            lines.append(f"  - {r}")
+
+    return "\n".join(lines) if (must_rules or should_rules) else ""
+
+
 def run_automation_prompt(
     prompt: str,
     *,
@@ -562,6 +618,13 @@ def run_automation_prompt(
             reasoning_effort = profile["reasoning_effort"]
     selected_backend = _resolve_available_backend(selected_backend, preferences=prefs)
 
+    enforcement_fragment = _build_enforcement_system_prompt()
+    if enforcement_fragment:
+        if append_system_prompt:
+            append_system_prompt = append_system_prompt + "\n\n" + enforcement_fragment
+        else:
+            append_system_prompt = enforcement_fragment
+
     cwd_path = Path(cwd).expanduser().resolve() if cwd else Path.cwd()
     run_env = _headless_env(env)
     extra_args = list(extra_args or [])
@@ -599,14 +662,24 @@ def run_automation_prompt(
         if allowed_tools:
             cmd.extend(["--allowedTools", allowed_tools])
         cmd.extend(extra_args)
-        result = subprocess.run(
-            cmd,
-            cwd=str(cwd_path),
-            capture_output=True,
-            text=True,
-            timeout=timeout,
-            env=run_env,
-        )
+        try:
+            from enforcement_engine import run_with_enforcement
+            result = run_with_enforcement(
+                cmd,
+                prompt=prompt,
+                cwd=str(cwd_path),
+                env=run_env,
+                timeout=timeout,
+            )
+        except ImportError:
+            result = subprocess.run(
+                cmd,
+                cwd=str(cwd_path),
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                env=run_env,
+            )
         final_stdout, telemetry = _extract_claude_telemetry(
             result.stdout or "",
             requested_output_format=requested_output_format,

package/src/enforcement_engine.py

@@ -0,0 +1,348 @@
+"""Headless Protocol Enforcement Engine for NEXO Brain.
+
+Wraps a Claude Code subprocess with stream-json I/O, monitors tool calls,
+and injects enforcement prompts when rules from tool-enforcement-map.json
+are violated. Python equivalent of Desktop's enforcement-engine.js.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import threading
+import time
+from pathlib import Path
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+MAP_FILENAME = "tool-enforcement-map.json"
+
+
+def _load_map() -> dict | None:
+    for candidate in [
+        NEXO_HOME / MAP_FILENAME,
+        NEXO_HOME / "brain" / MAP_FILENAME,
+        Path(__file__).parent.parent / MAP_FILENAME,
+    ]:
+        if candidate.exists():
+            try:
+                return json.loads(candidate.read_text(encoding="utf-8"))
+            except Exception:
+                continue
+    return None
+
+
+def _normalize(name: str) -> str:
+    return name.replace("mcp__nexo__", "")
+
+
+class HeadlessEnforcer:
+    """Monitor a Claude Code stream-json process and enforce protocol rules."""
+
+    def __init__(self):
+        self.map = _load_map()
+        self.tools_called: set[str] = set()
+        self.tool_call_count = 0
+        self.user_message_count = 0
+        self.tool_timestamps: dict[str, float] = {}
+        self.msg_since_tool: dict[str, int] = {}
+        self.injection_queue: list[dict] = []
+        self._started_at = time.time()
+
+        # Build indexes from map
+        self._on_start: list[dict] = []
+        self._on_end: list[dict] = []
+        self._periodic_msg: list[dict] = []
+        self._periodic_time: list[dict] = []
+        self._after_tool: dict[str, list[dict]] = {}
+
+        if self.map:
+            self._build_indexes()
+
+    def _build_indexes(self):
+        for tool_name, tool_def in self.map.get("tools", {}).items():
+            enf = tool_def.get("enforcement")
+            if not enf or enf.get("level") == "none":
+                continue
+            for rule in enf.get("rules", []):
+                rtype = rule.get("type", "")
+                entry = {"tool": tool_name, "rule": rule, "enf": enf}
+                if rtype == "on_session_start":
+                    self._on_start.append(entry)
+                elif rtype == "on_session_end":
+                    self._on_end.append(entry)
+                elif rtype == "periodic_by_messages":
+                    self._periodic_msg.append(entry)
+                elif rtype == "periodic_by_time":
+                    self._periodic_time.append(entry)
+                elif rtype == "after_tool":
+                    for wt in rule.get("watch_tools", []):
+                        self._after_tool.setdefault(wt, []).append(entry)
+
+            # triggers_after chains
+            for triggered in enf.get("triggers_after", []):
+                self._after_tool.setdefault(tool_name, []).append({
+                    "tool": triggered,
+                    "rule": {"type": "after_tool"},
+                    "enf": self.map["tools"].get(triggered, {}).get("enforcement", {}),
+                })
+
+    def on_tool_call(self, raw_name: str):
+        name = _normalize(raw_name)
+        self.tool_call_count += 1
+        self.tools_called.add(name)
+        self.tool_timestamps[name] = time.time()
+        self.msg_since_tool[name] = 0
+
+        # Check after_tool rules
+        for entry in self._after_tool.get(name, []):
+            target = entry["tool"]
+            if target not in self.tools_called:
+                prompt = entry["enf"].get("inject_prompt", "")
+                if prompt:
+                    self._enqueue(prompt, f"after:{name}->{target}")
+
+    def check_periodic(self):
+        """Called periodically to check time-based and message-based rules."""
+        # on_session_start
+        for entry in self._on_start:
+            tool = entry["tool"]
+            threshold = entry["rule"].get("threshold", 2)
+            if tool not in self.tools_called and self.tool_call_count >= threshold:
+                prompt = entry["enf"].get("inject_prompt", "")
+                if prompt:
+                    self._enqueue(prompt, f"start:{tool}")
+
+        # periodic_by_messages
+        for entry in self._periodic_msg:
+            tool = entry["tool"]
+            threshold = entry["rule"].get("threshold", 3)
+            count = self.msg_since_tool.get(tool, self.user_message_count)
+            if count >= threshold:
+                prompt = entry["enf"].get("inject_prompt", "")
+                if prompt:
+                    self._enqueue(prompt, f"periodic_msg:{tool}")
+
+        # periodic_by_time
+        for entry in self._periodic_time:
+            tool = entry["tool"]
+            threshold_min = entry["rule"].get("threshold", 15)
+            last = self.tool_timestamps.get(tool, self._started_at)
+            elapsed_min = (time.time() - last) / 60
+            if elapsed_min >= threshold_min:
+                prompt = entry["enf"].get("inject_prompt", "")
+                if prompt:
+                    self._enqueue(prompt, f"periodic_time:{tool}")
+
+    def get_end_prompts(self) -> list[str]:
+        prompts = []
+        for entry in self._on_end:
+            if entry["enf"].get("level") == "must":
+                p = entry["enf"].get("session_end_inject_prompt") or entry["enf"].get("inject_prompt", "")
+                if p:
+                    prompts.append(p)
+        return prompts
+
+    def flush(self) -> dict | None:
+        if not self.injection_queue:
+            return None
+        return self.injection_queue.pop(0)
+
+    def _enqueue(self, prompt: str, tag: str):
+        if any(q["tag"] == tag for q in self.injection_queue):
+            return
+        tool = tag.split(":")[-1].split("->")[-1]
+        if tool in self.tools_called and not tag.startswith("periodic_"):
+            return
+        self.injection_queue.append({"prompt": prompt, "tag": tag, "at": time.time()})
+
+
+def run_with_enforcement(
+    cmd: list[str],
+    *,
+    prompt: str,
+    cwd: str = "",
+    env: dict | None = None,
+    timeout: int = 300,
+) -> subprocess.CompletedProcess:
+    """Run a Claude Code process with real-time enforcement monitoring.
+
+    Uses stream-json mode instead of -p mode. Monitors stdout for tool calls,
+    injects enforcement prompts via stdin when rules are violated.
+    """
+    enforcer = HeadlessEnforcer()
+    if not enforcer.map:
+        # No map available — fall back to simple subprocess.run
+        return subprocess.run(cmd, cwd=cwd or None, capture_output=True, text=True,
+                              timeout=timeout, env=env)
+
+    # Replace -p with stream-json mode
+    stream_cmd = []
+    skip_next = False
+    for i, arg in enumerate(cmd):
+        if skip_next:
+            skip_next = False
+            continue
+        if arg == "-p":
+            skip_next = True  # Skip the prompt argument
+            continue
+        if arg == "--output-format":
+            skip_next = True  # Skip output format
+            continue
+        stream_cmd.append(arg)
+
+    stream_cmd.extend([
+        "--print",
+        "--input-format", "stream-json",
+        "--output-format", "stream-json",
+        "--verbose",
+    ])
+
+    proc = subprocess.Popen(
+        stream_cmd,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        cwd=cwd or None,
+        env=env,
+        text=True,
+    )
+
+    # Send initial user message
+    initial_msg = json.dumps({
+        "type": "user",
+        "message": {"role": "user", "content": [{"type": "text", "text": prompt}]}
+    })
+    proc.stdin.write(initial_msg + "\n")
+    proc.stdin.flush()
+
+    collected_text = []
+    stderr_lines = []
+    start_time = time.time()
+    waiting_for_injection_response = False
+
+    def _inject(text: str):
+        nonlocal waiting_for_injection_response
+        msg = json.dumps({
+            "type": "user",
+            "message": {"role": "user", "content": [{"type": "text", "text": text}]}
+        })
+        try:
+            proc.stdin.write(msg + "\n")
+            proc.stdin.flush()
+            waiting_for_injection_response = True
+        except Exception:
+            pass
+
+    def _read_stderr():
+        try:
+            for line in proc.stderr:
+                stderr_lines.append(line)
+        except Exception:
+            pass
+
+    stderr_thread = threading.Thread(target=_read_stderr, daemon=True)
+    stderr_thread.start()
+
+    # Periodic check timer
+    last_periodic_check = time.time()
+
+    try:
+        for raw_line in proc.stdout:
+            line = raw_line.strip()
+            if not line:
+                continue
+
+            # Check timeout
+            if time.time() - start_time > timeout:
+                proc.kill()
+                break
+
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            event_type = event.get("type", "")
+
+            # Detect tool use
+            if event_type == "assistant" and event.get("message", {}).get("content"):
+                for block in event["message"]["content"]:
+                    if block.get("type") == "tool_use":
+                        enforcer.on_tool_call(block.get("name", ""))
+            elif event_type == "content_block_start":
+                cb = event.get("content_block", {})
+                if cb.get("type") == "tool_use":
+                    enforcer.on_tool_call(cb.get("name", ""))
+
+            # Collect assistant text
+            if event_type == "assistant" and not waiting_for_injection_response:
+                msg = event.get("message", {})
+                for block in msg.get("content", []):
+                    if block.get("type") == "text":
+                        collected_text.append(block["text"])
+
+            # Detect turn end (result event with stop_reason)
+            if event_type == "result":
+                if waiting_for_injection_response:
+                    waiting_for_injection_response = False
+                    # After injection response, check for more injections
+                    item = enforcer.flush()
+                    if item:
+                        _inject(item["prompt"])
+                    continue
+
+                # Normal turn end — check for pending enforcements
+                enforcer.check_periodic()
+                item = enforcer.flush()
+                if item:
+                    _inject(item["prompt"])
+                else:
+                    break  # No more injections, we're done
+
+            # Periodic check every 30 seconds
+            if time.time() - last_periodic_check > 30:
+                enforcer.check_periodic()
+                last_periodic_check = time.time()
+
+    except Exception:
+        pass
+    finally:
+        # End-of-session enforcement: inject diary + stop
+        end_prompts = enforcer.get_end_prompts()
+        for ep in end_prompts:
+            try:
+                _inject(ep)
+                # Wait briefly for response
+                deadline = time.time() + 15
+                for raw_line in proc.stdout:
+                    if time.time() > deadline:
+                        break
+                    line = raw_line.strip()
+                    if not line:
+                        continue
+                    try:
+                        event = json.loads(line)
+                        if event.get("type") == "result":
+                            break
+                    except json.JSONDecodeError:
+                        continue
+            except Exception:
+                break
+
+        try:
+            proc.stdin.close()
+        except Exception:
+            pass
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+
+    stderr_thread.join(timeout=2)
+    final_text = "\n".join(collected_text)
+    final_stderr = "".join(stderr_lines)
+
+    return subprocess.CompletedProcess(
+        stream_cmd, proc.returncode or 0, final_text, final_stderr
+    )