nexo-brain 2.7.0 → 3.0.1

package/src/evolution_cycle.py

@@ -390,6 +390,68 @@ Quality over quantity. One strong improvement is better than three weak ones.
 """
 
 
+def build_public_pr_review_prompt(
+    *,
+    pr_number: int,
+    title: str,
+    author: str,
+    url: str,
+    body: str,
+    files: list[str],
+    diff_text: str,
+) -> str:
+    """Prompt for peer-reviewing another public evolution PR.
+
+    This is used only when this machine already has its own Draft PR open, so
+    Evolution can still add value without opening a second PR.
+    """
+
+    rendered_files = "\n".join(f"- {path}" for path in files[:40]) if files else "- (no file list provided)"
+    trimmed_diff = (diff_text or "").strip()
+    if len(trimmed_diff) > 80000:
+        trimmed_diff = trimmed_diff[:80000] + "\n\n[diff truncated by NEXO]"
+
+    return f"""You are NEXO Public Evolution Review.
+
+You are reviewing another opt-in public evolution PR. You must NOT merge, rebase,
+push, or edit the PR. Your only job is to decide whether it deserves an approval
+or whether it should receive a review comment without approval.
+
+STRICT RULES:
+- Review only this PR:
+  - Number: #{pr_number}
+  - Author: {author}
+  - URL: {url}
+- Base the review only on the provided title, body, file list, and diff
+- Do not assume hidden context
+- If confidence is not strong, choose `comment`, not `approve`
+- If the diff is too incomplete, too risky, or too ambiguous, choose `skip`
+- Never suggest merge authority; maintainers decide that later
+- Keep the review concise, technical, and useful
+
+PR TITLE:
+{title}
+
+PR BODY:
+{body or "(empty)"}
+
+FILES CHANGED:
+{rendered_files}
+
+DIFF:
+```diff
+{trimmed_diff or "(empty diff)"}
+```
+
+Return ONLY valid JSON:
+{{
+  "decision": "approve|comment|skip",
+  "summary": "one-line verdict",
+  "body": "the exact markdown text to post as the review body"
+}}
+"""
+
+
 def max_auto_changes(total_evolutions: int) -> int:
     """Progressive trust: 1 for first 4 cycles, 2 for next 4, then 3."""
     if total_evolutions < 4:

package/src/hook_guardrails.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+"""Post-tool guardrails for conditioned file learnings."""
+
+import json
+import sys
+from pathlib import Path
+
+from db import create_protocol_debt, get_db
+from plugins.guard import _load_conditioned_learnings, _normalize_path_token
+
+READ_LIKE_TOOLS = {"Read"}
+WRITE_LIKE_TOOLS = {"Edit", "MultiEdit", "Write"}
+DELETE_LIKE_TOOLS = {"Delete"}
+
+
+def _operation_kind(tool_name: str) -> str:
+    if tool_name in READ_LIKE_TOOLS:
+        return "read"
+    if tool_name in WRITE_LIKE_TOOLS:
+        return "write"
+    if tool_name in DELETE_LIKE_TOOLS:
+        return "delete"
+    return "other"
+
+
+def _normalize_file_path(path: str) -> str:
+    return _normalize_path_token(str(Path(path)))
+
+
+def _extract_touched_files(tool_input) -> list[str]:
+    files: list[str] = []
+    if not isinstance(tool_input, dict):
+        return files
+
+    def add(candidate) -> None:
+        if isinstance(candidate, str) and candidate.strip():
+            files.append(candidate.strip())
+
+    add(tool_input.get("file_path"))
+    add(tool_input.get("path"))
+
+    for key in ("paths", "file_paths", "files"):
+        value = tool_input.get(key)
+        if isinstance(value, list):
+            for item in value:
+                if isinstance(item, str):
+                    add(item)
+                elif isinstance(item, dict):
+                    add(item.get("file_path"))
+                    add(item.get("path"))
+
+    unique: list[str] = []
+    seen = set()
+    for item in files:
+        normalized = _normalize_file_path(item)
+        if normalized and normalized not in seen:
+            seen.add(normalized)
+            unique.append(item)
+    return unique
+
+
+def _resolve_nexo_sid(conn, external_session_id: str) -> str:
+    if not external_session_id.strip():
+        return ""
+    row = conn.execute(
+        """SELECT sid
+           FROM sessions
+           WHERE external_session_id = ? OR claude_session_id = ?
+           ORDER BY last_update_epoch DESC
+           LIMIT 1""",
+        (external_session_id.strip(), external_session_id.strip()),
+    ).fetchone()
+    return str(row["sid"]) if row else ""
+
+
+def _find_open_task_for_file(conn, sid: str, filepath: str) -> dict | None:
+    target = _normalize_file_path(filepath)
+    rows = conn.execute(
+        """SELECT task_id, files, guard_has_blocking
+           FROM protocol_tasks
+           WHERE session_id = ? AND status = 'open'
+           ORDER BY opened_at DESC""",
+        (sid,),
+    ).fetchall()
+    for row in rows:
+        try:
+            files = json.loads(row["files"] or "[]")
+        except Exception:
+            files = []
+        for item in files if isinstance(files, list) else []:
+            if _normalize_file_path(str(item)) == target:
+                return dict(row)
+    return None
+
+
+def _find_open_debt(conn, *, session_id: str, task_id: str, debt_type: str, file_token: str) -> dict | None:
+    row = conn.execute(
+        """SELECT *
+           FROM protocol_debt
+           WHERE status = 'open'
+             AND session_id = ?
+             AND task_id = ?
+             AND debt_type = ?
+             AND INSTR(evidence, ?) > 0
+           ORDER BY id DESC
+           LIMIT 1""",
+        (session_id, task_id, debt_type, file_token),
+    ).fetchone()
+    return dict(row) if row else None
+
+
+def _find_task_guard_blocking_debt(conn, task_id: str) -> dict | None:
+    row = conn.execute(
+        """SELECT *
+           FROM protocol_debt
+           WHERE status = 'open'
+             AND task_id = ?
+             AND debt_type = 'unacknowledged_guard_blocking'
+           ORDER BY id DESC
+           LIMIT 1""",
+        (task_id,),
+    ).fetchone()
+    return dict(row) if row else None
+
+
+def _ensure_protocol_debt(
+    conn,
+    *,
+    session_id: str,
+    task_id: str,
+    debt_type: str,
+    severity: str,
+    evidence: str,
+    file_token: str,
+) -> dict:
+    existing = _find_open_debt(
+        conn,
+        session_id=session_id,
+        task_id=task_id,
+        debt_type=debt_type,
+        file_token=file_token,
+    )
+    if existing:
+        return existing
+    return create_protocol_debt(
+        session_id,
+        debt_type,
+        severity=severity,
+        task_id=task_id,
+        evidence=evidence,
+    )
+
+
+def process_tool_event(payload: dict) -> dict:
+    tool_name = str(payload.get("tool_name", "")).strip()
+    op = _operation_kind(tool_name)
+    if op == "other":
+        return {"ok": True, "skipped": True, "reason": "tool not monitored"}
+
+    tool_input = payload.get("tool_input")
+    files = _extract_touched_files(tool_input)
+    if not files:
+        return {"ok": True, "skipped": True, "reason": "no touched files found"}
+
+    conn = get_db()
+    sid = _resolve_nexo_sid(conn, str(payload.get("session_id", "")))
+    if not sid:
+        return {"ok": True, "skipped": True, "reason": "session not mapped to nexo"}
+
+    conditioned = _load_conditioned_learnings(conn, files)
+    warnings: list[dict] = []
+    violations: list[dict] = []
+
+    for filepath in files:
+        hits = conditioned.get(filepath) or []
+        if not hits:
+            continue
+        learning_ids = [int(row["id"]) for row in hits]
+        task = _find_open_task_for_file(conn, sid, filepath)
+
+        if op == "read":
+            if not task:
+                evidence = (
+                    f"{tool_name} read conditioned file {filepath} linked to learning IDs {learning_ids} "
+                    "without an open protocol task."
+                )
+                debt = _ensure_protocol_debt(
+                    conn,
+                    session_id=sid,
+                    task_id="",
+                    debt_type="conditioned_file_read_without_protocol",
+                    severity="warn",
+                    evidence=evidence,
+                    file_token=filepath,
+                )
+                warnings.append(
+                    {
+                        "file": filepath,
+                        "learning_ids": learning_ids,
+                        "debt_id": debt.get("id"),
+                        "debt_type": "conditioned_file_read_without_protocol",
+                        "message": "Read conditioned file outside protocol task; review the file rules before any write/delete step.",
+                    }
+                )
+            continue
+
+        if not task:
+            evidence = (
+                f"{tool_name} touched conditioned file {filepath} linked to learning IDs {learning_ids} "
+                f"without an open protocol task."
+            )
+            debt = _ensure_protocol_debt(
+                conn,
+                session_id=sid,
+                task_id="",
+                debt_type="conditioned_file_touch_without_protocol",
+                severity="error",
+                evidence=evidence,
+                file_token=filepath,
+            )
+            violations.append(
+                {
+                    "file": filepath,
+                    "learning_ids": learning_ids,
+                    "task_id": "",
+                    "debt_id": debt.get("id"),
+                    "debt_type": "conditioned_file_touch_without_protocol",
+                }
+            )
+            continue
+
+        guard_debt = _find_task_guard_blocking_debt(conn, task["task_id"])
+        if guard_debt:
+            evidence = (
+                f"{tool_name} touched conditioned file {filepath} linked to learning IDs {learning_ids} "
+                f"before acknowledging blocking guard debt for task {task['task_id']}."
+            )
+            debt = _ensure_protocol_debt(
+                conn,
+                session_id=sid,
+                task_id=task["task_id"],
+                debt_type="conditioned_file_touch_without_guard_ack",
+                severity="error",
+                evidence=evidence,
+                file_token=filepath,
+            )
+            violations.append(
+                {
+                    "file": filepath,
+                    "learning_ids": learning_ids,
+                    "task_id": task["task_id"],
+                    "debt_id": debt.get("id"),
+                    "debt_type": "conditioned_file_touch_without_guard_ack",
+                }
+            )
+
+    return {
+        "ok": True,
+        "session_id": sid,
+        "tool_name": tool_name,
+        "operation": op,
+        "warnings": warnings,
+        "violations": violations,
+        "status": "violation" if violations else ("warn" if warnings else "clean"),
+    }
+
+
+def format_hook_message(result: dict) -> str:
+    if not result.get("violations") and not result.get("warnings"):
+        return ""
+    lines = ["NEXO DISCIPLINE:"]
+    for item in result.get("warnings", []):
+        if item.get("debt_id"):
+            lines.append(
+                f"- REVIEW FILE RULES: {item['file']} -> learnings {item['learning_ids']}. "
+                f"{item['message']} (debt={item['debt_type']}, debt_id={item['debt_id']})"
+            )
+        else:
+            lines.append(
+                f"- REVIEW FILE RULES: {item['file']} -> learnings {item['learning_ids']}. "
+                f"{item['message']}"
+            )
+    for item in result.get("violations", []):
+        lines.append(
+            f"- DEBT RECORDED: {item['debt_type']} on {item['file']} "
+            f"(task={item['task_id'] or 'none'}, debt_id={item['debt_id']}, learnings={item['learning_ids']})"
+        )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return 0
+    try:
+        payload = json.loads(raw)
+    except Exception:
+        return 0
+    result = process_tool_event(payload)
+    message = format_hook_message(result)
+    if message:
+        print(message)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/hooks/protocol-guardrail.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# NEXO PostToolUse hook — conditioned file discipline guardrail
+
+INPUT=$(cat || true)
+[ -z "$INPUT" ] && exit 0
+
+NEXO_CODE="${NEXO_CODE:-${HOME}/.nexo}"
+python3 "$NEXO_CODE/hook_guardrails.py" <<< "$INPUT" 2>/dev/null || true
+
+exit 0

package/src/nexo_sdk.py

@@ -0,0 +1,103 @@
+"""Minimal Python SDK for the public NEXO mental model."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass
+class NEXOClient:
+    """Tiny Python wrapper around `nexo call` for common public operations."""
+
+    nexo_bin: str = "nexo"
+
+    def call(self, tool: str, payload: dict | None = None) -> dict | list | str:
+        result = subprocess.run(
+            [
+                self.nexo_bin,
+                "call",
+                tool,
+                "--input",
+                json.dumps(payload or {}, ensure_ascii=False),
+                "--json-output",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise RuntimeError((result.stderr or result.stdout or f"{tool} failed").strip())
+        text = (result.stdout or "").strip()
+        if not text:
+            return {}
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return {"result": text}
+
+    def remember(
+        self,
+        content: str,
+        *,
+        title: str = "",
+        domain: str = "",
+        source_type: str = "note",
+        tags: str = "",
+        bypass_gate: bool = True,
+    ) -> dict | list | str:
+        return self.call(
+            "nexo_remember",
+            {
+                "content": content,
+                "title": title,
+                "domain": domain,
+                "source_type": source_type,
+                "tags": tags,
+                "bypass_gate": bypass_gate,
+            },
+        )
+
+    def recall(self, query: str, *, days: int = 30) -> dict | list | str:
+        return self.call("nexo_memory_recall", {"query": query, "days": days})
+
+    def consolidate(
+        self,
+        *,
+        max_insights: int = 12,
+        threshold: float = 0.9,
+        dry_run: bool = False,
+    ) -> dict | list | str:
+        return self.call(
+            "nexo_consolidate",
+            {
+                "max_insights": max_insights,
+                "threshold": threshold,
+                "dry_run": dry_run,
+            },
+        )
+
+    def run_workflow(
+        self,
+        sid: str,
+        goal: str,
+        *,
+        steps: list[dict] | str,
+        goal_id: str = "",
+        shared_state: dict | str | None = None,
+        owner: str = "",
+        idempotency_key: str = "",
+    ) -> dict | list | str:
+        return self.call(
+            "nexo_run_workflow",
+            {
+                "sid": sid,
+                "goal": goal,
+                "steps": steps if isinstance(steps, str) else json.dumps(steps, ensure_ascii=False),
+                "goal_id": goal_id,
+                "shared_state": shared_state if isinstance(shared_state, str) else json.dumps(shared_state or {}, ensure_ascii=False),
+                "owner": owner,
+                "idempotency_key": idempotency_key,
+            },
+        )

package/src/plugins/cognitive_memory.py

@@ -533,6 +533,23 @@ def handle_cognitive_trigger_check(text: str, use_semantic: bool = False) -> str
     return "\n".join(lines)
 
 
+def handle_cognitive_trigger_preview(text: str, use_semantic: bool = False) -> str:
+    """Preview prospective trigger matches without firing them."""
+    matches = cognitive.preview_triggers(text, use_semantic=use_semantic)
+    if not matches:
+        return "No anticipatory warnings."
+
+    lines = [f"ANTICIPATORY WARNINGS: {len(matches)}", ""]
+    for match in matches:
+        lines.append(f"  #{match['id']} [{match['match_type']}] pattern='{match['pattern']}'")
+        lines.append(f"    ACTION: {match['action']}")
+        if match.get("context"):
+            lines.append(f"    context: {match['context']}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
 def handle_cognitive_trigger_delete(trigger_id: int) -> str:
     """Delete a prospective memory trigger.
 
@@ -570,6 +587,7 @@ TOOLS = [
     (handle_cognitive_quarantine_process, "nexo_cognitive_quarantine_process", "Run quarantine promotion cycle — evaluate pending items against policy."),
     (handle_cognitive_trigger_create, "nexo_cognitive_trigger_create", "Create a prospective memory trigger — 'when X is mentioned, remind about Y'."),
     (handle_cognitive_trigger_list, "nexo_cognitive_trigger_list", "List prospective triggers by status (armed/fired/all)."),
+    (handle_cognitive_trigger_preview, "nexo_cognitive_trigger_preview", "Preview anticipatory trigger matches without firing them."),
     (handle_cognitive_trigger_check, "nexo_cognitive_trigger_check", "Check text against armed triggers. Returns fired triggers with actions."),
     (handle_cognitive_trigger_delete, "nexo_cognitive_trigger_delete", "Delete a prospective trigger by ID."),
     (handle_cognitive_trigger_rearm, "nexo_cognitive_trigger_rearm", "Re-arm a fired trigger so it can fire again."),

package/src/plugins/cortex.py

@@ -15,6 +15,7 @@ v0.1: Single MCP tool + middleware validation.
 """
 
 import json
+import secrets
 import time
 
 
@@ -135,6 +136,51 @@ def _tools_for_mode(mode: str) -> list[str]:
         return ["all"]
 
 
+def _parse_json_list(value) -> list:
+    try:
+        parsed = json.loads(value) if isinstance(value, str) else value
+        return parsed if isinstance(parsed, list) else []
+    except (json.JSONDecodeError, TypeError):
+        return []
+
+
+def evaluate_cortex_state(state: dict) -> dict:
+    """Return structured Cortex evaluation for internal callers."""
+    result = _validate_state(state)
+    result["check_id"] = f"CTX-{int(time.time())}-{secrets.randbelow(100000)}"
+    result["expires_at_epoch"] = int(time.time()) + 1200
+    return result
+
+
+def _log_cortex_activation(goal: str, task_type: str, result: dict):
+    try:
+        conn = _get_db()
+        conn.execute(
+            """CREATE TABLE IF NOT EXISTS cortex_log (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                goal TEXT,
+                task_type TEXT,
+                mode TEXT,
+                warnings TEXT,
+                trust_score INTEGER,
+                created_at TEXT DEFAULT (datetime('now'))
+            )"""
+        )
+        conn.execute(
+            "INSERT INTO cortex_log (goal, task_type, mode, warnings, trust_score) VALUES (?, ?, ?, ?, ?)",
+            (
+                goal[:200],
+                task_type,
+                result["mode"],
+                json.dumps(result["warnings"]),
+                result["trust_score"],
+            ),
+        )
+        conn.commit()
+    except Exception:
+        pass
+
+
 def handle_cortex_check(
     goal: str,
     task_type: str = "answer",
@@ -172,31 +218,25 @@ def handle_cortex_check(
     Returns:
         Mode (ask/propose/act), available tools, warnings, and relevant Core Rules
     """
-    # Parse JSON arrays safely
-    def _parse(s):
-        try:
-            v = json.loads(s) if isinstance(s, str) else s
-            return v if isinstance(v, list) else []
-        except (json.JSONDecodeError, TypeError):
-            return []
-
     state = {
         "goal": goal.strip() if goal else "",
         "task_type": task_type if task_type in ("answer", "analyze", "edit", "execute", "delegate") else "answer",
-        "plan": _parse(plan),
-        "known_facts": _parse(known_facts),
-        "unknowns": _parse(unknowns),
-        "constraints": _parse(constraints),
-        "evidence_refs": _parse(evidence_refs),
+        "plan": _parse_json_list(plan),
+        "known_facts": _parse_json_list(known_facts),
+        "unknowns": _parse_json_list(unknowns),
+        "constraints": _parse_json_list(constraints),
+        "evidence_refs": _parse_json_list(evidence_refs),
         "verification_step": verification_step.strip() if verification_step else "",
     }
 
-    result = _validate_state(state)
+    result = evaluate_cortex_state(state)
 
     # Format response
     lines = [
         f"CORTEX CHECK — mode: {result['mode'].upper()}",
         f"Trust: {result['trust_score']}/100",
+        f"Check ID: {result['check_id']}",
+        f"Valid until epoch: {result['expires_at_epoch']}",
     ]
 
     if result["mode"] == "act":
@@ -223,27 +263,7 @@ def handle_cortex_check(
     lines.append("")
     lines.append(f"Tools available: {', '.join(result['tools_available'])}")
 
-    # Log cortex activation for metrics
-    try:
-        conn = _get_db()
-        conn.execute(
-            """CREATE TABLE IF NOT EXISTS cortex_log (
-                id INTEGER PRIMARY KEY AUTOINCREMENT,
-                goal TEXT,
-                task_type TEXT,
-                mode TEXT,
-                warnings TEXT,
-                trust_score INTEGER,
-                created_at TEXT DEFAULT (datetime('now'))
-            )"""
-        )
-        conn.execute(
-            "INSERT INTO cortex_log (goal, task_type, mode, warnings, trust_score) VALUES (?, ?, ?, ?, ?)",
-            (goal[:200], task_type, result["mode"], json.dumps(result["warnings"]), result["trust_score"])
-        )
-        conn.commit()
-    except Exception:
-        pass
+    _log_cortex_activation(goal, task_type, result)
 
     return "\n".join(lines)