nexo-brain 3.0.2 → 3.1.0

package/src/hook_guardrails.py

@@ -3,11 +3,13 @@ from __future__ import annotations
 """Post-tool guardrails for conditioned file learnings."""
 
 import json
+import os
 import sys
 from pathlib import Path
 
 from db import create_protocol_debt, get_db
 from plugins.guard import _load_conditioned_learnings, _normalize_path_token
+from protocol_settings import get_protocol_strictness
 
 READ_LIKE_TOOLS = {"Read"}
 WRITE_LIKE_TOOLS = {"Edit", "MultiEdit", "Write"}
@@ -94,6 +96,18 @@ def _find_open_task_for_file(conn, sid: str, filepath: str) -> dict | None:
     return None
 
 
+def _find_any_open_task(conn, sid: str) -> dict | None:
+    row = conn.execute(
+        """SELECT task_id, files, guard_has_blocking
+           FROM protocol_tasks
+           WHERE session_id = ? AND status = 'open'
+           ORDER BY opened_at DESC
+           LIMIT 1""",
+        (sid,),
+    ).fetchone()
+    return dict(row) if row else None
+
+
 def _find_open_debt(conn, *, session_id: str, task_id: str, debt_type: str, file_token: str) -> dict | None:
     row = conn.execute(
         """SELECT *
@@ -152,6 +166,136 @@ def _ensure_protocol_debt(
     )
 
 
+def process_pre_tool_event(payload: dict) -> dict:
+    strictness = get_protocol_strictness()
+    tool_name = str(payload.get("tool_name", "")).strip()
+    op = _operation_kind(tool_name)
+    if strictness == "lenient":
+        return {"ok": True, "skipped": True, "reason": "lenient mode", "strictness": strictness}
+    if op not in {"write", "delete"}:
+        return {"ok": True, "skipped": True, "reason": "operation not blocked", "strictness": strictness}
+
+    tool_input = payload.get("tool_input")
+    files = _extract_touched_files(tool_input)
+    conn = get_db()
+    sid = _resolve_nexo_sid(conn, str(payload.get("session_id", "")))
+    blocks: list[dict] = []
+
+    if not sid:
+        debt = _ensure_protocol_debt(
+            conn,
+            session_id="",
+            task_id="",
+            debt_type="strict_protocol_write_without_startup",
+            severity="error",
+            evidence=f"{tool_name} attempted before nexo_startup/session mapping.",
+            file_token="startup",
+        )
+        blocks.append(
+            {
+                "file": "",
+                "task_id": "",
+                "debt_id": debt.get("id"),
+                "debt_type": "strict_protocol_write_without_startup",
+                "reason_code": "missing_startup",
+            }
+        )
+        return {
+            "ok": True,
+            "session_id": sid,
+            "tool_name": tool_name,
+            "operation": op,
+            "strictness": strictness,
+            "blocks": blocks,
+            "status": "blocked",
+        }
+
+    if not files:
+        task = _find_any_open_task(conn, sid)
+        if not task:
+            debt = _ensure_protocol_debt(
+                conn,
+                session_id=sid,
+                task_id="",
+                debt_type="strict_protocol_write_without_task",
+                severity="error",
+                evidence=f"{tool_name} attempted without a detectable file path and without an open protocol task.",
+                file_token="unknown-target",
+            )
+            blocks.append(
+                {
+                    "file": "",
+                    "task_id": "",
+                    "debt_id": debt.get("id"),
+                    "debt_type": "strict_protocol_write_without_task",
+                    "reason_code": "missing_task",
+                }
+            )
+        return {
+            "ok": True,
+            "session_id": sid,
+            "tool_name": tool_name,
+            "operation": op,
+            "strictness": strictness,
+            "blocks": blocks,
+            "status": "blocked" if blocks else "clean",
+        }
+
+    for filepath in files:
+        task = _find_open_task_for_file(conn, sid, filepath)
+        if not task:
+            debt = _ensure_protocol_debt(
+                conn,
+                session_id=sid,
+                task_id="",
+                debt_type="strict_protocol_write_without_task",
+                severity="error",
+                evidence=f"{tool_name} attempted on {filepath} without an open protocol task for that file.",
+                file_token=filepath,
+            )
+            blocks.append(
+                {
+                    "file": filepath,
+                    "task_id": "",
+                    "debt_id": debt.get("id"),
+                    "debt_type": "strict_protocol_write_without_task",
+                    "reason_code": "missing_task",
+                }
+            )
+            continue
+
+        guard_debt = _find_task_guard_blocking_debt(conn, task["task_id"])
+        if guard_debt:
+            debt = _ensure_protocol_debt(
+                conn,
+                session_id=sid,
+                task_id=task["task_id"],
+                debt_type="strict_protocol_write_without_guard_ack",
+                severity="error",
+                evidence=f"{tool_name} attempted on {filepath} before acknowledging guard debt for task {task['task_id']}.",
+                file_token=filepath,
+            )
+            blocks.append(
+                {
+                    "file": filepath,
+                    "task_id": task["task_id"],
+                    "debt_id": debt.get("id"),
+                    "debt_type": "strict_protocol_write_without_guard_ack",
+                    "reason_code": "guard_unacknowledged",
+                }
+            )
+
+    return {
+        "ok": True,
+        "session_id": sid,
+        "tool_name": tool_name,
+        "operation": op,
+        "strictness": strictness,
+        "blocks": blocks,
+        "status": "blocked" if blocks else "clean",
+    }
+
+
 def process_tool_event(payload: dict) -> dict:
     tool_name = str(payload.get("tool_name", "")).strip()
     op = _operation_kind(tool_name)
@@ -289,6 +433,38 @@ def format_hook_message(result: dict) -> str:
     return "\n".join(lines)
 
 
+def format_pretool_block_message(result: dict) -> str:
+    blocks = result.get("blocks") or []
+    if not blocks:
+        return ""
+    strictness = str(result.get("strictness") or "strict")
+    header = (
+        "NEXO LEARNING MODE BLOCKED THIS EDIT:"
+        if strictness == "learning"
+        else "NEXO STRICT MODE BLOCKED THIS EDIT:"
+    )
+    lines = [header]
+    for item in blocks:
+        file_note = item["file"] or "(unknown target)"
+        if item.get("reason_code") == "missing_startup":
+            lines.append(
+                f"- Start the shared-brain session first: call `nexo_startup`, then `nexo_task_open`, before editing {file_note}."
+            )
+        elif item.get("reason_code") == "guard_unacknowledged":
+            lines.append(
+                f"- {file_note}: task {item['task_id']} still has blocking guard debt. Acknowledge it with `nexo_task_acknowledge_guard` before retrying."
+            )
+        elif strictness == "learning":
+            lines.append(
+                f"- {file_note}: open `nexo_task_open(task_type='edit', files=['{file_note}'])` first, then rerun the edit."
+            )
+        else:
+            lines.append(
+                f"- {file_note}: open `nexo_task_open(... files=['{file_note}'])` before editing."
+            )
+    return "\n".join(lines)
+
+
 def main() -> int:
     raw = sys.stdin.read()
     if not raw.strip():
@@ -297,6 +473,12 @@ def main() -> int:
         payload = json.loads(raw)
     except Exception:
         return 0
+    if os.environ.get("NEXO_HOOK_PHASE", "").strip().lower() == "pre":
+        result = process_pre_tool_event(payload)
+        message = format_pretool_block_message(result)
+        if message:
+            print(message, file=sys.stderr)
+        return 2 if result.get("status") == "blocked" else 0
     result = process_tool_event(payload)
     message = format_hook_message(result)
     if message:

package/src/hooks/protocol-guardrail.sh

@@ -5,6 +5,6 @@ INPUT=$(cat || true)
 [ -z "$INPUT" ] && exit 0
 
 NEXO_CODE="${NEXO_CODE:-${HOME}/.nexo}"
-python3 "$NEXO_CODE/hook_guardrails.py" <<< "$INPUT" 2>/dev/null || true
+NEXO_HOOK_PHASE=post python3 "$NEXO_CODE/hook_guardrails.py" <<< "$INPUT" 2>/dev/null || true
 
 exit 0

package/src/hooks/protocol-pretool-guardrail.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# NEXO PreToolUse hook — strict protocol blocking before writes/deletes
+
+INPUT=$(cat || true)
+[ -z "$INPUT" ] && exit 0
+
+NEXO_CODE="${NEXO_CODE:-${HOME}/.nexo}"
+NEXO_HOOK_PHASE=pre python3 "$NEXO_CODE/hook_guardrails.py" <<< "$INPUT"
+exit $?

package/src/plugins/protocol.py

@@ -23,6 +23,7 @@ from db import (
 )
 from plugins.cortex import evaluate_cortex_state
 from plugins.guard import handle_guard_check
+from protocol_settings import get_protocol_strictness
 from tools_sessions import handle_heartbeat
 
 
@@ -450,6 +451,18 @@ def handle_task_open(
 
     clean_type = task_type if task_type in {"answer", "analyze", "edit", "execute", "delegate"} else "answer"
     files_list = _parse_list(files)
+    protocol_strictness = get_protocol_strictness()
+    if protocol_strictness in {"strict", "learning"} and clean_type == "edit" and not files_list:
+        note = (
+            "Strict protocol mode requires explicit `files` for edit tasks."
+            if protocol_strictness == "strict"
+            else "Learning mode requires explicit `files` on edit tasks so NEXO can match the write against the open protocol task."
+        )
+        return json.dumps(
+            {"ok": False, "error": note, "protocol_strictness": protocol_strictness},
+            ensure_ascii=False,
+            indent=2,
+        )
     state = {
         "goal": clean_goal,
         "task_type": clean_type,
@@ -569,6 +582,7 @@ def handle_task_open(
         "session_id": sid,
         "goal": clean_goal,
         "task_type": clean_type,
+        "protocol_strictness": protocol_strictness,
         "mode": cortex["mode"],
         "check_id": cortex["check_id"],
         "blocked_reason": cortex.get("blocked_reason"),
@@ -596,6 +610,7 @@ def handle_task_open(
             "must_change_log": must_change_log,
             "must_learning_if_corrected": must_learning_if_corrected,
             "must_write_diary_on_close": must_write_diary_on_close,
+            "protocol_strictness": protocol_strictness,
         },
         "session_touch": heartbeat_result.splitlines()[0] if heartbeat_result else "",
         "open_debts": debts_created,

package/src/protocol_settings.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+"""Shared protocol-discipline settings loaded from calibration.json."""
+
+import json
+import os
+from pathlib import Path
+
+
+DEFAULT_PROTOCOL_STRICTNESS = "lenient"
+VALID_PROTOCOL_STRICTNESS = {"lenient", "strict", "learning"}
+
+
+def _nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo"))).expanduser()
+
+
+def _calibration_path() -> Path:
+    return _nexo_home() / "brain" / "calibration.json"
+
+
+def normalize_protocol_strictness(value: str | None) -> str:
+    candidate = str(value or "").strip().lower()
+    aliases = {
+        "default": "lenient",
+        "normal": "lenient",
+        "off": "lenient",
+        "warn": "lenient",
+        "soft": "lenient",
+        "hard": "strict",
+        "guided": "learning",
+    }
+    candidate = aliases.get(candidate, candidate)
+    if candidate in VALID_PROTOCOL_STRICTNESS:
+        return candidate
+    return DEFAULT_PROTOCOL_STRICTNESS
+
+
+def get_protocol_strictness() -> str:
+    env_override = os.environ.get("NEXO_PROTOCOL_STRICTNESS", "").strip()
+    if env_override:
+        return normalize_protocol_strictness(env_override)
+
+    cal_path = _calibration_path()
+    if not cal_path.is_file():
+        return DEFAULT_PROTOCOL_STRICTNESS
+
+    try:
+        payload = json.loads(cal_path.read_text())
+    except Exception:
+        return DEFAULT_PROTOCOL_STRICTNESS
+
+    preferences = payload.get("preferences") if isinstance(payload, dict) else {}
+    candidate = ""
+    if isinstance(preferences, dict):
+        candidate = str(preferences.get("protocol_strictness", "") or "").strip()
+    if not candidate and isinstance(payload, dict):
+        candidate = str(payload.get("protocol_strictness", "") or "").strip()
+    return normalize_protocol_strictness(candidate)

package/src/public_evolution_queue.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+"""Durable queue for public-core ports discovered outside the public runner.
+
+Managed flows such as self-audit may apply a local/core fix inline. When that
+fix belongs in the public repository as well, we persist a normalized queue
+entry in ``evolution_log`` so the weekly public contribution cycle can port it
+later instead of losing the improvement inside one machine.
+"""
+
+import json
+import os
+import sqlite3
+from pathlib import Path
+
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo"))).expanduser()
+QUEUE_CLASSIFICATION = "public_port_queue"
+QUEUE_STATUS_PENDING = "pending_public_port"
+PUBLIC_ALLOWED_PREFIXES = (
+    "src/",
+    "bin/",
+    "tests/",
+    "templates/",
+    "hooks/",
+    "migrations/",
+    ".claude-plugin/",
+)
+
+
+def resolve_repo_root(nexo_code: str | os.PathLike[str] | None = None) -> Path | None:
+    raw = Path(
+        nexo_code
+        or os.environ.get("NEXO_CODE")
+        or str(NEXO_HOME)
+    ).expanduser()
+    candidates = []
+    if raw.name == "src":
+        candidates.append(raw.parent)
+    candidates.append(raw)
+    for candidate in candidates:
+        if (candidate / "package.json").exists():
+            return candidate.resolve()
+    return None
+
+
+def normalize_public_path(
+    filepath: str,
+    *,
+    repo_root: Path | None = None,
+) -> str:
+    text = str(filepath or "").strip()
+    if not text:
+        return ""
+
+    normalized_raw = text.replace("\\", "/").lstrip("./")
+    if any(
+        normalized_raw == prefix.rstrip("/")
+        or normalized_raw.startswith(prefix)
+        for prefix in PUBLIC_ALLOWED_PREFIXES
+    ):
+        return normalized_raw
+
+    repo_root = repo_root or resolve_repo_root()
+    if not repo_root:
+        return ""
+
+    candidate = Path(text).expanduser()
+    if not candidate.is_absolute():
+        candidate = repo_root / candidate
+    try:
+        rel = candidate.resolve().relative_to(repo_root.resolve()).as_posix()
+    except Exception:
+        for prefix in PUBLIC_ALLOWED_PREFIXES:
+            marker = normalized_raw.find(prefix)
+            if marker >= 0:
+                return normalized_raw[marker:]
+        return ""
+    if any(rel == prefix.rstrip("/") or rel.startswith(prefix) for prefix in PUBLIC_ALLOWED_PREFIXES):
+        return rel
+    return ""
+
+
+def is_public_core_path(filepath: str, *, repo_root: Path | None = None) -> bool:
+    return bool(normalize_public_path(filepath, repo_root=repo_root))
+
+
+def queue_public_port_candidate(
+    conn: sqlite3.Connection,
+    *,
+    title: str,
+    reasoning: str,
+    files_changed: list[str],
+    source: str,
+    metadata: dict | None = None,
+) -> dict:
+    row = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='evolution_log'"
+    ).fetchone()
+    if not row:
+        return {"ok": False, "reason": "evolution_log_missing"}
+
+    repo_root = resolve_repo_root()
+    normalized_files: list[str] = []
+    seen: set[str] = set()
+    for filepath in files_changed:
+        rel = normalize_public_path(filepath, repo_root=repo_root)
+        if rel and rel not in seen:
+            normalized_files.append(rel)
+            seen.add(rel)
+    if not normalized_files:
+        return {"ok": False, "reason": "no_public_files"}
+
+    proposal = str(title or "").strip()[:300] or "Managed core autofix queued for public port"
+    clean_reasoning = str(reasoning or "").strip()[:4000] or "Queued for public-core port."
+    payload = dict(metadata or {})
+    payload.setdefault("source", source)
+    payload["files"] = normalized_files
+
+    existing = conn.execute(
+        """SELECT id, status
+           FROM evolution_log
+           WHERE classification = ?
+             AND proposal = ?
+             AND files_changed = ?
+             AND status IN (?, 'draft_pr_created', 'skipped_duplicate_existing_pr')
+           ORDER BY id DESC
+           LIMIT 1""",
+        (
+            QUEUE_CLASSIFICATION,
+            proposal,
+            json.dumps(normalized_files),
+            QUEUE_STATUS_PENDING,
+        ),
+    ).fetchone()
+    if existing:
+        return {
+            "ok": True,
+            "queued": False,
+            "log_id": int(existing["id"]),
+            "status": str(existing["status"] or ""),
+            "files_changed": normalized_files,
+        }
+
+    cur = conn.execute(
+        """INSERT INTO evolution_log (
+               cycle_number, dimension, proposal, classification, reasoning, status, files_changed, test_result
+           ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+        (
+            0,
+            "public_core",
+            proposal,
+            QUEUE_CLASSIFICATION,
+            clean_reasoning,
+            QUEUE_STATUS_PENDING,
+            json.dumps(normalized_files),
+            json.dumps(payload, ensure_ascii=False),
+        ),
+    )
+    return {
+        "ok": True,
+        "queued": True,
+        "log_id": int(cur.lastrowid),
+        "status": QUEUE_STATUS_PENDING,
+        "files_changed": normalized_files,
+    }
+
+
+def list_pending_public_port_candidates(
+    conn: sqlite3.Connection,
+    *,
+    limit: int = 3,
+) -> list[dict]:
+    rows = conn.execute(
+        """SELECT id, created_at, proposal, reasoning, status, files_changed, test_result
+           FROM evolution_log
+           WHERE classification = ?
+             AND status = ?
+           ORDER BY created_at ASC, id ASC
+           LIMIT ?""",
+        (QUEUE_CLASSIFICATION, QUEUE_STATUS_PENDING, max(1, int(limit))),
+    ).fetchall()
+    results: list[dict] = []
+    for row in rows:
+        metadata = {}
+        raw_payload = str(row["test_result"] or "").strip()
+        if raw_payload:
+            try:
+                parsed = json.loads(raw_payload)
+                if isinstance(parsed, dict):
+                    metadata = parsed
+            except Exception:
+                metadata = {"raw": raw_payload}
+        files_changed = []
+        raw_files = str(row["files_changed"] or "").strip()
+        if raw_files:
+            try:
+                parsed_files = json.loads(raw_files)
+                if isinstance(parsed_files, list):
+                    files_changed = [str(item).strip() for item in parsed_files if str(item).strip()]
+            except Exception:
+                pass
+        results.append(
+            {
+                "id": int(row["id"]),
+                "created_at": str(row["created_at"] or ""),
+                "title": str(row["proposal"] or ""),
+                "reasoning": str(row["reasoning"] or ""),
+                "status": str(row["status"] or ""),
+                "files_changed": files_changed,
+                "metadata": metadata,
+            }
+        )
+    return results
+
+
+def update_public_port_candidate(
+    conn: sqlite3.Connection,
+    log_id: int,
+    *,
+    status: str,
+    metadata_patch: dict | None = None,
+) -> None:
+    row = conn.execute(
+        "SELECT test_result FROM evolution_log WHERE id = ? LIMIT 1",
+        (int(log_id),),
+    ).fetchone()
+    payload: dict = {}
+    if row and str(row["test_result"] or "").strip():
+        try:
+            parsed = json.loads(str(row["test_result"]))
+            if isinstance(parsed, dict):
+                payload = parsed
+        except Exception:
+            payload = {"raw": str(row["test_result"])}
+    if metadata_patch:
+        payload.update(metadata_patch)
+    conn.execute(
+        "UPDATE evolution_log SET status = ?, test_result = ? WHERE id = ?",
+        (status, json.dumps(payload, ensure_ascii=False), int(log_id)),
+    )