nexo-brain 5.10.2 → 6.0.1

package/hooks/hooks.json

@@ -10,18 +10,8 @@
           },
           {
             "type": "command",
-            "command": "mkdir -p \"${CLAUDE_PLUGIN_DATA}/operations\" && date +%s > \"${CLAUDE_PLUGIN_DATA}/operations/.session-start-ts\"",
-            "timeout": 2
-          },
-          {
-            "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/daily-briefing-check.sh\"",
-            "timeout": 5
-          },
-          {
-            "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/session-start.sh\"",
-            "timeout": 35
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" python3 \"${CLAUDE_PLUGIN_ROOT}/src/hooks/session_start.py\"",
+            "timeout": 40
           }
         ]
       }
@@ -32,87 +22,67 @@
         "hooks": [
           {
             "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/session-stop.sh\"",
-            "timeout": 10
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" python3 \"${CLAUDE_PLUGIN_ROOT}/src/hooks/stop.py\"",
+            "timeout": 15
           }
         ]
       }
     ],
-    "PreToolUse": [
+    "UserPromptSubmit": [
       {
-        "matcher": "Edit|MultiEdit|Write|Delete",
+        "matcher": "*",
         "hooks": [
           {
             "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/protocol-pretool-guardrail.sh\"",
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" python3 \"${CLAUDE_PLUGIN_ROOT}/src/hooks/auto_capture.py\"",
             "timeout": 5
           }
         ]
       }
     ],
-    "UserPromptSubmit": [
+    "PostToolUse": [
       {
         "matcher": "*",
         "hooks": [
           {
             "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/heartbeat-user-msg.sh\"",
-            "timeout": 3
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" python3 \"${CLAUDE_PLUGIN_ROOT}/src/hooks/post_tool_use.py\"",
+            "timeout": 20
           }
         ]
       }
     ],
-    "PostToolUse": [
+    "PreCompact": [
       {
         "matcher": "*",
         "hooks": [
           {
             "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/capture-tool-logs.sh\"",
-            "timeout": 5
-          },
-          {
-            "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/capture-session.sh\"",
-            "timeout": 3
-          },
-          {
-            "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/inbox-hook.sh\"",
-            "timeout": 5
-          },
-          {
-            "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/protocol-guardrail.sh\"",
-            "timeout": 5
-          },
-          {
-            "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/heartbeat-posttool.sh\"",
-            "timeout": 3
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" python3 \"${CLAUDE_PLUGIN_ROOT}/src/hooks/pre_compact.py\"",
+            "timeout": 15
           }
         ]
       }
     ],
-    "PreCompact": [
+    "Notification": [
       {
         "matcher": "*",
         "hooks": [
           {
             "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/pre-compact.sh\"",
-            "timeout": 10
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" python3 \"${CLAUDE_PLUGIN_ROOT}/src/hooks/notification.py\"",
+            "timeout": 3
           }
         ]
       }
     ],
-    "PostCompact": [
+    "SubagentStop": [
       {
         "matcher": "*",
         "hooks": [
           {
             "type": "command",
-            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/post-compact.sh\"",
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" python3 \"${CLAUDE_PLUGIN_ROOT}/src/hooks/subagent_stop.py\"",
             "timeout": 10
           }
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.10.2",
+  "version": "6.0.1",
   "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",
@@ -76,6 +76,8 @@
     "bin/postinstall.js",
     "scripts/sync_release_artifacts.py",
     "src/",
+    "src/resonance_tiers.json",
+    "src/hooks/manifest.json",
     "community/",
     "!src/**/__pycache__",
     "!src/**/*.pyc",

package/src/auto_update.py

@@ -2894,6 +2894,26 @@ def _run_runtime_post_sync(dest: Path = NEXO_HOME, progress_fn=None) -> tuple[bo
     except Exception as exc:
         actions.append(f"profile-bootstrap-warning:{exc.__class__.__name__}")
 
+    # v6.0.0 purge — drop legacy fields that moved elsewhere in v6.
+    # client_runtime_profiles.*.{model,reasoning_effort} → resonance_tiers.json.
+    # preferences.protocol_strictness → TTY/no-TTY detection.
+    # preferences.show_pending_at_start → NEXO Desktop electron-store.
+    # Never re-raises: the update must finish even if purge fails.
+    try:
+        _emit_progress(progress_fn, "Applying v6.0.0 calibration purge...")
+        from calibration_migration import apply_v6_purge
+        v6_result = apply_v6_purge(nexo_home=dest)
+        if v6_result.get("calibration_changed"):
+            actions.append("v6-purge:calibration")
+        if v6_result.get("schedule_changed"):
+            actions.append("v6-purge:schedule")
+        if v6_result.get("seeded_default_resonance"):
+            actions.append("v6-purge:seeded-default-resonance-alto")
+        if v6_result.get("status") == "noop":
+            actions.append("v6-purge:noop")
+    except Exception as exc:
+        actions.append(f"v6-purge-warning:{exc.__class__.__name__}")
+
     _emit_progress(progress_fn, "Verifying runtime imports...")
     verify = subprocess.run(
         [sys.executable, "-c", "import server"],

package/src/calibration_migration.py

@@ -240,3 +240,137 @@ def revert(
     except Exception as exc:
         return {"status": "error", "reason": f"copy failed: {exc}", "path": str(target)}
     return {"status": "reverted", "from": str(backup), "path": str(target)}
+
+
+# ---------------------------------------------------------------------------
+# v6.0.0 purge
+# ---------------------------------------------------------------------------
+# v6.0.0 removed three user-facing knobs whose state now lives elsewhere:
+#   - ``client_runtime_profiles.{claude_code,codex}.{model,reasoning_effort}``
+#     in schedule.json → replaced by resonance_tiers.json (tier is the only
+#     input, model+effort are resolved from the JSON).
+#   - ``preferences.protocol_strictness`` in calibration.json → replaced by
+#     the TTY/no-TTY detection in protocol_settings.py.
+#   - ``preferences.show_pending_at_start`` in calibration.json → moved to
+#     NEXO Desktop's electron-store; Brain no longer reads or writes it.
+#
+# The update path calls ``apply_v6_purge(nexo_home)`` exactly once per
+# upgrade. It never maps legacy values to new ones (that would re-create
+# learning #398, the reasoning_effort=max → maximo footgun) — legacy
+# fields are dropped silently and callers fall back to the canonical
+# defaults (strict or lenient via TTY, tier=alto).
+
+_V6_LEGACY_RUNTIME_KEYS = ("model", "reasoning_effort")
+_V6_LEGACY_PREFS_KEYS = ("protocol_strictness", "show_pending_at_start")
+_V6_DEFAULT_TIER = "alto"
+
+
+def _prune_client_runtime_profiles(schedule: dict) -> bool:
+    """Remove model/reasoning_effort from every client_runtime_profile.
+
+    Leaves the enclosing dict shape intact so downstream schedule.json
+    readers that still iterate ``client_runtime_profiles`` do not need a
+    guard — they just see an empty-ish profile for each client.
+    """
+    changed = False
+    profiles = schedule.get("client_runtime_profiles")
+    if not isinstance(profiles, dict):
+        return False
+    for client, profile in list(profiles.items()):
+        if not isinstance(profile, dict):
+            continue
+        for key in _V6_LEGACY_RUNTIME_KEYS:
+            if key in profile:
+                profile.pop(key, None)
+                changed = True
+    return changed
+
+
+def _prune_calibration_preferences(cal: dict) -> bool:
+    """Drop protocol_strictness and show_pending_at_start from calibration."""
+    changed = False
+    # Pref dict may be absent or non-dict on pathological payloads.
+    prefs = cal.get("preferences")
+    if isinstance(prefs, dict):
+        for key in _V6_LEGACY_PREFS_KEYS:
+            if key in prefs:
+                prefs.pop(key, None)
+                changed = True
+    # Some early v5.x installs wrote protocol_strictness at the top level.
+    for key in _V6_LEGACY_PREFS_KEYS:
+        if key in cal:
+            cal.pop(key, None)
+            changed = True
+    return changed
+
+
+def _ensure_default_resonance(cal: dict) -> bool:
+    """Seed preferences.default_resonance='alto' when the user has none.
+
+    Never overwrites an existing value — respecting a non-default choice
+    is the whole point of making this idempotent.
+    """
+    prefs = cal.setdefault("preferences", {})
+    if not isinstance(prefs, dict):
+        # Reset to a sane shape without losing the rest of the payload.
+        cal["preferences"] = prefs = {}
+    current = str(prefs.get("default_resonance") or "").strip().lower()
+    if current:
+        return False
+    prefs["default_resonance"] = _V6_DEFAULT_TIER
+    return True
+
+
+def apply_v6_purge(
+    nexo_home: Path | None = None,
+    *,
+    dry_run: bool = False,
+) -> dict:
+    """Perform the v6.0.0 migration against an on-disk NEXO_HOME.
+
+    Returns a dict describing what changed. Never raises — the update
+    flow appends the result to the actions trail and keeps going.
+    """
+    home = Path(nexo_home) if nexo_home else Path(
+        __import__("os").environ.get("NEXO_HOME", str(Path.home() / ".nexo"))
+    )
+    result: dict[str, Any] = {
+        "status": "noop",
+        "home": str(home),
+        "calibration_changed": False,
+        "schedule_changed": False,
+        "seeded_default_resonance": False,
+    }
+
+    cal_path = home / "brain" / "calibration.json"
+    sched_path = home / "config" / "schedule.json"
+
+    # --- calibration.json ---
+    if cal_path.is_file():
+        try:
+            cal = json.loads(cal_path.read_text())
+        except Exception:
+            cal = None
+        if isinstance(cal, dict):
+            pruned = _prune_calibration_preferences(cal)
+            seeded = _ensure_default_resonance(cal)
+            if (pruned or seeded) and not dry_run:
+                cal_path.write_text(json.dumps(cal, ensure_ascii=False, indent=2))
+            result["calibration_changed"] = bool(pruned or seeded)
+            result["seeded_default_resonance"] = bool(seeded)
+
+    # --- schedule.json ---
+    if sched_path.is_file():
+        try:
+            sched = json.loads(sched_path.read_text())
+        except Exception:
+            sched = None
+        if isinstance(sched, dict):
+            pruned = _prune_client_runtime_profiles(sched)
+            if pruned and not dry_run:
+                sched_path.write_text(json.dumps(sched, ensure_ascii=False, indent=2))
+            result["schedule_changed"] = bool(pruned)
+
+    if any([result["calibration_changed"], result["schedule_changed"]]):
+        result["status"] = "migrated"
+    return result

package/src/db/__init__.py

@@ -81,6 +81,14 @@ from db._sessions import (
     track_files, untrack_files, get_all_tracked_files,
     send_message, get_inbox,
     ask_question, answer_question, get_pending_questions, check_answer,
+    update_last_heartbeat_ts, get_last_heartbeat_ts,
+    count_pending_inbox_messages, resolve_sid_from_external,
+)
+
+# PostToolUse inbox-reminder rate limit (v6.0.1)
+_hook_inbox_reminders = _load_submodule("db._hook_inbox_reminders")
+from db._hook_inbox_reminders import (
+    get_last_reminder_ts, mark_reminder_sent, reset_reminders_for_sid,
 )
 
 # Reminders and followups

package/src/db/_hook_inbox_reminders.py

@@ -0,0 +1,73 @@
+"""NEXO DB — Hook inbox reminder bookkeeping (v6.0.1).
+
+The ``PostToolUse`` hook may surface a ``systemMessage`` that tells the
+agent it has unread ``nexo_send`` messages when the session has been
+autopiloting through tool calls for a while. This module backs the rate
+limit: at most one reminder per minute per SID, stored in the tiny
+``hook_inbox_reminders`` table created by migration m42.
+
+All helpers are best-effort on the read path and raise on unexpected
+write failures — callers (the hook itself) wrap calls in try/except so
+a malformed DB never breaks the tool pipeline.
+"""
+from __future__ import annotations
+
+from db._core import get_db
+
+
+def get_last_reminder_ts(sid: str) -> float | None:
+    """Return the epoch seconds of the last inbox reminder for ``sid``.
+
+    Returns None when no row exists yet. Never raises — treats any
+    unexpected error as "no prior reminder recorded" so the hook can
+    decide to emit a fresh one.
+    """
+    if not sid:
+        return None
+    try:
+        row = get_db().execute(
+            "SELECT last_reminder_ts FROM hook_inbox_reminders WHERE sid = ?",
+            (sid,),
+        ).fetchone()
+    except Exception:
+        return None
+    if row is None:
+        return None
+    try:
+        return float(row[0]) if row[0] is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def mark_reminder_sent(sid: str, ts: float) -> None:
+    """Record that a reminder was surfaced for ``sid`` at ``ts``.
+
+    Uses SQLite UPSERT so the table tracks one row per SID. Silently
+    swallows DB errors; the hook caller logs / skips as needed.
+    """
+    if not sid:
+        return
+    try:
+        conn = get_db()
+        conn.execute(
+            "INSERT INTO hook_inbox_reminders (sid, last_reminder_ts) "
+            "VALUES (?, ?) "
+            "ON CONFLICT(sid) DO UPDATE SET last_reminder_ts = excluded.last_reminder_ts",
+            (sid, float(ts)),
+        )
+        conn.commit()
+    except Exception:
+        pass
+
+
+def reset_reminders_for_sid(sid: str) -> None:
+    """Delete the reminder row for ``sid``. Used by tests that want to
+    start from a clean slate between assertions."""
+    if not sid:
+        return
+    try:
+        conn = get_db()
+        conn.execute("DELETE FROM hook_inbox_reminders WHERE sid = ?", (sid,))
+        conn.commit()
+    except Exception:
+        pass

package/src/db/_schema.py

@@ -1010,6 +1010,37 @@ def _m41_automation_sessions_columns(conn):
     )
 
 
+def _m42_v6_0_1_hotfix(conn):
+    """v6.0.1 hotfix — last_heartbeat_ts on sessions + hook_inbox_reminders.
+
+    Two surfaces:
+
+    1. ``sessions.last_heartbeat_ts`` is a REAL column holding the epoch
+       seconds of the most recent ``nexo_heartbeat`` call for that SID.
+       The PostToolUse hook uses it to decide whether to emit an
+       inbox-reminder systemMessage on autopilot sessions that have not
+       checked their inbox in a while.
+
+    2. ``hook_inbox_reminders`` is a tiny table storing the last time we
+       surfaced an inbox reminder per SID. The hook reads/writes it to
+       enforce a rate limit of at most one reminder per minute per
+       session, so long streams of tool calls do not spam the user.
+
+    Idempotent by construction: ``_migrate_add_column`` is a no-op when
+    the column exists, ``CREATE TABLE IF NOT EXISTS`` likewise.
+    """
+    _migrate_add_column(conn, "sessions", "last_heartbeat_ts", "REAL")
+    _migrate_add_index(
+        conn, "idx_sessions_last_heartbeat_ts", "sessions", "last_heartbeat_ts"
+    )
+    conn.execute(
+        """CREATE TABLE IF NOT EXISTS hook_inbox_reminders (
+            sid TEXT PRIMARY KEY,
+            last_reminder_ts REAL NOT NULL
+        )"""
+    )
+
+
 MIGRATIONS = [
     (1, "learnings_columns", _m1_learnings_columns),
     (2, "followups_reasoning", _m2_followups_reasoning),
@@ -1052,6 +1083,7 @@ MIGRATIONS = [
     (39, "hook_runs", _m39_hook_runs),
     (40, "classification_columns", _m40_classification_columns),
     (41, "automation_sessions_columns", _m41_automation_sessions_columns),
+    (42, "v6_0_1_hotfix", _m42_v6_0_1_hotfix),
 ]
 
 

package/src/db/_sessions.py

@@ -123,6 +123,110 @@ def clean_stale_sessions() -> int:
     return count
 
 
+def update_last_heartbeat_ts(sid: str, ts: float | None = None) -> None:
+    """Stamp ``sessions.last_heartbeat_ts`` with the current heartbeat time.
+
+    Added in v6.0.1 so the PostToolUse hook can decide whether an
+    autopilot session has gone long enough without a heartbeat to
+    deserve an inbox reminder. Called from ``handle_heartbeat`` after
+    every successful heartbeat. Never raises — treats a missing
+    session row (test harnesses, race on cleanup) as a no-op.
+    """
+    if not sid:
+        return
+    try:
+        sid = _validate_sid(sid)
+    except Exception:
+        return
+    stamp = float(ts) if ts is not None else now_epoch()
+    conn = get_db()
+    try:
+        conn.execute(
+            "UPDATE sessions SET last_heartbeat_ts = ? WHERE sid = ?",
+            (stamp, sid),
+        )
+        conn.commit()
+    except Exception:
+        pass
+
+
+def get_last_heartbeat_ts(sid: str) -> float | None:
+    """Return the epoch seconds of the most recent heartbeat for ``sid``.
+
+    Returns None when either the session does not exist or the column
+    has never been populated (pre-v6.0.1 rows, or a brand-new session
+    that has not yet called ``nexo_heartbeat``). The hook treats None
+    as "too new to reason about" and skips the reminder.
+    """
+    if not sid:
+        return None
+    conn = get_db()
+    try:
+        row = conn.execute(
+            "SELECT last_heartbeat_ts FROM sessions WHERE sid = ?", (sid,)
+        ).fetchone()
+    except Exception:
+        return None
+    if not row:
+        return None
+    try:
+        return float(row["last_heartbeat_ts"]) if row["last_heartbeat_ts"] is not None else None
+    except (TypeError, ValueError, KeyError):
+        return None
+
+
+def count_pending_inbox_messages(sid: str) -> int:
+    """Count unread ``messages`` addressed to ``sid`` (direct or broadcast).
+
+    The concrete read-tracking table is ``message_reads``; a message is
+    "pending" when no row in ``message_reads`` matches ``(message_id, sid)``
+    and the message is not self-sent. Added in v6.0.1 for the PostToolUse
+    inbox-autodetect reminder.
+    """
+    if not sid:
+        return 0
+    try:
+        row = get_db().execute(
+            "SELECT COUNT(*) FROM messages m "
+            "WHERE (m.to_sid = 'all' OR m.to_sid = ?) "
+            "AND m.from_sid != ? "
+            "AND m.id NOT IN (SELECT message_id FROM message_reads WHERE sid = ?)",
+            (sid, sid, sid),
+        ).fetchone()
+    except Exception:
+        return 0
+    if not row:
+        return 0
+    try:
+        return int(row[0])
+    except (TypeError, ValueError):
+        return 0
+
+
+def resolve_sid_from_external(external_id: str) -> str:
+    """Map a Claude Code ``session_id`` back to the NEXO SID we track.
+
+    The PostToolUse hook payload carries the external Claude session id;
+    we want the internal SID to query the messages table. Returns an
+    empty string when no session matches or the external id is empty.
+    """
+    external = (external_id or "").strip()
+    if not external:
+        return ""
+    try:
+        conn = get_db()
+        row = conn.execute(
+            "SELECT sid FROM sessions WHERE external_session_id = ? OR claude_session_id = ? "
+            "ORDER BY last_update_epoch DESC LIMIT 1",
+            (external, external),
+        ).fetchone()
+    except Exception:
+        return ""
+    if row and row["sid"]:
+        return str(row["sid"])
+    return ""
+
+
 def search_sessions(keyword: str) -> list[dict]:
     """Find sessions whose task contains keyword (case-insensitive)."""
     conn = get_db()

package/src/hook_observability.py

@@ -123,6 +123,30 @@ def record_hook_run(
         return 0
 
 
+def record_activity(
+    *,
+    session_id: str = "",
+    activity_type: str = "notification",
+    metadata: dict | None = None,
+) -> int:
+    """Record a lightweight "session is alive" signal.
+
+    Consumed by the Notification hook (added in v6.0.0) and by any other
+    entry point that wants to tell auto_close_sessions "this session is
+    actively doing something, don't prune it". Internally it stores a row
+    in hook_runs with hook_name=f'activity:{activity_type}' so the same
+    observability surface that renders hook health also shows activity
+    pings without needing a second table.
+    """
+    hook_tag = f"activity:{(activity_type or 'generic').strip().lower()}"[:120]
+    return record_hook_run(
+        hook_tag,
+        session_id=session_id,
+        summary=f"{activity_type or 'generic'} activity",
+        metadata=metadata or {"type": activity_type or "generic"},
+    )
+
+
 def list_recent_hook_runs(
     *,
     hours: int = 24,