nexo-brain 7.13.5 → 7.13.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.13.5",
+  "version": "7.13.7",
   "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,9 @@
 
 [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 `7.13.5` is the current packaged-runtime line. Corrective release — D.5 correction-learning enforcement is durable, doctor `--fix` explicitly repairs orphan personal schedule metadata, G5 now warns on protected `com.nexo.*.plist` unload/remove flows with the three-layer recovery path, and Codex now gets a managed `PreToolUse` guard for shell/exec_command calls plus `installation_live.codex_protocol_compliance` drift checks. Result: coordinated Desktop bundles can ship the fixed Brain without changing the Mac/Windows installation contract.
+Version `7.13.7` is the current packaged-runtime line. Patch release over v7.13.6 — Brain adds an authenticated official protocol-card client (`nexo_card_catalog`, `nexo_card_get`, `nexo_card_match`) so agents can ask the NEXO Desktop backend for the right task protocol at runtime. The protocol corpus stays private on the server; this open-source package ships only the client, tool map, and agent guidance.
+
+Previously in `7.13.6`: patch release — Codex hook sync now renders the managed `PreToolUse` shell/exec_command guard with native Windows `cmd.exe` syntax while preserving the existing POSIX command on macOS/Linux. Result: coordinated Desktop bundles can ship the fixed Brain without changing the Mac/Windows installation contract.
 
 Previously in `7.13.3`: unified release — doctor now repairs orphan personal script metadata and ignores historical `versions/**` snapshots, `nexo update` prunes runtime snapshots older than two back, protocol compliance self-heals missing task-open/change-log/stale-session gaps, headless automation uses bounded timeouts, Guardian false positives are tightened, and Codex CLI config/default checks are release-gated. Result: coordinated Desktop bundles can ship the new Brain without changing the Mac/Windows installation contract.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.13.5",
+  "version": "7.13.7",
   "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",

package/src/client_sync.py

@@ -917,23 +917,43 @@ def _resolve_hook_source_dir(runtime_root: Path) -> Path:
     return direct
 
 
-def _render_hook_command(spec: dict, *, nexo_home: Path, runtime_root: Path, hooks_dir: Path) -> str:
+def _cmd_env_assignment(name: str, value: str | os.PathLike[str]) -> str:
+    # `set "VAR=value"` is the safe cmd.exe form; it preserves spaces and
+    # avoids trailing quote pollution.
+    safe_value = str(value).replace('"', r'\"')
+    return f'set "{name}={safe_value}"'
+
+
+def _cmd_args(*args: str | os.PathLike[str]) -> str:
+    return subprocess.list2cmdline([str(arg) for arg in args])
+
+
+def _render_hook_command(
+    spec: dict,
+    *,
+    nexo_home: Path,
+    runtime_root: Path,
+    hooks_dir: Path,
+    windows_shell: bool | None = None,
+) -> str:
     command_template = spec.get("command_template")
     if callable(command_template):
         return command_template(nexo_home, runtime_root, hooks_dir)
     handler_name = (spec.get("handler") or spec.get("script") or "").strip()
     script_path = hooks_dir / handler_name
-    if spec.get("interpreter") == "python" or handler_name.endswith(".py"):
-        return (
-            f"NEXO_HOME={shlex.quote(str(nexo_home))} "
-            f"NEXO_CODE={shlex.quote(str(runtime_root))} "
-            f"{shlex.quote(_resolve_python(nexo_home))} {shlex.quote(str(script_path))}"
-        )
-    return (
-        f"NEXO_HOME={shlex.quote(str(nexo_home))} "
-        f"NEXO_CODE={shlex.quote(str(runtime_root))} "
-        f"bash {shlex.quote(str(script_path))}"
+    use_windows_shell = (os.name == "nt") if windows_shell is None else bool(windows_shell)
+    env_prefix = (
+        f"{_cmd_env_assignment('NEXO_HOME', nexo_home)} && {_cmd_env_assignment('NEXO_CODE', runtime_root)} && "
+        if use_windows_shell
+        else f"NEXO_HOME={shlex.quote(str(nexo_home))} NEXO_CODE={shlex.quote(str(runtime_root))} "
     )
+    if spec.get("interpreter") == "python" or handler_name.endswith(".py"):
+        if use_windows_shell:
+            return f"{env_prefix}{_cmd_args(_resolve_python(nexo_home), script_path)}"
+        return env_prefix + f"{shlex.quote(_resolve_python(nexo_home))} {shlex.quote(str(script_path))}"
+    if use_windows_shell:
+        return f"{env_prefix}{_cmd_args('bash', script_path)}"
+    return env_prefix + f"bash {shlex.quote(str(script_path))}"
 
 
 def _hook_identity(command: str) -> str:

package/src/plugins/cards.py

@@ -0,0 +1,221 @@
+"""Authenticated client for NEXO official protocol cards.
+
+The protocol corpus lives on the private NEXO Desktop backend. This open-source
+plugin only knows how to authenticate and fetch cards at runtime.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_API_BASE = "https://nexo-desktop.com"
+SHARED_AUTH_DIRNAME = "nexo-shared-auth"
+SHARED_AUTH_FILENAME = "session.json"
+
+_urlopen = urllib.request.urlopen
+
+
+def _json(data: dict[str, Any]) -> str:
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+def _as_bool(value: Any, default: bool = False) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    return str(value).strip().lower() in {"1", "true", "yes", "y", "si", "sí", "on"}
+
+
+def _as_int(value: Any, default: int = 5) -> int:
+    try:
+        return int(value)
+    except Exception:
+        return default
+
+
+def _api_base() -> str:
+    raw = os.environ.get("NEXO_DESKTOP_API_BASE") or os.environ.get("NEXO_CARDS_API_BASE") or DEFAULT_API_BASE
+    return raw.strip().rstrip("/") or DEFAULT_API_BASE
+
+
+def _normalize_locale(locale: str = "es") -> str:
+    return "en" if str(locale or "").lower().startswith("en") else "es"
+
+
+def _shared_auth_candidates() -> list[Path]:
+    candidates: list[Path] = []
+    for env_name in ("NEXO_SHARED_AUTH_FILE", "NEXO_DESKTOP_SHARED_AUTH_FILE"):
+        raw = os.environ.get(env_name)
+        if raw:
+            candidates.append(Path(raw).expanduser())
+
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        candidates.append(Path(appdata) / SHARED_AUTH_DIRNAME / SHARED_AUTH_FILENAME)
+
+    home = Path.home()
+    system = platform.system().lower()
+    if system == "darwin":
+        candidates.append(home / "Library" / "Application Support" / SHARED_AUTH_DIRNAME / SHARED_AUTH_FILENAME)
+    elif system == "windows":
+        candidates.append(home / "AppData" / "Roaming" / SHARED_AUTH_DIRNAME / SHARED_AUTH_FILENAME)
+    else:
+        xdg = os.environ.get("XDG_CONFIG_HOME")
+        if xdg:
+            candidates.append(Path(xdg) / SHARED_AUTH_DIRNAME / SHARED_AUTH_FILENAME)
+        candidates.append(home / ".config" / SHARED_AUTH_DIRNAME / SHARED_AUTH_FILENAME)
+
+    nexo_home = Path(os.environ.get("NEXO_HOME", str(home / ".nexo"))).expanduser()
+    candidates.append(nexo_home / "runtime" / "shared-auth" / SHARED_AUTH_FILENAME)
+    return candidates
+
+
+def _read_token_from_shared_auth() -> str:
+    for path in _shared_auth_candidates():
+        try:
+            if not path.is_file():
+                continue
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            token = str(payload.get("token") or "").strip()
+            if token:
+                return token
+        except Exception:
+            continue
+    return ""
+
+
+def _read_token() -> str:
+    for env_name in ("NEXO_DESKTOP_AUTH_TOKEN", "NEXO_CARDS_TOKEN", "NEXO_AUTH_TOKEN"):
+        token = str(os.environ.get(env_name) or "").strip()
+        if token:
+            return token
+    return _read_token_from_shared_auth()
+
+
+def _error(error_type: str, message: str, *, status: int = 0, extra: dict[str, Any] | None = None) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "ok": False,
+        "error": {
+            "type": error_type,
+            "message": message,
+        },
+    }
+    if status:
+        payload["status"] = status
+    if extra:
+        payload["error"].update(extra)
+    return payload
+
+
+def _decode_body(raw: bytes) -> dict[str, Any]:
+    if not raw:
+        return {}
+    try:
+        decoded = json.loads(raw.decode("utf-8"))
+        return decoded if isinstance(decoded, dict) else {"data": decoded}
+    except Exception:
+        return {"raw": raw.decode("utf-8", errors="replace")[:1000]}
+
+
+def _request_json(method: str, path: str, *, body: dict[str, Any] | None = None, locale: str = "es") -> dict[str, Any]:
+    token = _read_token()
+    if not token:
+        return _error(
+            "not_authenticated",
+            "No hay sesión NEXO Desktop disponible para consultar fichas.",
+        )
+
+    data = json.dumps(body or {}, ensure_ascii=False).encode("utf-8") if body is not None else None
+    request = urllib.request.Request(
+        f"{_api_base()}{path}",
+        data=data,
+        method=method.upper(),
+        headers={
+            "Accept": "application/json",
+            "Accept-Language": _normalize_locale(locale),
+            "Authorization": f"Bearer {token}",
+            **({"Content-Type": "application/json"} if data is not None else {}),
+        },
+    )
+    try:
+        with _urlopen(request, timeout=20) as response:
+            payload = _decode_body(response.read())
+            if isinstance(payload, dict):
+                payload.setdefault("ok", True)
+                payload.setdefault("status", getattr(response, "status", 200))
+                return payload
+            return {"ok": True, "data": payload, "status": getattr(response, "status", 200)}
+    except urllib.error.HTTPError as exc:
+        payload = _decode_body(exc.read())
+        error = payload.get("error") if isinstance(payload, dict) else None
+        if isinstance(error, dict):
+            return _error(
+                str(error.get("type") or "request_failed"),
+                str(error.get("message") or f"HTTP {exc.code}"),
+                status=int(exc.code or 0),
+                extra={k: v for k, v in error.items() if k not in {"type", "message"}},
+            )
+        return _error("request_failed", f"Protocol cards API returned HTTP {exc.code}.", status=int(exc.code or 0))
+    except Exception as exc:
+        return _error("network_error", str(exc))
+
+
+def handle_card_catalog(locale: str = "es") -> str:
+    """Return the visible official protocol card catalog. Never includes protocols."""
+    params = urllib.parse.urlencode({"locale": _normalize_locale(locale)})
+    return _json(_request_json("GET", f"/api/cards/catalog?{params}", locale=locale))
+
+
+def handle_card_get(slug: str, locale: str = "es") -> str:
+    """Fetch one official protocol card, including protocol text, by slug."""
+    clean_slug = str(slug or "").strip()
+    if not clean_slug:
+        return _json(_error("invalid_input", "slug is required"))
+    params = urllib.parse.urlencode({"locale": _normalize_locale(locale)})
+    safe_slug = urllib.parse.quote(clean_slug, safe="")
+    return _json(_request_json("GET", f"/api/cards/{safe_slug}?{params}", locale=locale))
+
+
+def handle_card_match(
+    query: str,
+    limit: int = 5,
+    include_protocol: bool = True,
+    locale: str = "es",
+    category: str = "",
+    business_type: str = "",
+) -> str:
+    """Find official protocol cards for a user request.
+
+    Use this before non-trivial work when available. Protocols are fetched from
+    the authenticated backend at runtime; this package does not embed them.
+    """
+    clean_query = str(query or "").strip()
+    if not clean_query:
+        return _json(_error("invalid_input", "query is required"))
+    body = {
+        "query": clean_query,
+        "limit": max(1, min(20, _as_int(limit, 5))),
+        "include_protocol": _as_bool(include_protocol, True),
+        "locale": _normalize_locale(locale),
+    }
+    if category:
+        body["category"] = str(category).strip()
+    if business_type:
+        body["business_type"] = str(business_type).strip()
+    return _json(_request_json("POST", "/api/cards/match", body=body, locale=locale))
+
+
+TOOLS = [
+    (handle_card_catalog, "nexo_card_catalog", "List visible official NEXO protocol cards from the authenticated backend. Does not return protocol text."),
+    (handle_card_get, "nexo_card_get", "Fetch one official NEXO protocol card by slug from the authenticated backend, including protocol text."),
+    (handle_card_match, "nexo_card_match", "Find the official NEXO protocol card for a user request. Call before non-trivial work when available."),
+]

package/templates/CLAUDE.md.template

@@ -30,13 +30,14 @@ Claude Code may list `mcp__nexo__*` tools as **deferred** at session start (name
 - Diagnostic plane: `nexo_doctor plane='installation_live'` inspects client/install surfaces — consult it when tools appear missing on a fresh install.
 <!-- nexo:end:tools_at_startup -->
 
-## Protocol (6 rules)
+## Protocol (7 rules)
 1. `nexo_startup` once per session and keep the returned `SID`.
 2. `nexo_heartbeat` on every user message.
 3. `nexo_task_open` for any non-trivial work. For `edit` / `execute` / `delegate`, this is the default path. If the work is long multi-step or likely to cross messages/sessions, also open `nexo_workflow_open` and keep it updated. If task_open surfaces blocking conditioned-file learnings, review them and acknowledge guard before any write / delete step.
-4. Do not say `done`, `fixed`, or `sent` without evidence captured in `nexo_task_close`.
-5. If a correction revealed a reusable pattern, capture or supersede the learning immediately so contradictory rules do not remain active.
-6. On clear end-of-session intent, write the diary before replying.
+4. If `nexo_card_match` is available, call it before non-trivial user-facing creation/analysis work. If it returns an official protocol, follow it silently; if unavailable or no match, continue normally.
+5. Do not say `done`, `fixed`, or `sent` without evidence captured in `nexo_task_close`.
+6. If a correction revealed a reusable pattern, capture or supersede the learning immediately so contradictory rules do not remain active.
+7. On clear end-of-session intent, write the diary before replying.
 
 ## Response Pacing
 - After the first relevant tool or artifact result, reply with the answer immediately instead of silently chaining more investigation.

package/templates/CODEX.AGENTS.md.template

@@ -25,13 +25,14 @@ Codex (and Claude Code) may list `mcp__nexo__*` tools as **deferred** at session
 - If discovery still cannot resolve a `nexo_*` tool, then (and only then) treat it as a real runtime gap and surface it as a blocker.
 - Diagnostic plane: `nexo_doctor plane='installation_live'` inspects client/install surfaces — consult it when tools appear missing on a fresh install.
 
-## Protocol (6 rules)
+## Protocol (7 rules)
 1. `nexo_startup` once per session, then keep the returned `SID`.
 2. `nexo_heartbeat` on every user message.
 3. `nexo_task_open` for any non-trivial work. For `edit` / `execute` / `delegate`, this is the default path. If the work is long multi-step or likely to cross messages/sessions, also open `nexo_workflow_open` and keep it updated. If task_open surfaces blocking conditioned-file learnings, review them and acknowledge guard before any write / delete step.
-4. Do not say `done`, `fixed`, or `sent` without evidence captured in `nexo_task_close`.
-5. If a correction revealed a reusable pattern, capture or supersede the learning immediately so contradictory rules do not remain active.
-6. On clear end-of-session intent, write the diary before replying.
+4. If `nexo_card_match` is available, call it before non-trivial user-facing creation/analysis work. If it returns an official protocol, follow it silently; if unavailable or no match, continue normally.
+5. Do not say `done`, `fixed`, or `sent` without evidence captured in `nexo_task_close`.
+6. If a correction revealed a reusable pattern, capture or supersede the learning immediately so contradictory rules do not remain active.
+7. On clear end-of-session intent, write the diary before replying.
 
 ## Response Pacing
 - After the first relevant tool or artifact result, answer immediately instead of silently chaining more investigation.

package/templates/core-prompts/server-mcp-instructions.md

@@ -7,6 +7,7 @@
 - **Diagnostic plane (MANDATORY before diagnosing NEXO):** fix the plane explicitly first — `product_public`, `runtime_personal`, `installation_live`, `database_real`, or `cooperator`. Do not mix product, runtime, install, DB, and agent-behavior explanations in the same diagnosis.
 - **Guard (MANDATORY before ANY code edit):** `nexo_guard_check(files='...', area='...')` BEFORE editing code. No exceptions. Blocking rules→resolve first. `nexo_track(sid=SID, paths=[...])` before shared files
 - **Skills (MANDATORY before multi-step tasks):** `nexo_skill_match(task)` to find reusable procedures. If match found, read it and follow the steps. After completion, `nexo_skill_result(id, success, context)` to record outcome.
+- **Official protocol cards (MANDATORY when available):** before non-trivial user-facing creation/analysis work, call `nexo_card_match(query=...)`. If it returns a protocol, follow it silently. The protocol text is served by the authenticated backend and is not embedded in Brain.
 - **Learnings (MANDATORY on corrections):** When you discover a bug, pattern, or get corrected→`nexo_learning_add` IMMEDIATELY. Do NOT batch. Do NOT wait until end of session.
 
 ## Rules

package/tool-enforcement-map.json

@@ -315,6 +315,55 @@
       },
       "triggers_after": []
     },
+    "nexo_card_catalog": {
+      "description": "List visible official protocol cards from backend",
+      "category": "protocol_cards",
+      "source": "plugin:cards",
+      "requires": [],
+      "provides": [
+        "official_protocol_card_catalog"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_card_get": {
+      "description": "Fetch one official protocol card from backend",
+      "category": "protocol_cards",
+      "source": "plugin:cards",
+      "requires": [
+        "desktop_auth_token"
+      ],
+      "provides": [
+        "official_protocol_card"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_card_match": {
+      "description": "Match user request to an official protocol card from backend",
+      "category": "protocol_cards",
+      "source": "plugin:cards",
+      "requires": [
+        "desktop_auth_token"
+      ],
+      "provides": [
+        "official_protocol_card_match"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
     "nexo_change_commit": {
       "description": "Link change log entry to git commit",
       "category": "change_log",