nexo-brain 5.8.1 → 5.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.8.1",
+  "version": "5.9.0",
   "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,11 @@
 
 [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 `5.8.1` is the current packaged-runtime line: closes a self-reinforcing `launchctl kickstart -k` loop in the watchdog that wedged deep-sleep Phase 2 between 2026-04-14 and 2026-04-17. The cron wrapper now INSERTs an in-flight row (`ended_at=NULL`) at start and traps SIGTERM/INT/HUP to close it with `exit_code=143` instead of vanishing from `cron_runs`. The watchdog interprets in-flight rows as "currently running" and only re-executes after verifying the worker process is dead. `extract.py` classifies CLI failures into transient (`overloaded_error`, rate-limit, timeout, signal — retried next run) and deterministic (skipped after `MAX_POISON_ATTEMPTS`), and passes a slim shared-context (200 head lines + metadata) instead of the full 400+ KB dump. A new `auto_update._heal_deep_sleep_runtime()` repairs existing installs silently on the next `nexo update`: poisoned checkpoints, stale locks, dangling `cron_runs` rows, and bloated `.watchdog-fails` counters.
+Version `5.9.0` is the current packaged-runtime line: every Claude/Codex invocation now flows through a central **resonance map** and a **unified session log**. Four tiers (`MAXIMO` / `ALTO` / `MEDIO` / `BAJO`) each resolve to a concrete `(model, reasoning_effort)` pair per backend. User-facing callers (`nexo chat`, Desktop new conversation, interactive `nexo update`) honour the user's `default_resonance` preference; system-owned callers (deep-sleep, evolution, catchup, GBP posts, …) run at a fixed tier chosen per caller in `src/resonance_map.py` — the user's preference never downgrades a cron we decided needs `MAXIMO`. Unknown callers raise `UnregisteredCallerError`. Migration #41 adds `caller`, `session_type`, `started_at`, `ended_at`, `pid`, `resonance_tier` to `automation_runs`; interactive sessions record a row at spawn (with `ended_at=NULL`) and update it on close, so the Brain now has a single source of truth for every Claude/Codex call regardless of origin. New `nexo preferences --resonance` CLI. New MCP tools `nexo_session_log_create` / `nexo_session_log_close` let NEXO Desktop (which spawns `claude` directly from its TypeScript process) feed the same log.
+
+Previously in `5.8.2`: the Brain core no longer auto-classifies `followups` and `reminders` on behalf of agents. v5.8.0's `classify_task()` heuristic (NEXO-specific ID prefixes `NF-PROTOCOL-*` / `NF-DS-*` / `NF-AUDIT-*`, Spanish user-verbs `debes` / `revisar` / `firmar`, agent keywords `monitor` / `auditoría diaria` / `checkpoint`) was fine for NEXO's own DB but bled convention into every third-party agent plugged into the shared Brain. The core now persists `internal=0` and `owner=NULL` when the caller omits them, and clients that want automatic classification (NEXO Desktop does, via its `_legacyClassifyOwner` helpers) compute it themselves and pass the result. Migration #40 keeps the columns + indexes; rows already backfilled by v5.8.0 keep their values. `normalise_owner` still explicitly rejects the string `"nexo"` so legacy hardcoding cannot sneak back in.
+
+Previously in `5.8.1`: closes a self-reinforcing `launchctl kickstart -k` loop in the watchdog that wedged deep-sleep Phase 2 between 2026-04-14 and 2026-04-17. The cron wrapper now INSERTs an in-flight row (`ended_at=NULL`) at start and traps SIGTERM/INT/HUP to close it with `exit_code=143` instead of vanishing from `cron_runs`. The watchdog interprets in-flight rows as "currently running" and only re-executes after verifying the worker process is dead. `extract.py` classifies CLI failures into transient (`overloaded_error`, rate-limit, timeout, signal — retried next run) and deterministic (skipped after `MAX_POISON_ATTEMPTS`), and passes a slim shared-context (200 head lines + metadata) instead of the full 400+ KB dump. A new `auto_update._heal_deep_sleep_runtime()` repairs existing installs silently on the next `nexo update`: poisoned checkpoints, stale locks, dangling `cron_runs` rows, and bloated `.watchdog-fails` counters.
 
 Previously in `5.8.0`: first-class `internal` and `owner` columns on `followups` and `reminders`. Migration #40 adds both fields with an idempotent one-shot backfill, so the "who does this task belong to?" classification moves from client-side regex (Desktop) to persistent storage every MCP client shares. Taxonomy is intentionally generic — `owner in {user, waiting, agent, shared}` — so third-party agents plugging into the shared Brain can render whatever assistant label they carry without inheriting NEXO branding. `nexo_reminder_create`, `nexo_reminder_update`, `nexo_followup_create`, and `nexo_followup_update` gain optional `internal` and `owner` parameters that win over the default heuristic.
 

package/package.json

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

@@ -180,68 +180,188 @@ def _append_stderr(stderr: str, message: str) -> str:
     return "\n".join(bits) + "\n"
 
 
-def _record_automation_run(
+def _record_automation_start(
     *,
+    caller: str,
     backend: str,
+    session_type: str,
     task_profile: str,
     model: str,
     reasoning_effort: str,
+    resonance_tier: str,
     cwd: Path,
     output_format: str,
     prompt: str,
-    returncode: int,
-    duration_ms: int,
-    telemetry: dict,
-) -> tuple[bool, str]:
+    pid: int | None = None,
+) -> tuple[int | None, str]:
+    """Insert an automation_runs row at START time with ended_at=NULL.
+
+    Returns ``(row_id, error_message)``. Row_id is ``None`` if the insert
+    fails for any reason — callers should degrade gracefully (telemetry is
+    best-effort, never blocking the actual automation call).
+    """
     try:
         from db._core import get_db
     except Exception as exc:
-        return False, f"automation telemetry unavailable: {exc}"
+        return None, f"automation telemetry unavailable: {exc}"
 
     try:
         conn = get_db()
-        usage = telemetry.get("usage") or {}
-        conn.execute(
+        cur = conn.execute(
             """
             INSERT INTO automation_runs (
-                backend, task_profile, model, reasoning_effort, cwd, output_format,
-                prompt_chars, returncode, duration_ms,
-                input_tokens, cached_input_tokens, output_tokens,
-                total_cost_usd, telemetry_source, cost_source, status, metadata
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                caller, backend, session_type, task_profile, model,
+                reasoning_effort, resonance_tier, cwd, output_format,
+                prompt_chars, status, started_at, pid
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', datetime('now'), ?)
             """,
             (
+                caller or "",
                 backend,
+                session_type or "headless",
                 task_profile or "default",
-                model,
-                reasoning_effort,
+                model or "",
+                reasoning_effort or "",
+                resonance_tier or "",
                 str(cwd),
                 output_format or "text",
                 len(prompt or ""),
-                int(returncode),
-                int(duration_ms),
-                int(usage.get("input_tokens") or 0),
-                int(usage.get("cached_input_tokens") or 0),
-                int(usage.get("output_tokens") or 0),
-                telemetry.get("total_cost_usd"),
-                telemetry.get("telemetry_source", ""),
-                telemetry.get("cost_source", ""),
-                "ok" if int(returncode) == 0 else "failed",
-                json.dumps(
-                    {
-                        "warnings": telemetry.get("warnings") or [],
-                        "raw": telemetry.get("raw") or {},
-                    },
-                    ensure_ascii=False,
-                ),
+                int(pid) if pid is not None else None,
             ),
         )
         conn.commit()
+        return int(cur.lastrowid), ""
+    except Exception as exc:
+        return None, f"automation telemetry unavailable: {exc}"
+
+
+def _record_automation_end(
+    *,
+    row_id: int | None,
+    returncode: int,
+    duration_ms: int,
+    telemetry: dict,
+) -> tuple[bool, str]:
+    """Close an automation_runs row opened by _record_automation_start.
+
+    Falls back to a fresh INSERT when ``row_id`` is None so callers that
+    never got a start row (start failed, or pre-v5.9.0 code paths) still
+    leave a completion trace.
+    """
+    try:
+        from db._core import get_db
+    except Exception as exc:
+        return False, f"automation telemetry unavailable: {exc}"
+
+    usage = (telemetry or {}).get("usage") or {}
+    metadata = json.dumps(
+        {
+            "warnings": (telemetry or {}).get("warnings") or [],
+            "raw": (telemetry or {}).get("raw") or {},
+        },
+        ensure_ascii=False,
+    )
+    status = "ok" if int(returncode) == 0 else "failed"
+
+    try:
+        conn = get_db()
+        if row_id is not None:
+            conn.execute(
+                """
+                UPDATE automation_runs
+                   SET returncode=?, duration_ms=?,
+                       input_tokens=?, cached_input_tokens=?, output_tokens=?,
+                       total_cost_usd=?, telemetry_source=?, cost_source=?,
+                       status=?, metadata=?, ended_at=datetime('now')
+                 WHERE id=?
+                """,
+                (
+                    int(returncode),
+                    int(duration_ms),
+                    int(usage.get("input_tokens") or 0),
+                    int(usage.get("cached_input_tokens") or 0),
+                    int(usage.get("output_tokens") or 0),
+                    (telemetry or {}).get("total_cost_usd"),
+                    (telemetry or {}).get("telemetry_source", ""),
+                    (telemetry or {}).get("cost_source", ""),
+                    status,
+                    metadata,
+                    int(row_id),
+                ),
+            )
+        else:
+            conn.execute(
+                """
+                INSERT INTO automation_runs (
+                    backend, task_profile, model, reasoning_effort, cwd,
+                    output_format, prompt_chars, returncode, duration_ms,
+                    input_tokens, cached_input_tokens, output_tokens,
+                    total_cost_usd, telemetry_source, cost_source, status,
+                    metadata, ended_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+                """,
+                (
+                    "", "default", "", "", "", "text", 0,
+                    int(returncode),
+                    int(duration_ms),
+                    int(usage.get("input_tokens") or 0),
+                    int(usage.get("cached_input_tokens") or 0),
+                    int(usage.get("output_tokens") or 0),
+                    (telemetry or {}).get("total_cost_usd"),
+                    (telemetry or {}).get("telemetry_source", ""),
+                    (telemetry or {}).get("cost_source", ""),
+                    status,
+                    metadata,
+                ),
+            )
+        conn.commit()
         return True, ""
     except Exception as exc:
         return False, f"automation telemetry unavailable: {exc}"
 
 
+def _record_automation_run(
+    *,
+    backend: str,
+    task_profile: str,
+    model: str,
+    reasoning_effort: str,
+    cwd: Path,
+    output_format: str,
+    prompt: str,
+    returncode: int,
+    duration_ms: int,
+    telemetry: dict,
+    caller: str = "",
+    session_type: str = "headless",
+    resonance_tier: str = "",
+) -> tuple[bool, str]:
+    """Backwards-compatible facade for code paths that record in a single
+    shot (no separate start row). Prefer the split start/end pair going
+    forward so interactive sessions and long-running jobs can be seen
+    while they are still in flight."""
+    row_id, err = _record_automation_start(
+        caller=caller,
+        backend=backend,
+        session_type=session_type,
+        task_profile=task_profile,
+        model=model,
+        reasoning_effort=reasoning_effort,
+        resonance_tier=resonance_tier,
+        cwd=cwd,
+        output_format=output_format,
+        prompt=prompt,
+    )
+    if err and row_id is None:
+        pass  # fall through, end will insert a single row
+    return _record_automation_end(
+        row_id=row_id,
+        returncode=returncode,
+        duration_ms=duration_ms,
+        telemetry=telemetry,
+    )
+
+
 def _resolve_claude_cli() -> str:
     saved = NEXO_HOME / "config" / "claude-cli-path"
     if saved.exists():
@@ -394,11 +514,94 @@ def launch_interactive_client(
     env: dict | None = None,
     preferences: dict | None = None,
 ) -> subprocess.CompletedProcess:
-    _, cmd = build_interactive_client_command(target=target, client=client, preferences=preferences)
+    return run_automation_interactive(
+        caller="nexo_chat",
+        target=target,
+        client=client,
+        env=env,
+        preferences=preferences,
+    )
+
+
+def run_automation_interactive(
+    *,
+    caller: str,
+    target: str | os.PathLike[str],
+    client: str | None = None,
+    env: dict | None = None,
+    preferences: dict | None = None,
+    session_type: str = "interactive_chat",
+) -> subprocess.CompletedProcess:
+    """Launch an interactive Claude/Codex session with automation_runs logging.
+
+    Unlike ``run_automation_prompt`` the child inherits stdin/stdout/stderr
+    from the current terminal so the user can carry a normal conversation.
+    We still record the run in the ``automation_runs`` table: a row is
+    INSERTed at spawn time with ``ended_at IS NULL`` and UPDATEd when the
+    session exits. Rows that die before the UPDATE (crash, kill -9) can be
+    reconciled later by the watchdog via the ``pid`` column.
+
+    ``caller`` must be registered in ``src/resonance_map.py`` (typically
+    ``nexo_chat``, ``desktop_new_session``, or ``nexo_update_interactive``).
+    The resonance tier resolves through the user's default preference so
+    the interactive surface honours whatever the user selected.
+    """
+    prefs = preferences or load_client_preferences()
+    resolved_client, cmd = build_interactive_client_command(
+        target=target, client=client, preferences=prefs
+    )
     launch_env = os.environ.copy()
     if env:
         launch_env.update(env)
-    return subprocess.run(cmd, env=launch_env, cwd=_interactive_target_cwd(target))
+    cwd_path = Path(_interactive_target_cwd(target))
+
+    # Best-effort resonance lookup — interactive sessions do not swap the
+    # command (the user chose Claude or Codex explicitly), but we still
+    # record which tier they are running at so telemetry is honest.
+    resonance_tier = ""
+    try:
+        from resonance_map import resolve_tier_for_caller
+        user_default = ""
+        if isinstance(prefs, dict):
+            user_default = str(prefs.get("default_resonance") or "").strip()
+        resonance_tier = resolve_tier_for_caller(
+            caller, user_default=user_default or None
+        )
+    except Exception:
+        resonance_tier = ""
+
+    # model / effort come from the pre-built command; we don't replay them
+    # here (build_interactive_client_command already embedded them).
+    row_id, _record_err = _record_automation_start(
+        caller=caller,
+        backend=resolved_client,
+        session_type=session_type,
+        task_profile="",
+        model="",
+        reasoning_effort="",
+        resonance_tier=resonance_tier,
+        cwd=cwd_path,
+        output_format="interactive",
+        prompt="",
+    )
+
+    started_wall = time.perf_counter()
+    try:
+        result = subprocess.run(cmd, env=launch_env, cwd=str(cwd_path))
+    finally:
+        duration_ms = int((time.perf_counter() - started_wall) * 1000)
+        try:
+            _record_automation_end(
+                row_id=row_id,
+                returncode=getattr(result, "returncode", -1)
+                if "result" in locals()
+                else -1,
+                duration_ms=duration_ms,
+                telemetry={},
+            )
+        except Exception:
+            pass
+    return result
 
 
 def build_followup_terminal_shell_command(
@@ -592,6 +795,7 @@ def _build_enforcement_system_prompt() -> str:
 def run_automation_prompt(
     prompt: str,
     *,
+    caller: str = "",
     backend: str | None = None,
     task_profile: str = "",
     cwd: str | os.PathLike[str] | None = None,
@@ -618,6 +822,36 @@ def run_automation_prompt(
             reasoning_effort = profile["reasoning_effort"]
     selected_backend = _resolve_available_backend(selected_backend, preferences=prefs)
 
+    # Resonance map takes over model+effort decisions when the caller is
+    # registered. Explicit model/effort arguments still win (required for
+    # edge cases like the fallback JSON-conversion call inside extract.py
+    # that asks a shorter/cheaper follow-up).
+    resonance_tier = ""
+    if caller and not model and not reasoning_effort:
+        try:
+            from resonance_map import (
+                resolve_model_and_effort,
+                resolve_tier_for_caller,
+                UnregisteredCallerError,
+            )
+            user_default = ""
+            if isinstance(prefs, dict):
+                user_default = str(prefs.get("default_resonance") or "").strip()
+            resonance_tier = resolve_tier_for_caller(
+                caller, user_default=user_default or None
+            )
+            mapped_model, mapped_effort = resolve_model_and_effort(
+                caller, selected_backend, user_default=user_default or None
+            )
+            if mapped_model:
+                model = mapped_model
+            if mapped_effort:
+                reasoning_effort = mapped_effort
+        except (ImportError, UnregisteredCallerError):
+            # Unknown caller during a transitional release: fall back to
+            # the legacy task_profile / model_defaults resolution below.
+            pass
+
     enforcement_fragment = _build_enforcement_system_prompt()
     if enforcement_fragment:
         if append_system_prompt:
@@ -698,6 +932,9 @@ def run_automation_prompt(
             returncode=result.returncode,
             duration_ms=int((time.perf_counter() - started_at) * 1000),
             telemetry=telemetry,
+            caller=caller,
+            session_type="headless",
+            resonance_tier=resonance_tier,
         )
         stderr = result.stderr or ""
         if not recorded:

package/src/cli.py

@@ -1099,6 +1099,63 @@ def _clients_sync(args):
     return 0 if result.get("ok") else 1
 
 
+def _preferences(args):
+    """Read or change user preferences stored in schedule.json.
+
+    Today this manages ``default_resonance``. Other knobs (default_client,
+    autonomy level, etc.) can be added here instead of spreading across
+    one-off flags.
+    """
+    from client_preferences import (
+        load_client_preferences,
+        save_client_preferences,
+    )
+    from resonance_map import DEFAULT_RESONANCE, TIERS
+
+    prefs = load_client_preferences()
+    if not isinstance(prefs, dict):
+        prefs = {}
+
+    if args.resonance:
+        tier = args.resonance.lower()
+        if tier not in TIERS:
+            print(
+                f"[NEXO] Unknown resonance tier '{args.resonance}'. "
+                f"Valid values: {', '.join(TIERS)}.",
+                file=sys.stderr,
+            )
+            return 2
+        save_client_preferences(default_resonance=tier)
+        prefs = load_client_preferences()
+
+    current_resonance = str(
+        (prefs.get("default_resonance") if isinstance(prefs, dict) else "")
+        or DEFAULT_RESONANCE
+    )
+
+    if args.show or args.resonance:
+        payload = {
+            "default_resonance": current_resonance,
+            "default_resonance_is_explicit": isinstance(prefs, dict)
+                and bool(prefs.get("default_resonance")),
+            "available_tiers": list(TIERS),
+        }
+        if args.json:
+            print(json.dumps(payload, indent=2, ensure_ascii=False))
+        else:
+            print(f"default_resonance = {current_resonance}")
+            if not payload["default_resonance_is_explicit"]:
+                print(f"  (inherited from DEFAULT_RESONANCE; run "
+                      f"`nexo preferences --resonance alto` to set explicitly)")
+        return 0
+
+    # No flag: print usage
+    print("Usage: nexo preferences [--resonance TIER] [--show] [--json]")
+    print(f"  resonance tiers: {', '.join(TIERS)}")
+    print(f"  current default: {current_resonance}")
+    return 0
+
+
 def _contributor_status(args):
     public_contribution = _load_public_contribution_support()
     config = public_contribution["refresh_public_contribution_state"](
@@ -2051,6 +2108,26 @@ def main():
     clients_sync_p = clients_sub.add_parser("sync", help="Sync Claude Code, Claude Desktop, and Codex to the same NEXO brain")
     clients_sync_p.add_argument("--json", action="store_true", help="JSON output")
 
+    # -- preferences --
+    preferences_parser = sub.add_parser(
+        "preferences",
+        help="Read or change NEXO user preferences (resonance, default client, ...)",
+    )
+    preferences_parser.add_argument(
+        "--resonance",
+        choices=["maximo", "alto", "medio", "bajo"],
+        help="Set the default resonance tier for interactive sessions "
+             "(nexo chat, Desktop new conversation, interactive nexo update). "
+             "System-owned callers (deep-sleep, catchup, etc.) ignore this value "
+             "and use the tier hard-coded in resonance_map.py. Default: alto.",
+    )
+    preferences_parser.add_argument(
+        "--show",
+        action="store_true",
+        help="Print the current preferences as JSON and exit.",
+    )
+    preferences_parser.add_argument("--json", action="store_true", help="JSON output")
+
     # -- doctor --
     doctor_parser = sub.add_parser("doctor", help="Unified diagnostics")
     doctor_parser.add_argument("--tier", default="boot", choices=["boot", "runtime", "deep", "all"],
@@ -2245,6 +2322,8 @@ def main():
             return _clients_sync(args)
         clients_parser.print_help()
         return 0
+    elif args.command == "preferences":
+        return _preferences(args)
     elif args.command == "doctor":
         return _doctor(args)
     elif args.command == "contributor":

package/src/client_preferences.py

@@ -494,6 +494,7 @@ def save_client_preferences(
     automation_task_profiles: dict | None = None,
     client_install_preferences: dict | None = None,
     acknowledged_model_recommendations: dict | None = None,
+    default_resonance: str | None = None,
 ) -> Path:
     schedule = apply_client_preferences(
         load_schedule_config(),
@@ -507,6 +508,10 @@ def save_client_preferences(
         client_install_preferences=client_install_preferences,
         acknowledged_model_recommendations=acknowledged_model_recommendations,
     )
+    if default_resonance is not None:
+        tier = str(default_resonance).strip().lower()
+        if tier:
+            schedule["default_resonance"] = tier
     return save_schedule_config(schedule)