nexo-brain 5.3.13 → 5.3.15

package/templates/launchagents/com.nexo.self-audit.plist

@@ -37,7 +37,7 @@
         <key>HOME</key>
         <string>{{HOME}}</string>
         <key>PATH</key>
-        <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:__NEXO_HOME__/bin</string>
         <key>NEXO_HOME</key>
         <string>{{NEXO_HOME}}</string>
         <key>NEXO_CODE</key>

package/templates/launchagents/com.nexo.synthesis 2.plist

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- com.nexo.synthesis
+     Runs nexo-synthesis.py every 2 hours to generate a daily synthesis
+     document. Aggregates session diaries, error patterns, pending items,
+     and self-evaluation notes into coordination/daily-synthesis.md.
+     This file is read at the start of each session to give NEXO context
+     about what happened recently without replaying full session logs.
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.nexo.synthesis</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/bin/python3</string>
+        <string>{{NEXO_HOME}}/scripts/nexo-synthesis.py</string>
+    </array>
+
+    <key>StartInterval</key>
+    <integer>7200</integer>
+
+    <key>RunAtLoad</key>
+    <false/>
+
+    <key>StandardOutPath</key>
+    <string>{{NEXO_HOME}}/coordination/synthesis-stdout.log</string>
+
+    <key>StandardErrorPath</key>
+    <string>{{NEXO_HOME}}/coordination/synthesis-stderr.log</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>HOME</key>
+        <string>{{HOME}}</string>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:__NEXO_HOME__/bin</string>
+        <key>NEXO_HOME</key>
+        <string>{{NEXO_HOME}}</string>
+        <key>NEXO_CODE</key>
+        <string>{{NEXO_CODE}}</string>
+    </dict>
+</dict>
+</plist>

package/templates/launchagents/com.nexo.synthesis.plist

@@ -35,7 +35,7 @@
         <key>HOME</key>
         <string>{{HOME}}</string>
         <key>PATH</key>
-        <string>/usr/bin:/bin:/usr/local/bin:/opt/homebrew/bin</string>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:__NEXO_HOME__/bin</string>
         <key>NEXO_HOME</key>
         <string>{{NEXO_HOME}}</string>
         <key>NEXO_CODE</key>

package/templates/launchagents/com.nexo.watchdog 2.plist

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- com.nexo.watchdog
+     Runs nexo-watchdog.sh every 30 minutes to monitor system health.
+     Checks that the NEXO MCP server, cron jobs, and key infrastructure
+     services are alive. Writes results to watchdog-status.json and
+     watchdog-report.txt. Sets a .watchdog-alert flag when failures are
+     detected so the next Claude session can alert the user immediately.
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.nexo.watchdog</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>{{NEXO_HOME}}/scripts/nexo-watchdog.sh</string>
+    </array>
+    <key>StartInterval</key>
+    <integer>1800</integer>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>{{NEXO_HOME}}/logs/watchdog-stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>{{NEXO_HOME}}/logs/watchdog-stderr.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:__NEXO_HOME__/bin</string>
+        <key>NEXO_HOME</key>
+        <string>{{NEXO_HOME}}</string>
+        <key>NEXO_CODE</key>
+        <string>{{NEXO_CODE}}</string>
+    </dict>
+</dict>
+</plist>

package/templates/launchagents/com.nexo.watchdog.plist

@@ -27,7 +27,7 @@
     <key>EnvironmentVariables</key>
     <dict>
         <key>PATH</key>
-        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:__NEXO_HOME__/bin</string>
         <key>NEXO_HOME</key>
         <string>{{NEXO_HOME}}</string>
         <key>NEXO_CODE</key>

package/templates/nexo_helper 2.py

@@ -0,0 +1,301 @@
+"""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 os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _detect_nexo_home() -> Path:
+    env_home = os.environ.get("NEXO_HOME", "").strip()
+    if env_home:
+        return Path(env_home).expanduser()
+
+    helper_path = Path(__file__).resolve()
+    inferred_home = helper_path.parent.parent
+    if (
+        helper_path.parent.name == "templates"
+        and (inferred_home / "scripts").is_dir()
+        and (inferred_home / "config").is_dir()
+    ):
+        return inferred_home
+
+    default_home = Path.home() / ".nexo"
+    if default_home.is_dir():
+        return default_home
+
+    claude_home = Path.home() / "claude"
+    if claude_home.is_dir():
+        return claude_home
+
+    return default_home
+
+
+NEXO_HOME = _detect_nexo_home()
+DEFAULT_ALLOWED_TOOLS = "Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*"
+DEFAULT_NEXO_TIMEOUT_SECONDS = max(15, int(os.environ.get("NEXO_HELPER_TIMEOUT", "90")))
+
+
+def _load_schedule() -> dict:
+    schedule_path = NEXO_HOME / "config" / "schedule.json"
+    if not schedule_path.is_file():
+        return {}
+    try:
+        return json.loads(schedule_path.read_text())
+    except Exception:
+        return {}
+
+
+def _resolve_automation_backend() -> str:
+    data = _load_schedule()
+    return str(data.get("automation_backend", "claude_code") or "claude_code")
+
+
+def _load_bootstrap_prompt() -> str:
+    backend = _resolve_automation_backend()
+    if backend == "codex":
+        path = Path.home() / ".codex" / "AGENTS.md"
+    else:
+        path = Path.home() / ".claude" / "CLAUDE.md"
+    if not path.is_file():
+        return ""
+    try:
+        return path.read_text()
+    except Exception:
+        return ""
+
+
+def _resolve_nexo_cli() -> str:
+    candidates = []
+
+    env_cli = os.environ.get("NEXO_BIN", "").strip()
+    if env_cli:
+        candidates.append(Path(env_cli).expanduser())
+
+    candidates.extend(
+        [
+            NEXO_HOME / "bin" / "nexo",
+            Path.home() / ".local" / "bin" / "nexo",
+            Path.home() / "bin" / "nexo",
+        ]
+    )
+
+    for candidate in candidates:
+        try:
+            if candidate.is_file() and os.access(candidate, os.X_OK):
+                return str(candidate)
+        except OSError:
+            continue
+
+    return shutil.which("nexo") or "nexo"
+
+
+def run_nexo(args: list[str]) -> str:
+    """Run a nexo CLI command and return stdout.
+
+    Raises RuntimeError on non-zero exit.
+    """
+    env = os.environ.copy()
+    env.setdefault("NEXO_HOME", str(NEXO_HOME))
+    result = subprocess.run(
+        [_resolve_nexo_cli(), *args],
+        capture_output=True,
+        text=True,
+        timeout=DEFAULT_NEXO_TIMEOUT_SECONDS,
+        env=env,
+    )
+    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)
+
+
+def _extract_json_object(text: str) -> dict:
+    raw = str(text or "").strip()
+    if not raw:
+        raise RuntimeError("Automation backend returned empty output.")
+
+    if raw.startswith("```"):
+        lines = raw.splitlines()
+        if len(lines) >= 2:
+            end = len(lines)
+            for i in range(len(lines) - 1, 0, -1):
+                if lines[i].strip() == "```":
+                    end = i
+                    break
+            raw = "\n".join(lines[1:end]).strip()
+
+    try:
+        parsed = json.loads(raw)
+        if isinstance(parsed, dict):
+            return parsed
+    except Exception:
+        pass
+
+    start = raw.find("{")
+    if start < 0:
+        raise RuntimeError("Automation backend did not return a JSON object.")
+
+    depth = 0
+    in_string = False
+    escape = False
+    for idx in range(start, len(raw)):
+        ch = raw[idx]
+        if in_string:
+            if escape:
+                escape = False
+            elif ch == "\\":
+                escape = True
+            elif ch == '"':
+                in_string = False
+            continue
+
+        if ch == '"':
+            in_string = True
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                candidate = raw[start : idx + 1]
+                try:
+                    parsed = json.loads(candidate)
+                except Exception as exc:
+                    raise RuntimeError(f"Automation backend returned invalid JSON object: {exc}") from exc
+                if isinstance(parsed, dict):
+                    return parsed
+                break
+
+    raise RuntimeError("Automation backend did not return a parseable JSON object.")
+
+
+def run_automation_text(
+    prompt: str,
+    *,
+    model: str = "",
+    reasoning_effort: str = "",
+    cwd: str = "",
+    timeout: int | None = None,
+    allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
+    append_system_prompt: str = "",
+    include_bootstrap: bool = True,
+) -> str:
+    """Run the configured NEXO automation backend and return text output.
+
+    This avoids hardcoding provider CLIs such as `claude -p` inside personal
+    scripts. The runtime routes the call through the selected backend and its
+    configured model profile.
+    """
+    runner = NEXO_HOME / "scripts" / "nexo-agent-run.py"
+    if not runner.exists():
+        raise RuntimeError(f"Automation runner not found: {runner}")
+
+    cmd = [sys.executable, str(runner), "--prompt", prompt, "--output-format", "text"]
+    if model:
+        cmd.extend(["--model", model])
+    if reasoning_effort:
+        cmd.extend(["--reasoning-effort", reasoning_effort])
+    if cwd:
+        cmd.extend(["--cwd", cwd])
+    merged_system_prompt = []
+    if include_bootstrap:
+        bootstrap = _load_bootstrap_prompt()
+        if bootstrap:
+            merged_system_prompt.append(bootstrap)
+    if append_system_prompt:
+        merged_system_prompt.append(append_system_prompt)
+    if merged_system_prompt:
+        cmd.extend(["--append-system-prompt", "\n\n".join(merged_system_prompt)])
+    if allowed_tools:
+        cmd.extend(["--allowed-tools", allowed_tools])
+
+    env = os.environ.copy()
+    env.setdefault("NEXO_HOME", str(NEXO_HOME))
+    env.setdefault("NEXO_CODE", env.get("NEXO_CODE", str(NEXO_HOME)))
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=(int(timeout) if timeout else None),
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"automation backend exited {result.returncode}")
+    return result.stdout
+
+
+def run_automation_json(
+    prompt: str,
+    *,
+    model: str = "",
+    reasoning_effort: str = "",
+    cwd: str = "",
+    timeout: int | None = None,
+    allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
+    append_system_prompt: str = "",
+    include_bootstrap: bool = True,
+) -> dict:
+    """Run the configured backend and return a parsed JSON object."""
+    runner = NEXO_HOME / "scripts" / "nexo-agent-run.py"
+    if not runner.exists():
+        raise RuntimeError(f"Automation runner not found: {runner}")
+
+    cmd = [sys.executable, str(runner), "--prompt", prompt, "--output-format", "json"]
+    if model:
+        cmd.extend(["--model", model])
+    if reasoning_effort:
+        cmd.extend(["--reasoning-effort", reasoning_effort])
+    if cwd:
+        cmd.extend(["--cwd", cwd])
+    merged_system_prompt = []
+    if include_bootstrap:
+        bootstrap = _load_bootstrap_prompt()
+        if bootstrap:
+            merged_system_prompt.append(bootstrap)
+    if append_system_prompt:
+        merged_system_prompt.append(append_system_prompt)
+    if merged_system_prompt:
+        cmd.extend(["--append-system-prompt", "\n\n".join(merged_system_prompt)])
+    if allowed_tools:
+        cmd.extend(["--allowed-tools", allowed_tools])
+
+    env = os.environ.copy()
+    env.setdefault("NEXO_HOME", str(NEXO_HOME))
+    env.setdefault("NEXO_CODE", env.get("NEXO_CODE", str(NEXO_HOME)))
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        env=env,
+        timeout=(int(timeout) if timeout else None),
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or result.stdout.strip() or f"automation backend exited {result.returncode}")
+    return _extract_json_object(result.stdout)

package/templates/openclaw 2.json

@@ -0,0 +1,13 @@
+{
+  "mcp": {
+    "servers": {
+      "nexo-brain": {
+        "command": "python3",
+        "args": ["~/.nexo/server.py"],
+        "env": {
+          "NEXO_HOME": "~/.nexo"
+        }
+      }
+    }
+  }
+}

package/templates/plugin-template 2.py

@@ -0,0 +1,40 @@
+"""Personal NEXO MCP plugin scaffold.
+
+This file lives in NEXO_HOME/plugins/ and is loaded by the NEXO MCP server.
+Edit the handler below to implement your personal capability.
+
+If this plugin ever needs an autonomous model call, route it through the
+configured NEXO automation backend instead of hardcoding `claude -p` or
+provider-specific model names directly inside the plugin.
+"""
+
+from __future__ import annotations
+
+import json
+
+
+def handle_example_tool(payload_json: str = "{}") -> str:
+    """Example personal MCP tool.
+
+    Args:
+        payload_json: JSON string with your input payload.
+    """
+    try:
+        payload = json.loads(payload_json or "{}")
+    except Exception as exc:
+        return json.dumps({"ok": False, "error": f"invalid json: {exc}"}, ensure_ascii=False)
+
+    return json.dumps({
+        "ok": True,
+        "message": "Personal plugin scaffold created. Edit this handler in NEXO_HOME/plugins.",
+        "payload": payload,
+    }, ensure_ascii=False)
+
+
+TOOLS = [
+    (
+        handle_example_tool,
+        "nexo_example_tool",
+        "Example personal MCP tool scaffold. Edit it in NEXO_HOME/plugins.",
+    ),
+]

package/templates/script-template 2.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+# nexo: name=example-script
+# nexo: description=Example personal script using the stable NEXO CLI
+# nexo: category=automation
+# nexo: runtime=python
+# nexo: timeout=60
+# nexo: tools=nexo_learning_search,nexo_schedule_status
+# nexo: interval_seconds=300
+# nexo: schedule_required=false
+
+"""Example personal script for NEXO.
+
+This template demonstrates:
+- Inline metadata for auto-discovery
+- Safe CLI calls through nexo_helper
+- Optional agent calls through the configured automation backend
+- 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, run_automation_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, run_automation_text
+
+# If this script ever needs an autonomous model call:
+#   1. use resolve_user_model() to get the user's configured model
+#   2. pass it to run_automation_text(...)
+#   3. DO NOT hardcode model names — the user picks their model once
+# Example:
+#   from client_preferences import resolve_user_model
+#   result = run_automation_text(
+#       "Summarize pending issues",
+#       model=resolve_user_model(),
+#   )
+
+
+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())

package/templates/script-template 2.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# nexo: name=example-script
+# nexo: description=Example personal shell script using the stable NEXO CLI
+# nexo: category=automation
+# nexo: runtime=shell
+# nexo: timeout=60
+# nexo: schedule=08:00
+# nexo: schedule_required=false
+
+set -euo pipefail
+
+echo "Hello from NEXO personal shell script"
+echo "NEXO_HOME=${NEXO_HOME:-}"

package/templates/script-template.py

@@ -33,13 +33,14 @@ except ImportError:
     from nexo_helper import call_tool_text, run_automation_text
 
 # If this script ever needs an autonomous model call:
-#   1. use run_automation_text(...)
-#   2. pass a legacy task profile like model="opus" when useful
-#   3. DO NOT hardcode `claude -p` or provider-specific model defaults
+#   1. use resolve_user_model() to get the user's configured model
+#   2. pass it to run_automation_text(...)
+#   3. DO NOT hardcode model names — the user picks their model once
 # Example:
+#   from client_preferences import resolve_user_model
 #   result = run_automation_text(
 #       "Summarize pending issues",
-#       model="opus",  # legacy task profile; NEXO maps it per backend
+#       model=resolve_user_model(),
 #   )
 
 

package/templates/skill-script-template 2.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Skill script template.
+
+This script is meant to be referenced by a Skill v2 definition.
+It should use the stable NEXO CLI rather than importing internal DB modules.
+If it needs an agentic model call, route it through NEXO's configured
+automation backend instead of hardcoding `claude -p` or a provider model.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--query", default="")
+    args = parser.parse_args()
+
+    nexo_code = os.environ.get("NEXO_CODE", "")
+    if not nexo_code:
+        print("NEXO_CODE not set", file=sys.stderr)
+        return 1
+
+    cli_py = os.path.join(nexo_code, "cli.py")
+    cmd = [
+        sys.executable,
+        cli_py,
+        "scripts",
+        "call",
+        "nexo_learning_search",
+        "--input",
+        '{"query": %r}' % args.query,
+    ]
+    result = subprocess.run(cmd, text=True)
+    return result.returncode
+
+
+# Agentic example for future edits:
+#   from client_preferences import resolve_user_model
+#   from nexo_helper import run_automation_text
+#   result = run_automation_text("Analyze this", model=resolve_user_model())
+#   print(result)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/templates/skill-script-template.py

@@ -38,8 +38,9 @@ def main() -> int:
 
 
 # Agentic example for future edits:
+#   from client_preferences import resolve_user_model
 #   from nexo_helper import run_automation_text
-#   result = run_automation_text("Analyze this", model="opus")
+#   result = run_automation_text("Analyze this", model=resolve_user_model())
 #   print(result)
 
 

package/templates/skill-template 2.md

@@ -0,0 +1,33 @@
+# Skill Template
+
+Create a directory under one of:
+- `NEXO_HOME/skills/<slug>/`
+- `src/skills/<slug>/`
+- `community/skills/<slug>/`
+
+Required files:
+- `skill.json`
+- `guide.md`
+
+Optional:
+- `script.py` or `script.sh`
+
+Example `skill.json`:
+
+```json
+{
+  "id": "SK-EXAMPLE",
+  "name": "Example Skill",
+  "description": "What this skill does.",
+  "level": "draft",
+  "mode": "guide",
+  "source_kind": "personal",
+  "execution_level": "none",
+  "approval_required": false,
+  "tags": ["example"],
+  "trigger_patterns": ["example task"],
+  "params_schema": {},
+  "command_template": {},
+  "stable_after_uses": 10
+}
+```