nexo-brain 5.8.2 → 5.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.8.2",
+  "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,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 `5.8.2` is the current packaged-runtime line: 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.
+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.
 

package/package.json

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

package/src/db/_schema.py

@@ -968,6 +968,48 @@ def _m40_classification_columns(conn):
     _migrate_add_index(conn, "idx_reminders_owner", "reminders", "owner")
 
 
+def _m41_automation_sessions_columns(conn):
+    """Extend automation_runs with session-level tracking.
+
+    v5.9.0 introduces two changes to how we record Claude/Codex invocations:
+
+    1. Every caller is now required to pass a ``caller=`` string registered in
+       ``src/resonance_map.py``. Stored in a new ``caller`` column so every
+       row is traceable to the subsystem that started it (deep-sleep/extract,
+       evolution/run, nexo_chat, desktop_new_session, …).
+
+    2. Interactive sessions (``nexo chat`` and Desktop new conversation) no
+       longer bypass the logging path. They record a row at spawn time with
+       ``ended_at IS NULL`` and update it on close. The ``session_type``
+       column distinguishes ``headless`` from ``interactive_chat`` and
+       ``interactive_desktop`` so dashboards can slice the data by invocation
+       shape.
+
+    Migration is idempotent: ``_migrate_add_column`` is a no-op when the
+    column already exists; existing rows get empty / NULL values which is
+    compatible with callers that have not been updated yet.
+    """
+    _migrate_add_column(conn, "automation_runs", "caller", "TEXT DEFAULT ''")
+    _migrate_add_column(
+        conn, "automation_runs", "session_type", "TEXT DEFAULT 'headless'"
+    )
+    _migrate_add_column(conn, "automation_runs", "started_at", "TEXT")
+    _migrate_add_column(conn, "automation_runs", "ended_at", "TEXT")
+    _migrate_add_column(conn, "automation_runs", "pid", "INTEGER")
+    _migrate_add_column(
+        conn, "automation_runs", "resonance_tier", "TEXT DEFAULT ''"
+    )
+    _migrate_add_index(
+        conn, "idx_automation_runs_caller", "automation_runs", "caller"
+    )
+    _migrate_add_index(
+        conn, "idx_automation_runs_session_type", "automation_runs", "session_type"
+    )
+    _migrate_add_index(
+        conn, "idx_automation_runs_started_at", "automation_runs", "started_at"
+    )
+
+
 MIGRATIONS = [
     (1, "learnings_columns", _m1_learnings_columns),
     (2, "followups_reasoning", _m2_followups_reasoning),
@@ -1009,6 +1051,7 @@ MIGRATIONS = [
     (38, "evolution_log_proposal_payload", _m38_evolution_log_proposal_payload),
     (39, "hook_runs", _m39_hook_runs),
     (40, "classification_columns", _m40_classification_columns),
+    (41, "automation_sessions_columns", _m41_automation_sessions_columns),
 ]
 
 

package/src/resonance_map.py

@@ -0,0 +1,247 @@
+"""Central resonance map — single source of truth for (backend, model, effort)
+decisions across every automation caller.
+
+Motivation
+----------
+Before v5.9.0 each caller that wanted to invoke Claude or Codex had to either
+pass explicit model + reasoning_effort arguments or rely on the global defaults
+in ``model_defaults.json``. Global defaults meant every background cron shared
+the same max-effort configuration as the interactive ``nexo chat``, so batch
+jobs (daily synthesis, postmortem consolidation, gbp posts) burned maximum
+reasoning effort on tasks that didn't need it, while downgrading any single
+default changed behaviour everywhere at once.
+
+This module introduces four **resonance tiers** (``MAXIMO`` / ``ALTO`` /
+``MEDIO`` / ``BAJO``) and maps each tier to a concrete ``(model, effort)`` pair
+per backend. Every caller is labelled in one of two ways:
+
+    - **User-facing callers** (``nexo chat``, Desktop new session, interactive
+      ``nexo update``) use the user's configured default resonance. When the
+      user changes the default via ``nexo preferences --resonance`` or through
+      the Desktop preferences pane, those three entry points adjust.
+
+    - **System-owned callers** (every cron, every background script, every
+      MCP-tool-triggered automation) use a fixed tier we pick per caller based
+      on what the task needs. A quarterly evolution pass that synthesizes
+      ten thousand lines into a new self-improvement plan is ``MAXIMO``. A
+      daily GBP post that needs to produce 200 characters of marketing copy
+      is ``BAJO``. That decision stays in this file and NEVER reads the user
+      default.
+
+If a backend does not offer all four effort settings (e.g. a hypothetical
+model with only ``max`` and ``low``), we collapse adjacent tiers — ``MAXIMO``
+and ``ALTO`` both map to the backend's highest available effort, ``MEDIO``
+and ``BAJO`` to the lowest. If a backend has no effort knob at all, the tier
+still resolves to the same model with an empty effort string; the resonance
+label is then informational only.
+
+Contract
+--------
+Every call into ``run_automation_prompt`` and ``run_automation_interactive``
+MUST pass a ``caller=`` string that is registered here. Callers not in the
+registry raise ``UnregisteredCallerError`` — there is no silent default. This
+forces the resonance decision to be explicit and auditable, and prevents
+future scripts from silently inheriting the wrong tier.
+"""
+from __future__ import annotations
+
+from typing import Tuple
+
+
+# ---------------------------------------------------------------------------
+# Tier → (claude_model, claude_effort, codex_model, codex_effort)
+# ---------------------------------------------------------------------------
+# Keep this table in ONE place. When we promote a new Claude or Codex model,
+# update only this dict — every caller rebalances automatically.
+#
+# If a future backend offers fewer tiers (e.g. only max + low), collapse
+# adjacent tiers onto the closest available effort. MAXIMO + ALTO → highest,
+# MEDIO + BAJO → lowest. If a backend has no effort setting at all, leave
+# the effort string empty.
+
+TIERS = ("maximo", "alto", "medio", "bajo")
+
+_RESONANCE_TABLE: dict[str, dict[str, tuple[str, str]]] = {
+    "maximo": {
+        "claude_code": ("claude-opus-4-7[1m]", "max"),
+        "codex":       ("gpt-5.4", "xhigh"),
+    },
+    "alto": {
+        "claude_code": ("claude-opus-4-7[1m]", "xhigh"),
+        "codex":       ("gpt-5.4", "high"),
+    },
+    "medio": {
+        "claude_code": ("claude-opus-4-7[1m]", "high"),
+        "codex":       ("gpt-5.4", "medium"),
+    },
+    "bajo": {
+        "claude_code": ("claude-opus-4-7[1m]", "medium"),
+        "codex":       ("gpt-5.4", "low"),
+    },
+}
+
+DEFAULT_RESONANCE = "alto"
+
+
+# ---------------------------------------------------------------------------
+# Caller registry
+# ---------------------------------------------------------------------------
+# Every script that calls the automation backend is registered here. Two
+# categories, in two separate dicts so a reviewer can see at a glance which
+# callers follow the user's preference and which are locked by us.
+#
+# USE_USER_DEFAULT → the caller reads the user's configured resonance at
+#                    runtime. Only three callers should ever be in this list:
+#                    the two interactive entry points (terminal chat, Desktop
+#                    new conversation) and the interactive nexo update flow.
+#
+# SYSTEM_OWNED     → the caller runs at whatever tier we deem appropriate
+#                    for its workload, ignoring the user's default. Tier is
+#                    picked for quality of output, not cost: batch jobs that
+#                    synthesize across a lot of data lean ALTO/MAXIMO, jobs
+#                    that apply a fixed transform or produce short copy lean
+#                    MEDIO/BAJO.
+
+USE_USER_DEFAULT_SENTINEL = "__USE_USER_DEFAULT__"
+
+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,
+}
+
+# System-owned callers. Grouped thematically for readability.
+SYSTEM_OWNED_CALLERS: dict[str, str] = {
+    # ---- Evolution and introspection: highest-quality reasoning needed ----
+    "evolution/run":                    "maximo",
+    "reflection":                       "maximo",
+
+    # ---- Deep sleep: extraction and synthesis benefit from quality --------
+    "deep-sleep/extract":               "alto",
+    "deep-sleep/synthesize":            "maximo",
+    "deep-sleep/apply_findings":        "alto",
+    "sleep/nightly":                    "alto",
+    "synthesis/daily":                  "alto",
+
+    # ---- User-facing outputs where quality is visible ---------------------
+    "catchup/morning":                  "alto",
+    "daily_self_audit":                 "alto",
+    "postmortem_consolidator":          "alto",
+    "proactive_dashboard":              "alto",
+    "followup_runner":                  "alto",
+
+    # ---- Defensive / consistency tasks ------------------------------------
+    "immune/scan":                      "medio",
+    "learning_validator":               "medio",
+    "outcome_checker":                  "medio",
+    "check_context":                    "medio",
+
+    # ---- Agent orchestration ----------------------------------------------
+    "agent_run/generic":                "alto",
+
+    # ---- Tooling helpers (short, structured outputs) ----------------------
+    "tools/drive_search":               "medio",
+
+    # ---- Marketing automation ---------------------------------------------
+    # These produce short copy; we could run them at BAJO for speed, but the
+    # output is user-visible on a public surface, so we lean MEDIO for safety
+    # against embarrassing outputs.
+    "gbp/daily_post":                   "medio",
+    "gbp/post_wazion":                  "medio",
+    "gbp/post_psicologa":               "medio",
+    "gbp/monthly_audit":                "medio",
+    "gbp/reviews_watch":                "medio",
+}
+
+ALL_REGISTERED_CALLERS: frozenset[str] = frozenset(
+    list(USER_FACING_CALLERS.keys()) + list(SYSTEM_OWNED_CALLERS.keys())
+)
+
+
+class UnregisteredCallerError(ValueError):
+    """Raised when a caller string is not in the resonance registry.
+
+    Every caller that dispatches an automation subprocess MUST register here.
+    We do not fall back to a default tier silently — that would re-introduce
+    the pre-v5.9.0 problem where the wrong script could inherit the wrong
+    reasoning budget without anyone noticing. The fix for this error is:
+    add an entry to SYSTEM_OWNED_CALLERS (or USER_FACING_CALLERS if it is a
+    genuine interactive entry point) and pick the tier deliberately.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Resolution
+# ---------------------------------------------------------------------------
+
+def resolve_tier_for_caller(caller: str, user_default: str | None = None) -> str:
+    """Return the resonance tier that should apply to ``caller``.
+
+    - 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``.
+    """
+    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 in USER_FACING_CALLERS:
+        tier = (user_default or DEFAULT_RESONANCE).strip().lower()
+        if tier not in TIERS:
+            tier = DEFAULT_RESONANCE
+        return tier
+    if caller in SYSTEM_OWNED_CALLERS:
+        return SYSTEM_OWNED_CALLERS[caller]
+    raise UnregisteredCallerError(
+        f"caller {caller!r} is not registered in resonance_map.py. "
+        "Add it to SYSTEM_OWNED_CALLERS (or USER_FACING_CALLERS if it is an "
+        "interactive entry point) with a deliberate tier."
+    )
+
+
+def resolve_model_and_effort(
+    caller: str,
+    backend: str,
+    user_default: str | None = None,
+) -> Tuple[str, str]:
+    """Return ``(model, reasoning_effort)`` for ``caller`` on ``backend``.
+
+    The ``backend`` key must match the entries in ``_RESONANCE_TABLE`` tier
+    dicts (``claude_code`` or ``codex``). Unknown backends fall back to an
+    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)
+    backend_entry = _RESONANCE_TABLE.get(tier, {}).get(backend)
+    if backend_entry is None:
+        return "", ""
+    return backend_entry
+
+
+def register_system_caller(caller: str, tier: str) -> None:
+    """Test/debug helper: register a caller at runtime.
+
+    Production code must add callers statically to ``SYSTEM_OWNED_CALLERS``
+    at module level so the registry is reviewable. This helper exists so
+    unit tests can exercise ``resolve_*`` against synthetic caller names
+    without mutating the shipped table.
+    """
+    if tier not in TIERS:
+        raise ValueError(f"tier {tier!r} not in {TIERS}")
+    SYSTEM_OWNED_CALLERS[caller] = tier
+    # Rebuild the frozen view so the guard below sees the new caller.
+    global ALL_REGISTERED_CALLERS
+    ALL_REGISTERED_CALLERS = frozenset(
+        list(USER_FACING_CALLERS.keys()) + list(SYSTEM_OWNED_CALLERS.keys())
+    )
+
+
+def unregister_system_caller(caller: str) -> None:
+    """Mirror helper for tests that need to remove what they registered."""
+    SYSTEM_OWNED_CALLERS.pop(caller, None)
+    global ALL_REGISTERED_CALLERS
+    ALL_REGISTERED_CALLERS = frozenset(
+        list(USER_FACING_CALLERS.keys()) + list(SYSTEM_OWNED_CALLERS.keys())
+    )

package/src/scripts/check-context.py

@@ -198,7 +198,7 @@ Rules:
     try:
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="check_context",
             timeout=300,
             output_format="text",
             append_system_prompt="Return exactly one valid JSON object.",

package/src/scripts/deep-sleep/extract.py

@@ -193,7 +193,7 @@ def analyze_session(
 
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="deep-sleep/extract",
             timeout=CLAUDE_TIMEOUT,
             output_format="text",
             append_system_prompt=JSON_SYSTEM_PROMPT,
@@ -224,7 +224,7 @@ def analyze_session(
             )
             convert_result = run_automation_prompt(
                 convert_prompt,
-                model=_USER_MODEL,
+                caller="deep-sleep/extract",
                 timeout=120,
                 output_format="text",
                 append_system_prompt=JSON_SYSTEM_PROMPT,

package/src/scripts/deep-sleep/synthesize.py

@@ -241,7 +241,7 @@ def main():
     try:
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="deep-sleep/synthesize",
             timeout=CLAUDE_TIMEOUT,
             output_format="text",
             allowed_tools="Read,Grep,Bash",

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

@@ -52,6 +52,7 @@ def main(argv: list[str] | None = None) -> int:
     try:
         result = run_automation_prompt(
             prompt,
+            caller=getattr(args, "caller", "") or "agent_run/generic",
             cwd=args.cwd or None,
             task_profile=args.task_profile,
             model=args.model,

package/src/scripts/nexo-catchup.py

@@ -280,7 +280,7 @@ Format:
     try:
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="catchup/morning",
             timeout=AUTOMATION_SUBPROCESS_TIMEOUT,
             output_format="text",
             allowed_tools="Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*",

package/src/scripts/nexo-daily-self-audit.py

@@ -2050,7 +2050,7 @@ Also write the machine-readable summary to {LOG_DIR}/self-audit-summary.json.
     try:
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="daily_self_audit",
             timeout=AUTOMATION_SUBPROCESS_TIMEOUT,
             output_format="text",
             allowed_tools="Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*",

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

@@ -227,7 +227,7 @@ def call_claude_cli(prompt: str) -> str:
     """Call the configured automation backend for the managed evolution prompt."""
     result = run_automation_prompt(
         prompt,
-        model=_USER_MODEL,
+        caller="evolution/run",
         timeout=CLI_TIMEOUT,
         output_format="text",
         allowed_tools="Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*",
@@ -241,9 +241,9 @@ def call_public_claude_cli(prompt: str, *, cwd: Path) -> str:
     """Run the configured automation backend in an isolated public repo checkout."""
     result = run_automation_prompt(
         prompt,
+        caller="evolution/run",
         cwd=cwd,
         env={"NEXO_PUBLIC_CONTRIBUTION": "1"},
-        model=_USER_MODEL,
         timeout=CLI_TIMEOUT,
         output_format="text",
         allowed_tools="Read,Write,Edit,Glob,Grep,Bash",

package/src/scripts/nexo-immune.py

@@ -916,7 +916,7 @@ Write the report. Be concise — max 40 lines."""
     try:
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="immune/scan",
             timeout=AUTOMATION_SUBPROCESS_TIMEOUT,
             output_format="text",
             allowed_tools="Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*",

package/src/scripts/nexo-learning-validator.py

@@ -158,7 +158,7 @@ Rules:
     try:
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="learning_validator",
             timeout=60,
             output_format="text",
             append_system_prompt=JSON_ONLY_SYSTEM_PROMPT,

package/src/scripts/nexo-postmortem-consolidator.py

@@ -255,7 +255,7 @@ Execute without asking."""
     try:
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="postmortem_consolidator",
             timeout=AUTOMATION_SUBPROCESS_TIMEOUT,
             output_format="text",
             allowed_tools="Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*",

package/src/scripts/nexo-sleep.py

@@ -446,7 +446,7 @@ Execute without asking."""
     try:
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="sleep/nightly",
             timeout=AUTOMATION_SUBPROCESS_TIMEOUT,
             output_format="text",
             allowed_tools="Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*",

package/src/scripts/nexo-synthesis.py

@@ -348,7 +348,7 @@ Execute without asking."""
     try:
         result = run_automation_prompt(
             prompt,
-            model=_USER_MODEL,
+            caller="synthesis/daily",
             timeout=AUTOMATION_SUBPROCESS_TIMEOUT,
             output_format="text",
             allowed_tools="Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*",

package/src/server.py

@@ -63,6 +63,10 @@ from tools_credentials import (
 from tools_task_history import (
     handle_task_log, handle_task_list, handle_task_frequency,
 )
+from tools_automation_sessions import (
+    handle_session_log_create,
+    handle_session_log_close,
+)
 from plugin_loader import load_all_plugins, load_plugin, remove_plugin, list_plugins
 
 
@@ -1375,6 +1379,104 @@ def nexo_drive_dismiss(signal_id: int, reason: str) -> str:
     return handle_drive_dismiss(signal_id, reason)
 
 
+@mcp.tool
+def nexo_session_log_create(
+    caller: str,
+    backend: str,
+    session_type: str = "interactive_desktop",
+    model: str = "",
+    reasoning_effort: str = "",
+    resonance_tier: str = "",
+    cwd: str = "",
+    pid: str = "",
+    context_excerpt: str = "",
+) -> str:
+    """Open an automation_runs row for an interactive Claude/Codex session.
+
+    Designed for clients that spawn Claude/Codex directly (notably NEXO
+    Desktop, which runs a TypeScript process that shells out to the CLI
+    without going through run_automation_prompt). Call this BEFORE
+    spawning the child, store the returned session_id, then call
+    nexo_session_log_close when the session ends.
+
+    Args:
+        caller: Registered caller id (see src/resonance_map.py). For
+                Desktop's "new conversation" button, use
+                "desktop_new_session".
+        backend: "claude_code" or "codex".
+        session_type: "interactive_chat" | "interactive_desktop" — how
+                     the session is shaped. Default "interactive_desktop".
+        model: Concrete model the client resolved, e.g. "claude-opus-4-7[1m]".
+        reasoning_effort: Concrete effort string, e.g. "xhigh".
+        resonance_tier: Tier label ("maximo"/"alto"/"medio"/"bajo"). If
+                        left empty the Brain resolves it from caller.
+        cwd: Working directory the session is anchored to.
+        pid: Child process PID if available.
+        context_excerpt: Optional first-prompt preview (used to size
+                         prompt_chars in telemetry).
+    """
+    import json as _json
+    result = handle_session_log_create(
+        caller=caller,
+        backend=backend,
+        session_type=session_type,
+        model=model,
+        reasoning_effort=reasoning_effort,
+        resonance_tier=resonance_tier,
+        cwd=cwd,
+        pid=pid,
+        context_excerpt=context_excerpt,
+    )
+    return _json.dumps(result, ensure_ascii=False)
+
+
+@mcp.tool
+def nexo_session_log_close(
+    session_id: int,
+    returncode: int = 0,
+    duration_ms: int = 0,
+    input_tokens: int = 0,
+    cached_input_tokens: int = 0,
+    output_tokens: int = 0,
+    total_cost_usd: str = "",
+    telemetry_source: str = "",
+    cost_source: str = "",
+    error: str = "",
+) -> str:
+    """Close an automation_runs row opened by nexo_session_log_create.
+
+    Args:
+        session_id: id returned by the create call.
+        returncode: child exit code (0 = ok).
+        duration_ms: wall-clock duration in milliseconds.
+        input_tokens / cached_input_tokens / output_tokens: client-side
+                     usage counters.
+        total_cost_usd: cost in USD as a string (parsed to float).
+        telemetry_source: short label identifying where the counts came
+                          from ("desktop_stream", "codex_json", ...).
+        cost_source: short label for cost provenance.
+        error: short error message if the session failed.
+    """
+    import json as _json
+    try:
+        cost = float(total_cost_usd) if total_cost_usd else None
+    except ValueError:
+        cost = None
+    result = handle_session_log_close(
+        session_id=session_id,
+        returncode=returncode,
+        duration_ms=duration_ms,
+        input_tokens=input_tokens,
+        cached_input_tokens=cached_input_tokens,
+        output_tokens=output_tokens,
+        total_cost_usd=cost,
+        telemetry_source=telemetry_source,
+        cost_source=cost_source,
+        error=error,
+    )
+    return _json.dumps(result, ensure_ascii=False)
+
+
 if __name__ == "__main__":
     _server_init()
     mcp.run(**_run_kwargs_from_env())

package/src/tools_automation_sessions.py

@@ -0,0 +1,159 @@
+"""MCP tools for automation session logging.
+
+Gives NEXO Desktop (which launches ``claude`` directly, not via
+``agent_runner.run_automation_prompt``) a way to record its interactive
+sessions in the same ``automation_runs`` table as every other backend call.
+
+Two tools:
+
+    nexo_session_log_create  → INSERT a row with ended_at=NULL, return id
+    nexo_session_log_close   → UPDATE the row with exit + duration + tokens
+
+The tools are intentionally thin wrappers over the helpers in
+``agent_runner``. They exist as MCP tools so clients that don't embed the
+Python runtime (Desktop's TypeScript/Electron process, any future
+third-party agent) can still participate in the unified log.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def handle_session_log_create(payload: dict | None = None, **kwargs) -> dict:
+    """Open an automation session row.
+
+    Expected arguments (all optional except ``caller`` and ``backend``):
+        caller          — e.g. "desktop_new_session" (registered in
+                          resonance_map.py).
+        backend         — "claude_code" or "codex".
+        session_type    — "interactive_chat" | "interactive_desktop"
+                          (default: "interactive_desktop").
+        model           — concrete model string, if the client already
+                          resolved it.
+        reasoning_effort — concrete effort string.
+        resonance_tier  — tier label for traceability.
+        cwd             — working directory the session is anchored to.
+        pid             — the child PID if the client already has it.
+        context_excerpt — optional short preview of the first prompt
+                          (truncated to 2048 chars for prompt_chars).
+    """
+    args = payload or kwargs or {}
+    caller = str(args.get("caller") or "").strip()
+    backend = str(args.get("backend") or "").strip()
+    if not caller or not backend:
+        return {
+            "ok": False,
+            "error": "caller and backend are required",
+            "session_id": None,
+        }
+
+    session_type = str(args.get("session_type") or "interactive_desktop").strip()
+    model = str(args.get("model") or "").strip()
+    reasoning_effort = str(args.get("reasoning_effort") or "").strip()
+    resonance_tier = str(args.get("resonance_tier") or "").strip()
+    cwd = Path(str(args.get("cwd") or ".")).expanduser()
+    pid_raw = args.get("pid")
+    try:
+        pid = int(pid_raw) if pid_raw is not None and pid_raw != "" else None
+    except (TypeError, ValueError):
+        pid = None
+
+    context_excerpt = str(args.get("context_excerpt") or "")[:2048]
+
+    # Resolve resonance_tier if client did not pre-compute it.
+    if not resonance_tier and caller:
+        try:
+            from resonance_map import (
+                resolve_tier_for_caller,
+                UnregisteredCallerError,
+            )
+            try:
+                from client_preferences import load_client_preferences
+                prefs = load_client_preferences()
+            except Exception:
+                prefs = {}
+            user_default = ""
+            if isinstance(prefs, dict):
+                user_default = str(prefs.get("default_resonance") or "").strip()
+            try:
+                resonance_tier = resolve_tier_for_caller(
+                    caller, user_default=user_default or None
+                )
+            except UnregisteredCallerError:
+                resonance_tier = ""
+        except Exception:
+            resonance_tier = ""
+
+    from agent_runner import _record_automation_start
+
+    row_id, err = _record_automation_start(
+        caller=caller,
+        backend=backend,
+        session_type=session_type,
+        task_profile="",
+        model=model,
+        reasoning_effort=reasoning_effort,
+        resonance_tier=resonance_tier,
+        cwd=cwd,
+        output_format="interactive",
+        prompt=context_excerpt,
+        pid=pid,
+    )
+    if row_id is None:
+        return {"ok": False, "error": err or "session log insert failed", "session_id": None}
+    return {
+        "ok": True,
+        "session_id": int(row_id),
+        "resonance_tier": resonance_tier,
+    }
+
+
+def handle_session_log_close(payload: dict | None = None, **kwargs) -> dict:
+    """Close an automation session row opened by nexo_session_log_create.
+
+    Expected arguments:
+        session_id    — int returned by the create call.
+        returncode    — exit code (default 0).
+        duration_ms   — total wall-clock duration in ms.
+        input_tokens, cached_input_tokens, output_tokens — counters from
+                         the client's own telemetry, all optional.
+        total_cost_usd — float, optional.
+        telemetry_source — short label ("desktop_stream", "codex_json", ...).
+        error         — short error string if the session failed.
+    """
+    args = payload or kwargs or {}
+    sid_raw = args.get("session_id")
+    try:
+        session_id = int(sid_raw) if sid_raw is not None else None
+    except (TypeError, ValueError):
+        session_id = None
+    if session_id is None:
+        return {"ok": False, "error": "session_id is required"}
+
+    returncode = int(args.get("returncode") or 0)
+    duration_ms = int(args.get("duration_ms") or 0)
+    telemetry = {
+        "usage": {
+            "input_tokens": int(args.get("input_tokens") or 0),
+            "cached_input_tokens": int(args.get("cached_input_tokens") or 0),
+            "output_tokens": int(args.get("output_tokens") or 0),
+        },
+        "total_cost_usd": args.get("total_cost_usd"),
+        "telemetry_source": str(args.get("telemetry_source") or "").strip(),
+        "cost_source": str(args.get("cost_source") or "").strip(),
+        "warnings": [],
+        "raw": {},
+    }
+    err_message = str(args.get("error") or "").strip()
+    if err_message:
+        telemetry["warnings"].append(err_message)
+
+    from agent_runner import _record_automation_end
+
+    ok, err = _record_automation_end(
+        row_id=session_id,
+        returncode=returncode,
+        duration_ms=duration_ms,
+        telemetry=telemetry,
+    )
+    return {"ok": bool(ok), "error": err or ""}

package/src/tools_drive.py

@@ -283,6 +283,7 @@ def _llm_classify_signal(text: str) -> dict:
     try:
         result = run_automation_prompt(
             prompt,
+            caller="tools/drive_search",
             task_profile="fast",
             timeout=_LLM_TIMEOUT_SECONDS,
             output_format="text",