nexo-brain 6.0.2 → 6.0.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "6.0.2",
+  "version": "6.0.4",
   "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 `6.0.2` is the current packaged-runtime line: adds the reserved caller prefix `personal/*` so scripts living in `~/.nexo/scripts/` can invoke the automation backend with their own caller id without editing `src/resonance_map.py`. New kwarg `tier` (`"maximo"` / `"alto"` / `"medio"` / `"bajo"`) on `run_automation_prompt`, `run_automation_interactive`, `nexo_helper.run_automation_text`, `nexo_helper.run_automation_json`, and `nexo-agent-run.py --tier`. Precedence for `personal/*` callers: explicit `tier=` → explicit `reasoning_effort=` → `calibration.preferences.default_resonance` → `DEFAULT_RESONANCE` (`alto`). Registered callers keep their behaviour unchanged. New guide: [`docs/personal-scripts-guide.md`](docs/personal-scripts-guide.md).
+Version `6.0.4` is the current packaged-runtime line: `nexo chat` and the dashboard's "Open followup in Terminal" action now honour `preferences.default_resonance`. Pre-v6.0.4 both launchers picked `--model` / `--effort` straight from `config/schedule.json`'s `client_runtime_profiles`, so users who switched their Resonance in NEXO Desktop Preferences (Alto → writes `brain/calibration.json`) kept getting the stale tier cached in the legacy profile — usually `max`. A new `_resolve_interactive_model_and_effort(caller, backend, ...)` helper consults `resonance_map.resolve_model_and_effort` first and falls back to `client_runtime_profiles` only when the resonance contract is missing. `nexo_followup_terminal` joins `nexo_chat` / `desktop_new_session` / `nexo_update_interactive` in `USER_FACING_CALLERS` so the dashboard launcher resolves against the user's preference.
+
+Previously in `6.0.2`: adds the reserved caller prefix `personal/*` so scripts living in `~/.nexo/scripts/` can invoke the automation backend with their own caller id without editing `src/resonance_map.py`. New kwarg `tier` (`"maximo"` / `"alto"` / `"medio"` / `"bajo"`) on `run_automation_prompt`, `run_automation_interactive`, `nexo_helper.run_automation_text`, `nexo_helper.run_automation_json`, and `nexo-agent-run.py --tier`. Precedence for `personal/*` callers: explicit `tier=` → explicit `reasoning_effort=` → `calibration.preferences.default_resonance` → `DEFAULT_RESONANCE` (`alto`). Registered callers keep their behaviour unchanged. New guide: [`docs/personal-scripts-guide.md`](docs/personal-scripts-guide.md).
 
 Previously in `6.0.1`: hotfix on top of the 6.0.0 release. `protocol_settings.py` now treats the process as interactive when **either** stdin+stdout are TTYs **or** `NEXO_INTERACTIVE=1` is exported — closes the gap where NEXO Desktop 0.12.0 spawned `claude` through pipes and Brain fell back to `lenient` even with a human in the loop. The `PostToolUse` hook also gains an inbox autodetect stage: when the session has unread `nexo_send` messages and has gone 60s+ without a heartbeat, it emits a `systemMessage` asking the agent to run `nexo_heartbeat` and consume them. Rate-limited to one reminder per minute per SID (new `hook_inbox_reminders` table, migration m42). Added `sessions.last_heartbeat_ts`, stamped by every successful heartbeat. `NEXO_INTERACTIVE` is an internal Brain↔Electron contract — not user-facing, not a resurrection of the removed `NEXO_PROTOCOL_STRICTNESS`.
 

package/bin/nexo-brain.js

@@ -235,7 +235,6 @@ function getCoreRuntimeFlatFiles(srcDir = path.join(__dirname, "..", "src")) {
     "runtime_power.py",
     "requirements.txt",
     "model_defaults.json",
-    "resonance_tiers.json",
   ];
   const discoveredRootModules = fs.existsSync(srcDir)
     ? fs.readdirSync(srcDir)
@@ -257,6 +256,29 @@ function getCoreRuntimePackages() {
   return ["db", "cognitive", "doctor"];
 }
 
+// Brain contracts — files the NEXO Brain publishes to consumers like
+// NEXO Desktop under ~/.nexo/brain/. These are NOT code (they live outside
+// getCoreRuntimeFlatFiles for that reason) but data contracts with a stable
+// path that external clients read. Keep in sync with docs/contracts/.
+function publishBrainContracts(srcDir = path.join(__dirname, "..", "src"), nexoHome = NEXO_HOME) {
+  const brainDir = path.join(nexoHome, "brain");
+  fs.mkdirSync(brainDir, { recursive: true });
+  const contracts = ["resonance_tiers.json"];
+  contracts.forEach((name) => {
+    const src = path.join(srcDir, name);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(brainDir, name));
+    }
+  });
+  // Clean up legacy location: before v6.0.3 the file was written to
+  // NEXO_HOME/resonance_tiers.json. Remove it so only the contract path
+  // remains authoritative.
+  const legacy = path.join(nexoHome, "resonance_tiers.json");
+  if (fs.existsSync(legacy)) {
+    try { fs.unlinkSync(legacy); } catch (_) { /* best-effort */ }
+  }
+}
+
 function resolveLaunchAgentPath(home) {
   const parts = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin",
     path.join(home, ".local/bin"), path.join(home, ".nexo/bin")];
@@ -1654,6 +1676,8 @@ async function main() {
             copyDirRec(pkgSrc, path.join(NEXO_HOME, pkg));
           }
         });
+        // Publish Brain contracts to ~/.nexo/brain/ (read by NEXO Desktop et al.)
+        publishBrainContracts(srcDir, NEXO_HOME);
         log("  Core files updated.");
 
         // Reconcile Python dependencies after updating code (mirrors fresh-install logic)
@@ -2490,6 +2514,9 @@ async function main() {
     }
   });
 
+  // Publish Brain contracts to ~/.nexo/brain/ (read by NEXO Desktop et al.)
+  publishBrainContracts(srcDir, NEXO_HOME);
+
   // Runtime CLI wrapper lives in NEXO_HOME/bin so it survives npx installs.
   const runtimeCli = [
     "#!/usr/bin/env bash",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "6.0.2",
+  "version": "6.0.4",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain \u2014 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/agent_runner.py

@@ -457,16 +457,75 @@ def _interactive_target_cwd(target: str | os.PathLike[str]) -> str:
     return str(Path.cwd())
 
 
+def _resolve_interactive_model_and_effort(
+    caller: str,
+    backend: str,
+    *,
+    preferences: dict | None = None,
+    tier: str | None = None,
+) -> tuple[str, str]:
+    """Return ``(model, effort)`` for an interactive launch.
+
+    v6.0.4 — interactive launchers (nexo chat, dashboard followup) were
+    picking the command flags straight from ``client_runtime_profiles``
+    (config/schedule.json), ignoring the user's ``default_resonance``
+    preference in calibration.json. That meant Preferences → "Alto"
+    never reached ``nexo chat`` even though the same preference was
+    applied correctly in headless runs (run_automation_prompt) and in
+    NEXO Desktop (lib/claude-runtime.js).
+
+    Resolution order (mirrors run_automation_prompt):
+      1. resonance_map → (model, effort) for the registered caller,
+         honouring user_default and the explicit tier override.
+      2. If the resonance_map is unavailable or returns blanks, fall
+         back to ``client_runtime_profiles`` so we stay backward
+         compatible with pre-6.0.0 installs missing resonance_tiers.json.
+    """
+    profile = resolve_client_runtime_profile(backend, preferences=preferences)
+    model = ""
+    effort = ""
+    try:
+        from resonance_map import resolve_model_and_effort
+
+        user_default = ""
+        if isinstance(preferences, dict):
+            user_default = str(preferences.get("default_resonance") or "").strip()
+        explicit_tier = (tier or "").strip() or None
+        mapped_model, mapped_effort = resolve_model_and_effort(
+            caller,
+            backend,
+            user_default=user_default or None,
+            explicit_tier=explicit_tier,
+        )
+        if mapped_model:
+            model = mapped_model
+        if mapped_effort:
+            effort = mapped_effort
+    except Exception:
+        # resonance_map missing or caller not registered — fall back to the
+        # legacy client_runtime_profiles path so nothing explodes.
+        pass
+    if not model:
+        model = profile.get("model", "")
+    if not effort:
+        effort = profile.get("reasoning_effort", "")
+    return model, effort
+
+
 def build_interactive_client_command(
     *,
     target: str | os.PathLike[str],
     client: str | None = None,
     preferences: dict | None = None,
+    caller: str = "nexo_chat",
+    tier: str | None = None,
 ) -> tuple[str, list[str]]:
     prefs = preferences or load_client_preferences()
     selected = resolve_terminal_client(client, preferences=prefs)
     target_path = str(Path(target).expanduser())
-    profile = resolve_client_runtime_profile(selected, preferences=prefs)
+    resolved_model, resolved_effort = _resolve_interactive_model_and_effort(
+        caller, selected, preferences=prefs, tier=tier
+    )
     startup_prompt = _interactive_startup_prompt(selected)
 
     if selected == CLIENT_CLAUDE_CODE:
@@ -476,10 +535,10 @@ def build_interactive_client_command(
                 "Claude Code launcher not found in PATH. Install `claude` first."
             )
         cmd = [claude_bin]
-        if profile["model"]:
-            cmd.extend(["--model", profile["model"]])
-        if profile["reasoning_effort"]:
-            cmd.extend(["--effort", profile["reasoning_effort"]])
+        if resolved_model:
+            cmd.extend(["--model", resolved_model])
+        if resolved_effort:
+            cmd.extend(["--effort", resolved_effort])
         cmd.append("--dangerously-skip-permissions")
         if startup_prompt:
             cmd.append(startup_prompt)
@@ -495,10 +554,10 @@ def build_interactive_client_command(
         bootstrap_prompt = _load_client_bootstrap_prompt(CLIENT_CODEX)
         if bootstrap_prompt and not _codex_managed_initial_messages_enabled():
             cmd.extend(["-c", _codex_initial_messages_config(bootstrap_prompt)])
-        if profile["model"]:
-            cmd.extend(["-m", profile["model"]])
-        if profile["reasoning_effort"]:
-            cmd.extend(["-c", f'model_reasoning_effort="{profile["reasoning_effort"]}"'])
+        if resolved_model:
+            cmd.extend(["-m", resolved_model])
+        if resolved_effort:
+            cmd.extend(["-c", f'model_reasoning_effort="{resolved_effort}"'])
         cmd.extend(["-C", target_path])
         if startup_prompt:
             cmd.append(startup_prompt)
@@ -548,8 +607,14 @@ def run_automation_interactive(
     the interactive surface honours whatever the user selected.
     """
     prefs = preferences or load_client_preferences()
+    # v6.0.4 — caller+tier propagate into the builder so interactive launches
+    # honour default_resonance (previously ignored for nexo chat).
     resolved_client, cmd = build_interactive_client_command(
-        target=target, client=client, preferences=prefs
+        target=target,
+        client=client,
+        preferences=prefs,
+        caller=caller,
+        tier=(tier or "").strip() or None,
     )
     launch_env = os.environ.copy()
     if env:
@@ -616,10 +681,14 @@ def build_followup_terminal_shell_command(
     client: str | None = None,
     preferences: dict | None = None,
     cwd: str | os.PathLike[str] | None = None,
+    caller: str = "nexo_followup_terminal",
+    tier: str | None = None,
 ) -> tuple[str, str]:
     prefs = preferences or load_client_preferences()
     selected = resolve_terminal_client(client, preferences=prefs)
-    profile = resolve_client_runtime_profile(selected, preferences=prefs)
+    resolved_model, resolved_effort = _resolve_interactive_model_and_effort(
+        caller, selected, preferences=prefs, tier=tier
+    )
     prompt = f"NEXO: execute followup from file $(cat {followup_reference})"
 
     if selected == CLIENT_CLAUDE_CODE:
@@ -629,10 +698,10 @@ def build_followup_terminal_shell_command(
                 "Claude Code launcher not found in PATH. Install `claude` first."
             )
         cmd = [claude_bin]
-        if profile["model"]:
-            cmd.extend(["--model", profile["model"]])
-        if profile["reasoning_effort"]:
-            cmd.extend(["--effort", profile["reasoning_effort"]])
+        if resolved_model:
+            cmd.extend(["--model", resolved_model])
+        if resolved_effort:
+            cmd.extend(["--effort", resolved_effort])
         cmd.extend(["--dangerously-skip-permissions", prompt])
         return selected, shlex.join(cmd)
 
@@ -647,10 +716,10 @@ def build_followup_terminal_shell_command(
         bootstrap_prompt = _load_client_bootstrap_prompt(CLIENT_CODEX)
         if bootstrap_prompt and not _codex_managed_initial_messages_enabled():
             cmd.extend(["-c", _codex_initial_messages_config(bootstrap_prompt)])
-        if profile["model"]:
-            cmd.extend(["-m", profile["model"]])
-        if profile["reasoning_effort"]:
-            cmd.extend(["-c", f'model_reasoning_effort="{profile["reasoning_effort"]}"'])
+        if resolved_model:
+            cmd.extend(["-m", resolved_model])
+        if resolved_effort:
+            cmd.extend(["-c", f'model_reasoning_effort="{resolved_effort}"'])
         cmd.extend(["-C", target_cwd, prompt])
         return selected, shlex.join(cmd)
 

package/src/auto_update.py

@@ -973,6 +973,57 @@ def _migrate_effort_to_resonance(dest: Path = NEXO_HOME) -> list[str]:
     return actions
 
 
+def _relocate_resonance_tiers_contract(dest: Path = NEXO_HOME) -> list[str]:
+    """Ensure ``resonance_tiers.json`` lives at the public contract path
+    ``NEXO_HOME/brain/resonance_tiers.json`` and purge the legacy copy at
+    ``NEXO_HOME/resonance_tiers.json``.
+
+    Context: v6.0.0 defined the public contract (read by NEXO Desktop) as
+    ``~/.nexo/brain/resonance_tiers.json`` but the installer kept copying
+    the file to ``~/.nexo/resonance_tiers.json`` (legacy flat-file layout),
+    so Desktop failed with *"NEXO Brain contract missing"* until the user
+    moved the file by hand. v6.0.3 publishes straight to ``brain/`` and
+    this migration reconciles existing runtimes.
+
+    Idempotent: no-op once the contract file is in ``brain/`` and the
+    legacy file is gone. Never raises — migration must not block an update.
+    """
+    actions: list[str] = []
+    brain_dir = dest / "brain"
+    contract_path = brain_dir / "resonance_tiers.json"
+    legacy_path = dest / "resonance_tiers.json"
+
+    try:
+        brain_dir.mkdir(parents=True, exist_ok=True)
+    except Exception as exc:
+        actions.append(f"resonance-contract-relocate-warning:mkdir:{exc.__class__.__name__}")
+        return actions
+
+    # If the contract already exists in brain/, just drop the legacy copy.
+    if contract_path.is_file():
+        if legacy_path.is_file():
+            try:
+                legacy_path.unlink()
+                actions.append("resonance-contract-relocate:legacy-removed")
+            except Exception as exc:
+                actions.append(f"resonance-contract-relocate-warning:unlink:{exc.__class__.__name__}")
+        return actions
+
+    # Contract missing from brain/ — promote the legacy file if present.
+    if legacy_path.is_file():
+        try:
+            contract_path.write_bytes(legacy_path.read_bytes())
+            legacy_path.unlink()
+            actions.append("resonance-contract-relocate:moved-to-brain")
+        except Exception as exc:
+            actions.append(f"resonance-contract-relocate-warning:move:{exc.__class__.__name__}")
+    # If neither exists, the caller (nexo-brain.js publishBrainContracts)
+    # will write it from the package source on the next install pass; nothing
+    # for this Python migration to do.
+
+    return actions
+
+
 def _bootstrap_profile_from_calibration_meta(dest: Path = NEXO_HOME) -> list[str]:
     """Create ``brain/profile.json`` from ``calibration.json`` fields when the
     profile file does not exist yet.
@@ -2894,6 +2945,17 @@ def _run_runtime_post_sync(dest: Path = NEXO_HOME, progress_fn=None) -> tuple[bo
     except Exception as exc:
         actions.append(f"profile-bootstrap-warning:{exc.__class__.__name__}")
 
+    # v6.0.3 — relocate resonance_tiers.json from NEXO_HOME root (pre-v6.0.3
+    # layout) to NEXO_HOME/brain/ (public contract path consumed by
+    # NEXO Desktop). Idempotent; safe no-op once the move is done.
+    try:
+        _emit_progress(progress_fn, "Relocating resonance_tiers contract to brain/...")
+        reloc_actions = _relocate_resonance_tiers_contract(dest)
+        for action in reloc_actions:
+            actions.append(action)
+    except Exception as exc:
+        actions.append(f"resonance-contract-relocate-warning:{exc.__class__.__name__}")
+
     # v6.0.0 purge — drop legacy fields that moved elsewhere in v6.
     # client_runtime_profiles.*.{model,reasoning_effort} → resonance_tiers.json.
     # preferences.protocol_strictness → TTY/no-TTY detection.

package/src/plugins/guard.py

@@ -11,6 +11,55 @@ from pathlib import Path
 from db import get_db, find_similar_learnings, extract_keywords, search_learnings, search_changes
 
 
+def _resolve_active_sid(conn) -> str:
+    """Resolve the SID of the caller invoking this guard check.
+
+    Order of precedence:
+      1. ``NEXO_SID`` env var (headless crons + wrapped CLI set this).
+      2. ``CLAUDE_SESSION_ID`` env var translated via
+         ``sessions.external_session_id`` / ``sessions.claude_session_id``.
+      3. The most-recently-updated session in ``sessions`` (fallback for
+         MCP tool calls where the broker doesn't forward env vars but a
+         single active session exists).
+
+    Returns an empty string if nothing resolves. The caller MUST handle
+    the empty-string case explicitly — persisting ``session_id=""`` was
+    the v6.0.2 bug that left ``missing_file_guard`` blind to successful
+    guard checks.
+    """
+    env_sid = (os.environ.get("NEXO_SID") or "").strip()
+    if env_sid.startswith("nexo-"):
+        return env_sid
+
+    external_candidates = [env_sid] if env_sid else []
+    claude_sid = (os.environ.get("CLAUDE_SESSION_ID") or "").strip()
+    if claude_sid:
+        external_candidates.append(claude_sid)
+    for cand in external_candidates:
+        try:
+            row = conn.execute(
+                "SELECT sid FROM sessions "
+                "WHERE external_session_id = ? OR claude_session_id = ? "
+                "ORDER BY last_update_epoch DESC LIMIT 1",
+                (cand, cand),
+            ).fetchone()
+        except Exception:
+            row = None
+        if row and row["sid"]:
+            return str(row["sid"])
+
+    try:
+        row = conn.execute(
+            "SELECT sid FROM sessions "
+            "ORDER BY last_update_epoch DESC LIMIT 1"
+        ).fetchone()
+    except Exception:
+        row = None
+    if row and row["sid"]:
+        return str(row["sid"])
+    return ""
+
+
 def _split_applies_to(applies_to: str) -> list[str]:
     return [item.strip() for item in str(applies_to or "").split(",") if item.strip()]
 
@@ -370,11 +419,15 @@ def handle_guard_check(files: str = "", area: str = "", include_schemas: str = "
                 (time.time(), lid)
             )
 
-    # Log the guard check
+    # Log the guard check — v6.0.3 fix: resolve the caller's SID instead of
+    # inserting the empty string. Pre-v6.0.3 every row landed with
+    # session_id='' so missing_file_guard could not find the guard call
+    # from hook_guardrails._session_has_guard_check and blocked forever.
+    active_sid = _resolve_active_sid(conn)
     conn.execute(
         "INSERT INTO guard_checks (session_id, files, area, learnings_returned, blocking_rules_returned) "
         "VALUES (?, ?, ?, ?, ?)",
-        ("", files, area, len(result["learnings"]) + len(result["universal_rules"]),
+        (active_sid, files, area, len(result["learnings"]) + len(result["universal_rules"]),
          len(result["blocking_rules"]))
     )
     conn.commit()

package/src/resonance_map.py

@@ -46,6 +46,7 @@ future scripts from silently inheriting the wrong tier.
 from __future__ import annotations
 
 import json
+import os
 from pathlib import Path
 from typing import Tuple
 
@@ -65,7 +66,27 @@ from typing import Tuple
 
 TIERS = ("maximo", "alto", "medio", "bajo")
 
-_RESONANCE_JSON_PATH = Path(__file__).resolve().parent / "resonance_tiers.json"
+# Resolution order for the contract file:
+#   1) ~/.nexo/brain/resonance_tiers.json  (v6.0.3+ public contract path, shared
+#      with NEXO Desktop and any external client)
+#   2) Legacy NEXO_HOME/resonance_tiers.json (pre-v6.0.3 runtime layout)
+#   3) Package source src/resonance_tiers.json (dev checkouts / tests)
+def _resolve_resonance_path() -> Path:
+    nexo_home = os.environ.get("NEXO_HOME") or str(Path.home() / ".nexo")
+    candidates = [
+        Path(nexo_home) / "brain" / "resonance_tiers.json",
+        Path(nexo_home) / "resonance_tiers.json",
+        Path(__file__).resolve().parent / "resonance_tiers.json",
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    # No contract present: return the canonical path so the ValueError raised
+    # at load time points at where the contract should live.
+    return candidates[0]
+
+
+_RESONANCE_JSON_PATH = _resolve_resonance_path()
 
 
 def _normalize_tier_entry(entry: dict) -> dict[str, tuple[str, str]]:
@@ -152,6 +173,10 @@ USER_FACING_CALLERS: dict[str, str] = {
     "nexo_chat": USE_USER_DEFAULT_SENTINEL,
     "desktop_new_session": USE_USER_DEFAULT_SENTINEL,
     "nexo_update_interactive": USE_USER_DEFAULT_SENTINEL,
+    # v6.0.4 — dashboard "Open followup in Terminal" spawns a fresh
+    # interactive Claude/Codex session. Treat it like nexo_chat so the
+    # user's default_resonance preference flows through.
+    "nexo_followup_terminal": USE_USER_DEFAULT_SENTINEL,
 }
 
 # System-owned callers. Grouped thematically for readability.