nexo-brain 2.4.0 → 2.5.1

package/src/skills_runtime.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+"""Runtime helpers for Skills v2.
+
+This module is the single execution gate for skills. It decides:
+- guide vs execute vs hybrid mode
+- whether a skill is allowed to run
+- how parameters are validated and rendered
+- how execution is routed through the stable `nexo scripts run` CLI
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from db import (
+    approve_skill,
+    collect_skill_improvement_candidates,
+    collect_scriptable_skill_candidates,
+    get_featured_skills,
+    get_skill,
+    get_skill_execution_spec,
+    init_db,
+    materialize_personal_skill_definition,
+    record_skill_usage,
+    render_command_template,
+    sync_skill_directories,
+    update_skill,
+)
+from script_registry import doctor_script
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
+
+
+def _parse_params(params) -> dict:
+    if isinstance(params, dict):
+        return params
+    if isinstance(params, str):
+        text = params.strip()
+        if not text:
+            return {}
+        return json.loads(text)
+    return {}
+
+
+def _ensure_ready():
+    init_db()
+
+
+def _resolve_mode(requested: str, skill: dict) -> str:
+    mode = (requested or "auto").strip().lower()
+    if mode in {"guide", "execute", "hybrid"}:
+        return mode
+    effective = str(skill.get("mode", "") or "").strip().lower()
+    if effective in {"guide", "execute", "hybrid"}:
+        return effective
+    if skill.get("file_path") and skill.get("content"):
+        return "hybrid"
+    if skill.get("file_path"):
+        return "execute"
+    return "guide"
+
+
+def _summarize_skill(skill: dict) -> str:
+    steps = []
+    gotchas = []
+    try:
+        steps = json.loads(skill.get("steps", "[]"))
+    except json.JSONDecodeError:
+        pass
+    try:
+        gotchas = json.loads(skill.get("gotchas", "[]"))
+    except json.JSONDecodeError:
+        pass
+
+    lines = [
+        f"[{skill['id']}] {skill['name']}",
+        skill.get("description", "") or "(no description)",
+    ]
+    if steps:
+        lines.append("Steps:")
+        for index, step in enumerate(steps[:6], 1):
+            lines.append(f"{index}. {step}")
+    elif skill.get("content"):
+        lines.append(skill["content"][:800])
+    if gotchas:
+        lines.append("Gotchas:")
+        for gotcha in gotchas[:4]:
+            lines.append(f"- {gotcha}")
+    return "\n".join(lines).strip()
+
+
+def _resolve_cli_command() -> list[str]:
+    installed = NEXO_HOME / "bin" / "nexo"
+    if installed.is_file():
+        return [str(installed)]
+    return [sys.executable, str(NEXO_CODE / "cli.py")]
+
+
+def _run_skill_script(skill: dict, argv: list[str], timeout: int = 300) -> dict:
+    if not argv:
+        return {"returncode": 1, "stdout": "", "stderr": "No command to execute"}
+
+    env = {
+        **os.environ,
+        "NEXO_HOME": str(NEXO_HOME),
+        "NEXO_CODE": str(NEXO_CODE),
+        "NEXO_SKILL_ID": skill["id"],
+        "NEXO_SKILL_NAME": skill["name"],
+    }
+
+    cli_cmd = _resolve_cli_command()
+    cmd = [*cli_cmd, "scripts", "run", argv[0], *argv[1:]]
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+        return {
+            "returncode": result.returncode,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+            "command": cmd,
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "returncode": 124,
+            "stdout": "",
+            "stderr": f"Skill execution timed out after {timeout}s",
+            "command": cmd,
+        }
+
+
+def get_featured_skill_summaries(limit: int = 5) -> list[dict]:
+    _ensure_ready()
+    sync_skill_directories()
+    featured = []
+    for skill in get_featured_skills(limit=limit):
+        triggers = []
+        try:
+            triggers = json.loads(skill.get("trigger_patterns", "[]"))
+        except json.JSONDecodeError:
+            pass
+        featured.append(
+            {
+                "id": skill["id"],
+                "name": skill["name"],
+                "mode": skill.get("mode", "guide"),
+                "execution_level": skill.get("execution_level", "none"),
+                "source_kind": skill.get("source_kind", "personal"),
+                "trust_score": skill.get("trust_score", 0),
+                "trigger_patterns": triggers[:3],
+            }
+        )
+    return featured
+
+
+def apply_skill(skill_id: str, params=None, mode: str = "auto", dry_run: bool = False, context: str = "") -> dict:
+    _ensure_ready()
+    sync_skill_directories()
+    skill = get_skill(skill_id)
+    if not skill:
+        return {"ok": False, "error": f"Skill {skill_id} not found"}
+
+    effective_mode = _resolve_mode(mode, skill)
+    response = {
+        "ok": True,
+        "skill_id": skill["id"],
+        "skill_name": skill["name"],
+        "requested_mode": mode,
+        "resolved_mode": effective_mode,
+        "approval_state": {
+            "approval_required": bool(skill.get("approval_required", 0)),
+            "approved_at": skill.get("approved_at", ""),
+            "execution_level": skill.get("execution_level", "none"),
+        },
+    }
+
+    if effective_mode in {"guide", "hybrid"}:
+        response["guide_summary"] = _summarize_skill(skill)
+
+    if effective_mode in {"execute", "hybrid"}:
+        exec_spec = get_skill_execution_spec(skill_id)
+        if "error" in exec_spec:
+            response["ok"] = False
+            response["error"] = exec_spec["error"]
+            return response
+
+        if not skill.get("file_path"):
+            response["ok"] = False
+            response["error"] = f"Skill {skill_id} has no executable script"
+            return response
+
+        if exec_spec["execution_level"] in {"read-only", "local", "remote"} and not skill.get("approved_at"):
+            skill = approve_skill(skill_id, execution_level=exec_spec["execution_level"], approved_by="system:auto")
+            response["approval_state"] = {
+                "approval_required": bool(skill.get("approval_required", 0)),
+                "approved_at": skill.get("approved_at", ""),
+                "execution_level": skill.get("execution_level", exec_spec["execution_level"]),
+            }
+
+        doctor = doctor_script(skill["file_path"])
+        response["script_doctor"] = doctor
+        if doctor["status"] == "fail":
+            response["ok"] = False
+            response["error"] = "Skill script failed validation"
+            return response
+
+        rendered = render_command_template(skill, _parse_params(params))
+        if not rendered.get("ok"):
+            response["ok"] = False
+            response["error"] = "Invalid skill parameters"
+            response["param_errors"] = rendered.get("errors", [])
+            return response
+
+        argv = rendered["argv"] or [skill["file_path"]]
+        response["resolved_params"] = rendered["params"]
+        response["script_command"] = argv
+        if dry_run:
+            response["dry_run"] = True
+            return response
+
+        execution = _run_skill_script(skill, argv)
+        response["execution_result"] = execution
+        success = execution["returncode"] == 0
+        record = record_skill_usage(
+            skill_id=skill_id,
+            success=success,
+            context=context or skill["name"],
+            notes=(execution["stderr"] or execution["stdout"])[:500],
+        )
+        response["usage_recorded"] = {
+            "success": success,
+            "trust_score": record.get("trust_score"),
+            "level": record.get("level"),
+            "promotion": record.get("_promotion"),
+        }
+        if not success:
+            response["ok"] = False
+            response["error"] = f"Skill execution failed with exit {execution['returncode']}"
+
+    return response
+
+
+def sync_skills() -> dict:
+    _ensure_ready()
+    return sync_skill_directories()
+
+
+def approve_skill_execution(skill_id: str, execution_level: str = "", approved_by: str = "") -> dict:
+    _ensure_ready()
+    return approve_skill(skill_id, execution_level=execution_level, approved_by=approved_by)
+
+
+def list_evolution_candidates() -> dict:
+    _ensure_ready()
+    sync_skill_directories()
+    return {
+        "scriptable": collect_scriptable_skill_candidates(),
+        "improvements": collect_skill_improvement_candidates(),
+    }
+
+
+def auto_promote_skill_evolution(approved_by: str = "system:auto") -> dict:
+    """Convert mature guide skills into executable drafts without manual approval."""
+    _ensure_ready()
+    sync_skill_directories()
+    promoted = []
+    skipped = []
+    for candidate in collect_scriptable_skill_candidates():
+        skill = get_skill(candidate["id"])
+        if not skill or skill.get("file_path"):
+            continue
+
+        steps = candidate.get("steps") or []
+        gotchas = candidate.get("gotchas") or []
+        description = candidate.get("description", "") or "Automated skill generated from repeated successful usage."
+        lines = [
+            "#!/usr/bin/env python3",
+            '"""Auto-generated executable skill draft."""',
+            "import json",
+            "import sys",
+            "",
+            "def main() -> int:",
+            "    payload = {",
+            f"        'skill_id': {json.dumps(candidate['id'])},",
+            f"        'skill_name': {json.dumps(candidate['name'])},",
+            f"        'description': {json.dumps(description)},",
+            f"        'steps': {json.dumps(steps, ensure_ascii=False)},",
+            f"        'gotchas': {json.dumps(gotchas, ensure_ascii=False)},",
+            "        'argv': sys.argv[1:],",
+            "    }",
+            "    print(json.dumps(payload, ensure_ascii=False))",
+            "    return 0",
+            "",
+            'if __name__ == "__main__":',
+            "    raise SystemExit(main())",
+            "",
+        ]
+        update = update_skill(
+            candidate["id"],
+            mode=candidate.get("suggested_mode", "hybrid"),
+            execution_level=candidate.get("suggested_execution_level", "read-only"),
+            approval_required=0,
+            approved_by=approved_by,
+        )
+        if "error" in update:
+            skipped.append({"id": candidate["id"], "reason": update["error"]})
+            continue
+
+        materialized = materialize_personal_skill_definition(
+            {
+                "id": candidate["id"],
+                "name": candidate["name"],
+                "description": description,
+                "level": skill.get("level", "published"),
+                "mode": candidate.get("suggested_mode", "hybrid"),
+                "execution_level": candidate.get("suggested_execution_level", "read-only"),
+                "approved_by": approved_by,
+                "tags": json.loads(skill.get("tags", "[]")) if skill.get("tags") else [],
+                "trigger_patterns": candidate.get("trigger_patterns", []),
+                "source_sessions": candidate.get("source_sessions", []),
+                "steps": steps,
+                "gotchas": gotchas,
+                "content": skill.get("content", ""),
+                "command_template": {"argv": ["{{file_path}}"]},
+                "executable_entry": "script.py",
+                "script_body": "\n".join(lines),
+            }
+        )
+        if "error" in materialized:
+            skipped.append({"id": candidate["id"], "reason": materialized["error"]})
+            continue
+
+        promoted.append(
+            {
+                "id": candidate["id"],
+                "mode": candidate.get("suggested_mode", "hybrid"),
+                "execution_level": candidate.get("suggested_execution_level", "read-only"),
+            }
+        )
+    return {"promoted": promoted, "skipped": skipped}

package/src/tools_menu.py

@@ -1,8 +1,9 @@
-"""Menu generator — NEXO operations center."""
+"""Menu generator — operations center."""
 
 from datetime import datetime, timedelta
 import json
 import subprocess
+from user_context import get_context as _get_ctx
 import sys
 from pathlib import Path
 from tools_sessions import handle_status
@@ -109,7 +110,7 @@ def handle_menu() -> str:
 
     lines = []
     lines.append("╔" + "═" * W + "╗")
-    lines.append("║" + "NEXO — OPERATIONS CENTER".center(W) + "║")
+    lines.append("║" + f"{_get_ctx().assistant_name} — OPERATIONS CENTER".center(W) + "║")
     lines.append("║" + date_str.center(W) + "║")
     lines.append("╠" + "═" * W + "╣")
 

package/src/tools_sessions.py

@@ -101,9 +101,74 @@ def handle_startup(task: str = "Startup", claude_session_id: str = "") -> str:
             age = _format_age(m["created_epoch"])
             lines.append(f"  [{m['from_sid']}] ({age}): {m['text']}")
 
+    # Check LaunchAgent health (macOS only)
+    la_warnings = _check_launchagents()
+    if la_warnings:
+        lines.append("")
+        lines.append("⚠ LAUNCHAGENT MISMATCH (plist on disk ≠ loaded in memory):")
+        for w in la_warnings:
+            lines.append(f"  {w}")
+        lines.append("  Fix: launchctl unload + load the affected plists, or restart.")
+
     return "\n".join(lines)
 
 
+def _check_launchagents() -> list[str]:
+    """Compare on-disk plists with what launchctl has loaded. macOS only."""
+    import platform
+    if platform.system() != "Darwin":
+        return []
+
+    import os, subprocess, plistlib, glob
+
+    plist_dir = os.path.expanduser("~/Library/LaunchAgents")
+    warnings = []
+
+    for plist_path in glob.glob(os.path.join(plist_dir, "com.nexo.*.plist")):
+        label = os.path.basename(plist_path).replace(".plist", "")
+        try:
+            with open(plist_path, "rb") as f:
+                disk = plistlib.load(f)
+            disk_args = disk.get("ProgramArguments", [])
+
+            result = subprocess.run(
+                ["launchctl", "list", label],
+                capture_output=True, text=True, timeout=5
+            )
+            if result.returncode != 0:
+                warnings.append(f"{label}: not loaded (plist exists on disk)")
+                continue
+
+            # Parse loaded ProgramArguments from launchctl output
+            loaded_args = []
+            in_args = False
+            for line in result.stdout.splitlines():
+                if '"ProgramArguments"' in line:
+                    in_args = True
+                    continue
+                if in_args:
+                    line = line.strip().rstrip(";")
+                    if line == ");":
+                        break
+                    if line.startswith('"') and line.endswith('"'):
+                        loaded_args.append(line.strip('"'))
+
+            if loaded_args and disk_args and loaded_args != disk_args:
+                # Check if loaded path points to /tmp or nonexistent path
+                stale = any("/tmp/" in a or not os.path.exists(a) for a in loaded_args if "/" in a)
+                if stale:
+                    # Auto-repair: reload the plist
+                    subprocess.run(["launchctl", "unload", plist_path], capture_output=True, timeout=5)
+                    subprocess.run(["launchctl", "load", plist_path], capture_output=True, timeout=5)
+                    warnings.append(f"{label}: AUTO-REPAIRED (was pointing to stale/tmp path, reloaded from disk)")
+                else:
+                    warnings.append(f"{label}: loaded args differ from disk plist")
+        except Exception:
+            continue
+
+    return warnings
+
+
 def handle_heartbeat(sid: str, task: str, context_hint: str = '') -> str:
     """Update session, check inbox + questions. Lightweight — no embeddings, no RAG.
 
@@ -209,6 +274,18 @@ def handle_heartbeat(sid: str, task: str, context_hint: str = '') -> str:
             parts.append("")
             parts.append(f"⚠ DIARY_OVERDUE: {_hb_count} heartbeats, {int(age_seconds/60)}min active, no diary. Write nexo_session_diary_write NOW.")
 
+    # Guard check reminder: if context_hint mentions code editing and no guard_check this session
+    if context_hint and _hint_suggests_code_edit(context_hint):
+        try:
+            guard_used = conn.execute(
+                "SELECT COUNT(*) FROM guard_log WHERE session_id = ?", (sid,)
+            ).fetchone()[0]
+            if guard_used == 0:
+                parts.append("")
+                parts.append("⚠ GUARD REMINDER: You appear to be editing code but haven't called `nexo_guard_check` this session. Do it NOW before any edits.")
+        except Exception:
+            pass  # guard_log table may not exist in older installs
+
     return "\n".join(parts)
 
 
@@ -445,11 +522,60 @@ def handle_smart_startup_query() -> str:
             lines.append("")
             lines.append(tone)
 
+        # Toolbox reminder: skills + behavioral learnings count
+        toolbox = _toolbox_summary(conn)
+        if toolbox:
+            lines.append("")
+            lines.append(toolbox)
+
         return "\n".join(lines)
     except Exception as e:
         return f"Smart startup query error: {e}"
 
 
+def _hint_suggests_code_edit(hint: str) -> bool:
+    """Check if a heartbeat context_hint suggests the agent is editing code."""
+    hint_lower = hint.lower()
+    edit_signals = ['edit', 'fix', 'patch', 'modify', 'implement', 'refactor', 'add function',
+                    'change code', 'update script', 'write code', '.py', '.js', '.ts', '.php',
+                    'commit', 'arregl', 'modific', 'implement', 'correg']
+    return any(signal in hint_lower for signal in edit_signals)
+
+
+def _toolbox_summary(conn) -> str:
+    """Quick count of available skills and behavioral learnings for startup reminder."""
+    try:
+        skill_count = conn.execute(
+            "SELECT COUNT(*) FROM skills"
+        ).fetchone()[0]
+        learning_count = conn.execute(
+            "SELECT COUNT(*) FROM learnings WHERE status = 'active' AND priority IN ('critical', 'high')"
+        ).fetchone()[0]
+        parts = []
+        if skill_count > 0:
+            parts.append(f"{skill_count} skills available — use `nexo_skill_match(task)` before multi-step tasks")
+            try:
+                from skills_runtime import get_featured_skill_summaries
+
+                featured = get_featured_skill_summaries(limit=3)
+                if featured:
+                    parts.append("Featured skills:")
+                    for skill in featured:
+                        triggers = ", ".join(skill.get("trigger_patterns", [])[:2]) or "no triggers"
+                        parts.append(
+                            f"- {skill['id']} — {skill['mode']}/{skill['execution_level']} — triggers: {triggers}"
+                        )
+            except Exception:
+                pass
+        if learning_count > 0:
+            parts.append(f"{learning_count} high-priority learnings — use `nexo_guard_check` before editing code")
+        if parts:
+            return "TOOLBOX REMINDER:\n  " + "\n  ".join(parts)
+    except Exception:
+        pass
+    return ""
+
+
 def handle_stop(sid: str) -> str:
     """Cleanly close a session, removing it from active sessions immediately."""
     _stop_keepalive(sid)

package/src/user_context.py

@@ -0,0 +1,46 @@
+"""User context singleton — loads operator/user identity from calibration.json."""
+from __future__ import annotations
+import json
+import os
+from pathlib import Path
+
+_ctx = None
+
+class UserContext:
+    """Cached user/operator identity loaded once from calibration.json."""
+
+    def __init__(self):
+        nexo_home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+        cal_path = nexo_home / "brain" / "calibration.json"
+        ver_path = nexo_home / "version.json"
+
+        self.assistant_name = "NEXO"
+        self.user_name = ""
+        self.user_language = "en"
+
+        # calibration.json has operator_name + user info
+        if cal_path.exists():
+            try:
+                cal = json.loads(cal_path.read_text())
+                self.assistant_name = cal.get("operator_name", "") or \
+                    cal.get("user", {}).get("assistant_name", "") or "NEXO"
+                self.user_name = cal.get("user", {}).get("name", "")
+                self.user_language = cal.get("user", {}).get("language", "en")
+            except Exception:
+                pass
+
+        # Fallback: version.json also has operator_name
+        if self.assistant_name == "NEXO" and ver_path.exists():
+            try:
+                ver = json.loads(ver_path.read_text())
+                self.assistant_name = ver.get("operator_name", "") or "NEXO"
+            except Exception:
+                pass
+
+
+def get_context() -> UserContext:
+    """Get or create the singleton UserContext."""
+    global _ctx
+    if _ctx is None:
+        _ctx = UserContext()
+    return _ctx

package/templates/nexo_helper.py

@@ -0,0 +1,45 @@
+"""NEXO Helper — vendorable utility for personal scripts.
+
+Provides stable access to NEXO MCP tools via the CLI.
+Copy this file next to your script or keep it in NEXO_HOME/templates/.
+
+This module does NOT import any NEXO internals (db, server, cognitive).
+All communication goes through the stable `nexo scripts call` CLI.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+
+
+def run_nexo(args: list[str]) -> str:
+    """Run a nexo CLI command and return stdout.
+
+    Raises RuntimeError on non-zero exit.
+    """
+    result = subprocess.run(
+        ["nexo", *args],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"nexo exited {result.returncode}")
+    return result.stdout
+
+
+def call_tool(name: str, payload: dict | None = None) -> str:
+    """Call a NEXO MCP tool by name. Returns raw text output."""
+    args = ["scripts", "call", name, "--input", json.dumps(payload or {})]
+    return run_nexo(args)
+
+
+def call_tool_text(name: str, payload: dict | None = None) -> str:
+    """Call a NEXO MCP tool and return text output."""
+    return call_tool(name, payload)
+
+
+def call_tool_json(name: str, payload: dict | None = None) -> dict:
+    """Call a NEXO MCP tool and return parsed JSON output."""
+    args = ["scripts", "call", name, "--input", json.dumps(payload or {}), "--json-output"]
+    out = run_nexo(args)
+    return json.loads(out)

package/templates/script-template.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+# nexo: name=example-script
+# nexo: description=Example personal script using the stable NEXO CLI
+# nexo: runtime=python
+# nexo: timeout=60
+# nexo: tools=nexo_learning_search,nexo_schedule_status
+
+"""Example personal script for NEXO.
+
+This template demonstrates:
+- Inline metadata for auto-discovery
+- Safe CLI calls through nexo_helper
+- Timeout handling (via metadata)
+- argparse for user arguments
+- No direct DB access
+- Clean exit codes
+"""
+
+import argparse
+import sys
+
+# nexo_helper.py is in NEXO_HOME/templates/ — copy it next to your script
+# or add the templates dir to your path
+try:
+    from nexo_helper import call_tool_text
+except ImportError:
+    import os
+    sys.path.insert(0, os.path.join(os.environ.get("NEXO_HOME", "~/.nexo"), "templates"))
+    from nexo_helper import call_tool_text
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Example NEXO personal script")
+    parser.add_argument("--query", default="cron", help="Search query for learnings")
+    args = parser.parse_args()
+
+    print(f"Searching learnings for: {args.query}")
+    result = call_tool_text("nexo_learning_search", {"query": args.query})
+    print(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())