nexo-brain 6.0.1 → 6.0.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "6.0.1",
+  "version": "6.0.2",
   "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.1` is the current packaged-runtime line: 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`.
+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).
+
+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`.
 
 Previously in `6.0.0`: **BREAKING** tier-only setup. Onboarding asks for one resonance tier (`maximo`/`alto`/`medio`/`bajo`) and that choice drives every backend via `src/resonance_tiers.json`; the per-backend model/effort prompts are gone and the legacy `client_runtime_profiles.{claude_code,codex}.{model,reasoning_effort}` are silently purged from `schedule.json` on upgrade. Protocol strictness is no longer configurable — interactive TTY sessions run `strict`, non-TTY (crons, pipes, tests) run `lenient`; `NEXO_PROTOCOL_STRICTNESS` env, `preferences.protocol_strictness`, and the `default/normal/off/warn/soft` aliases are all removed. `preferences.show_pending_at_start` moves to NEXO Desktop's electron-store. The seven core hooks are now unified behind `src/hooks/manifest.json` (plugin and npm modes read the same file), two new hooks ship (`Notification` for live-session activity and `SubagentStop` for auto-closing stale `protocol_tasks`), and `auto_capture.py` is wired to both `UserPromptSubmit` and `PostToolUse` with a persistent 1h dedup table plus an automatic `nexo_learning_add` on correction matches. `~/.nexo/hooks_status.json` is published after every `registerAllCoreHooks()` so NEXO Desktop ≥0.12.0 can render Hooks activos X/Y. New `nexo-brain --skip` flag aliases `--yes`/`--defaults`. Full suite 1057 passed, 1 skipped.
 
@@ -1145,6 +1147,7 @@ If NEXO Brain is useful to you, consider:
 - **Share your experience** — tell others how you're using cognitive memory in your AI workflows
 - **Contribute** — see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Issues and PRs welcome
 - **Client parity / shared-brain maintenance** — see [docs/client-parity-checklist.md](docs/client-parity-checklist.md)
+- **Writing a personal script that calls the automation backend** — see [docs/personal-scripts-guide.md](docs/personal-scripts-guide.md)
 
 [![Star History Chart](https://api.star-history.com/svg?repos=wazionapps/nexo&type=Date)](https://star-history.com/#wazionapps/nexo&Date)
 

package/package.json

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

@@ -531,6 +531,7 @@ def run_automation_interactive(
     env: dict | None = None,
     preferences: dict | None = None,
     session_type: str = "interactive_chat",
+    tier: str = "",
 ) -> subprocess.CompletedProcess:
     """Launch an interactive Claude/Codex session with automation_runs logging.
 
@@ -564,8 +565,13 @@ def run_automation_interactive(
         user_default = ""
         if isinstance(prefs, dict):
             user_default = str(prefs.get("default_resonance") or "").strip()
+        # v6.0.2 — respect explicit ``tier`` override so personal/* callers
+        # can force a resonance without registering in the core map.
+        explicit_tier_arg = (tier or "").strip() or None
         resonance_tier = resolve_tier_for_caller(
-            caller, user_default=user_default or None
+            caller,
+            user_default=user_default or None,
+            explicit_tier=explicit_tier_arg,
         )
     except Exception:
         resonance_tier = ""
@@ -848,6 +854,7 @@ def run_automation_prompt(
     env: dict | None = None,
     model: str = "",
     reasoning_effort: str = "",
+    tier: str = "",
     timeout: int = 300,
     output_format: str = "",
     append_system_prompt: str = "",
@@ -891,13 +898,22 @@ def run_automation_prompt(
     user_default = ""
     if isinstance(prefs, dict):
         user_default = str(prefs.get("default_resonance") or "").strip()
+    # v6.0.2 — ``tier`` kwarg propagates to the resolver as ``explicit_tier``
+    # so personal/* callers can pin their reasoning budget per-invocation
+    # without editing the registry. Registered callers remain unchanged.
+    explicit_tier_arg = (tier or "").strip() or None
     # This raises UnregisteredCallerError if caller is unknown — the
     # same fail-closed rule we wanted. No silent fallback.
     resonance_tier = resolve_tier_for_caller(
-        caller, user_default=user_default or None
+        caller,
+        user_default=user_default or None,
+        explicit_tier=explicit_tier_arg,
     )
     mapped_model, mapped_effort = resolve_model_and_effort(
-        caller, selected_backend, user_default=user_default or None
+        caller,
+        selected_backend,
+        user_default=user_default or None,
+        explicit_tier=explicit_tier_arg,
     )
     if mapped_model and not model:
         model = mapped_model

package/src/resonance_map.py

@@ -213,6 +213,21 @@ ALL_REGISTERED_CALLERS: frozenset[str] = frozenset(
 )
 
 
+# v6.0.2 — Reserved caller prefix for user-owned personal scripts that live
+# outside this repo (``~/.nexo/scripts/``). Callers matching this prefix
+# bypass the registry entirely: they cannot be required to register because
+# they ship with each operator's own install. Instead, the script passes
+# either an explicit ``tier`` (semantic) or a ``reasoning_effort`` (direct
+# override) — or falls back to the user's ``default_resonance`` preference,
+# and finally to ``DEFAULT_RESONANCE`` as the last line of defence.
+#
+# The prefix is NOT a loophole for new core scripts. Anything inside the
+# ``src/`` tree or shipped via the core manifest continues to require a
+# registered entry. The docs (``docs/personal-scripts-guide.md``) explain
+# the split to any NEXO session helping an operator author a new script.
+PERSONAL_CALLER_PREFIX = "personal/"
+
+
 class UnregisteredCallerError(ValueError):
     """Raised when a caller string is not in the resonance registry.
 
@@ -271,22 +286,55 @@ def _load_user_default_resonance() -> str:
     return ""
 
 
-def resolve_tier_for_caller(caller: str, user_default: str | None = None) -> str:
-    """Return the resonance tier that should apply to ``caller``.
+def _normalise_tier(candidate: str | None) -> str:
+    """Coerce a tier string to canonical lowercase; empty when invalid."""
+    if not candidate:
+        return ""
+    value = str(candidate).strip().lower()
+    return value if value in TIERS else ""
 
-    - User-facing callers resolve to ``user_default`` (or ``DEFAULT_RESONANCE``
-      if the user has no preference recorded).
-    - System-owned callers resolve to their fixed tier.
-    - Unknown callers raise ``UnregisteredCallerError``.
 
-    When ``user_default`` is not passed, the function looks it up from the
-    calibration.json preferences first and schedule.json second.
+def resolve_tier_for_caller(
+    caller: str,
+    user_default: str | None = None,
+    *,
+    explicit_tier: str | None = None,
+) -> str:
+    """Return the resonance tier that should apply to ``caller``.
+
+    Resolution order:
+
+    1. ``caller`` is empty → raise ``UnregisteredCallerError`` (same as v6.0.0).
+    2. ``caller`` starts with ``PERSONAL_CALLER_PREFIX``:
+         a. ``explicit_tier`` if valid — semantic override from the script.
+         b. ``user_default`` if valid — operator's configured default.
+         c. Stored ``preferences.default_resonance`` via the loader.
+         d. ``DEFAULT_RESONANCE`` as the final fallback.
+       The registry is NEVER consulted for personal callers: scripts outside
+       the repo cannot register, and forcing them to pin a tier there would
+       defeat the whole purpose of the ``personal/`` contract.
+    3. User-facing callers: user default → DEFAULT (unchanged).
+    4. System-owned callers: fixed tier (unchanged).
+    5. Anything else: ``UnregisteredCallerError`` (unchanged).
     """
     if not caller:
         raise UnregisteredCallerError(
             "caller= is required. Every automation subprocess must be registered "
             "in src/resonance_map.py so its reasoning budget is deliberate."
         )
+
+    if caller.startswith(PERSONAL_CALLER_PREFIX):
+        explicit = _normalise_tier(explicit_tier)
+        if explicit:
+            return explicit
+        from_user = _normalise_tier(user_default)
+        if from_user:
+            return from_user
+        from_prefs = _normalise_tier(_load_user_default_resonance())
+        if from_prefs:
+            return from_prefs
+        return DEFAULT_RESONANCE
+
     if caller in USER_FACING_CALLERS:
         resolved_default = user_default
         if resolved_default is None:
@@ -308,6 +356,8 @@ def resolve_model_and_effort(
     caller: str,
     backend: str,
     user_default: str | None = None,
+    *,
+    explicit_tier: str | None = None,
 ) -> Tuple[str, str]:
     """Return ``(model, reasoning_effort)`` for ``caller`` on ``backend``.
 
@@ -316,7 +366,9 @@ def resolve_model_and_effort(
     empty pair; the caller is expected to handle that by raising or by
     passing its own explicit model/effort arguments.
     """
-    tier = resolve_tier_for_caller(caller, user_default=user_default)
+    tier = resolve_tier_for_caller(
+        caller, user_default=user_default, explicit_tier=explicit_tier
+    )
     backend_entry = _RESONANCE_TABLE.get(tier, {}).get(backend)
     if backend_entry is None:
         return "", ""

package/src/scripts/nexo-agent-run.py

@@ -33,6 +33,20 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--task-profile", default="", help="Automation task profile: default|fast|balanced|deep")
     parser.add_argument("--model", default="", help="Backend model hint")
     parser.add_argument("--reasoning-effort", default="", help="Backend reasoning effort/profile")
+    parser.add_argument(
+        "--tier",
+        default="",
+        help="Resonance tier — 'maximo'/'alto'/'medio'/'bajo'. "
+             "v6.0.2+ — used by personal/* callers to override the "
+             "resonance without editing src/resonance_map.py.",
+    )
+    parser.add_argument(
+        "--caller",
+        default="",
+        help="Registered caller id (e.g. nexo_chat) or 'personal/<id>' for "
+             "user-owned scripts. Required in practice; empty falls back "
+             "to 'agent_run/generic' for backward compatibility.",
+    )
     parser.add_argument("--timeout", type=int, default=AUTOMATION_SUBPROCESS_TIMEOUT, help="Timeout in seconds")
     parser.add_argument("--output-format", default="text", help="Requested output format")
     parser.add_argument("--allowed-tools", default="", help="Claude-style allowed tools contract")
@@ -52,11 +66,12 @@ def main(argv: list[str] | None = None) -> int:
     try:
         result = run_automation_prompt(
             prompt,
-            caller=getattr(args, "caller", "") or "agent_run/generic",
+            caller=args.caller or "agent_run/generic",
             cwd=args.cwd or None,
             task_profile=args.task_profile,
             model=args.model,
             reasoning_effort=args.reasoning_effort,
+            tier=args.tier,
             timeout=args.timeout,
             output_format=args.output_format,
             append_system_prompt=append_system_prompt,

package/templates/nexo_helper.py

@@ -206,18 +206,29 @@ def run_automation_text(
     allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
     append_system_prompt: str = "",
     include_bootstrap: bool = True,
+    caller: str = "",
+    tier: str = "",
 ) -> 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.
+
+    Personal scripts (those living in ``~/.nexo/scripts/``) should pass
+    ``caller="personal/<descriptive-id>"`` and optionally ``tier="alto"``
+    (or another canonical tier) to pick their resonance without editing the
+    NEXO Brain repo. See ``docs/personal-scripts-guide.md`` for the rules.
     """
     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 caller:
+        cmd.extend(["--caller", caller])
+    if tier:
+        cmd.extend(["--tier", tier])
     if model:
         cmd.extend(["--model", model])
     if reasoning_effort:
@@ -261,13 +272,25 @@ def run_automation_json(
     allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
     append_system_prompt: str = "",
     include_bootstrap: bool = True,
+    caller: str = "",
+    tier: str = "",
 ) -> dict:
-    """Run the configured backend and return a parsed JSON object."""
+    """Run the configured backend and return a parsed JSON object.
+
+    v6.0.2 adds ``caller`` and ``tier`` kwargs so personal scripts
+    (``~/.nexo/scripts/``) can identify themselves and pick a resonance
+    without registering in the core repo. See
+    ``docs/personal-scripts-guide.md``.
+    """
     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 caller:
+        cmd.extend(["--caller", caller])
+    if tier:
+        cmd.extend(["--tier", tier])
     if model:
         cmd.extend(["--model", model])
     if reasoning_effort: