nexo-brain 7.2.0 → 7.4.0

package/src/lifecycle_events.py

@@ -0,0 +1,186 @@
+"""NEXO Brain — canonical lifecycle event handler (v7.4.0).
+
+Companion to nexo-desktop's ConversationLifecycleService. Desktop
+persists every conversation/app transition (close / delete / archive /
+switch / window-close / app-exit) to an append-only NDJSON queue BEFORE
+any UI mutation becomes visible, then calls this handler via the
+``nexo_lifecycle_event`` MCP tool. The handler is strictly idempotent:
+re-delivery of the same ``event_id`` returns ``already_processed``
+without replaying any canonical side effect.
+
+Canonical side effects are intentionally minimal in this first slice:
+
+- ``close`` / ``delete`` / ``archive`` / ``app-exit`` / ``window-close``
+  → mark processed. Diary / stop inside the conversation are driven by
+  Desktop's graceful-close flow (``conv-close`` IPC → nexo CLI) and
+  remain the authority for that per-conversation payload. This table
+  is the durable ledger so the next boot can reconcile.
+- ``switch`` → mark processed. No canonical side effect beyond the
+  audit trail; the ledger still matters for telemetry and guard
+  invariants ("operator switched away from a conversation that still
+  had uncommitted claims").
+
+Return shape matches the plan (lines 94-100):
+
+- ``processed``          first delivery, side effects (if any) done
+- ``already_processed``  duplicate delivery, no re-run
+- ``accepted``           persisted, side effect deferred (not used yet)
+- ``rejected``           malformed input, no persistence
+- ``retryable_error``    transient failure, Desktop should retry
+
+Any row keeps ``delivery_status`` as the latest terminal or retryable
+status so ``nexo_lifecycle_status`` / future reconciliation queries
+can read it directly.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from db import get_db
+
+
+VALID_ACTIONS = {
+    "close",
+    "delete",
+    "archive",
+    "switch",
+    "app-exit",
+    "window-close",
+}
+
+TERMINAL_STATUSES = {"processed", "already_processed", "rejected"}
+_DIARY_TRIGGERING = {"close", "delete", "archive", "app-exit"}
+
+
+def _normalise_payload(obj: Any) -> str:
+    try:
+        return json.dumps(obj or {}, ensure_ascii=False, sort_keys=True)
+    except Exception:
+        return "{}"
+
+
+def record_lifecycle_event(
+    event_id: str,
+    action: str,
+    conversation_id: str,
+    session_id: Optional[str] = None,
+    reason: str = "user_action",
+    payload_snapshot: Optional[Dict[str, Any]] = None,
+    source: str = "desktop",
+    schema_version: int = 1,
+) -> Dict[str, Any]:
+    """Idempotent upsert + process.
+
+    Returns ``{status, event_id, diary_triggered, duplicate}``.
+    """
+    if not event_id or not str(event_id).strip():
+        return {"status": "rejected", "reason": "missing-event-id"}
+    if action not in VALID_ACTIONS:
+        return {"status": "rejected", "reason": f"unknown-action:{action}"}
+    if not conversation_id or not str(conversation_id).strip():
+        return {"status": "rejected", "reason": "missing-conversation-id"}
+
+    conn = get_db()
+    existing = conn.execute(
+        "SELECT delivery_status FROM lifecycle_events WHERE event_id = ?",
+        (str(event_id),),
+    ).fetchone()
+
+    if existing is not None:
+        status = str(existing[0] or "")
+        if status in TERMINAL_STATUSES:
+            return {
+                "status": "already_processed",
+                "event_id": event_id,
+                "duplicate": True,
+                "prior_status": status,
+            }
+        # Non-terminal row (accepted / retryable_error) — flip to processed
+        # now and record the transition.
+        conn.execute(
+            "UPDATE lifecycle_events SET delivery_status = 'processed', "
+            "processed_at = datetime('now'), last_error = NULL "
+            "WHERE event_id = ?",
+            (str(event_id),),
+        )
+        conn.commit()
+        return {
+            "status": "processed",
+            "event_id": event_id,
+            "diary_triggered": action in _DIARY_TRIGGERING,
+            "duplicate": False,
+            "reopened": True,
+        }
+
+    conn.execute(
+        """
+        INSERT INTO lifecycle_events (
+            event_id, schema_version, source, action, conversation_id,
+            session_id, reason, payload_snapshot, delivery_status,
+            retry_count, processed_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'processed', 0, datetime('now'))
+        """,
+        (
+            str(event_id),
+            int(schema_version or 1),
+            str(source or "desktop"),
+            str(action),
+            str(conversation_id),
+            str(session_id) if session_id else None,
+            str(reason or "user_action"),
+            _normalise_payload(payload_snapshot),
+        ),
+    )
+    conn.commit()
+
+    return {
+        "status": "processed",
+        "event_id": event_id,
+        "diary_triggered": action in _DIARY_TRIGGERING,
+        "duplicate": False,
+    }
+
+
+def get_lifecycle_event(event_id: str) -> Optional[Dict[str, Any]]:
+    if not event_id:
+        return None
+    row = get_db().execute(
+        "SELECT event_id, schema_version, source, action, conversation_id, "
+        "session_id, reason, payload_snapshot, delivery_status, retry_count, "
+        "created_at, processed_at, last_error "
+        "FROM lifecycle_events WHERE event_id = ?",
+        (str(event_id),),
+    ).fetchone()
+    if row is None:
+        return None
+    try:
+        payload = json.loads(row[7] or "{}")
+    except Exception:
+        payload = {}
+    return {
+        "event_id": row[0],
+        "schema_version": row[1],
+        "source": row[2],
+        "action": row[3],
+        "conversation_id": row[4],
+        "session_id": row[5],
+        "reason": row[6],
+        "payload_snapshot": payload,
+        "delivery_status": row[8],
+        "retry_count": row[9],
+        "created_at": row[10],
+        "processed_at": row[11],
+        "last_error": row[12],
+    }
+
+
+def list_lifecycle_events_by_status(status: str, limit: int = 100) -> list[Dict[str, Any]]:
+    if not status:
+        return []
+    rows = get_db().execute(
+        "SELECT event_id FROM lifecycle_events "
+        "WHERE delivery_status = ? ORDER BY created_at ASC LIMIT ?",
+        (str(status), int(limit or 100)),
+    ).fetchall()
+    return [e for e in (get_lifecycle_event(r[0]) for r in rows) if e]

package/src/plugins/lifecycle_events.py

@@ -0,0 +1,113 @@
+"""Lifecycle Events MCP plugin — nexo_lifecycle_event tool (v7.4.0).
+
+Exposes the canonical handler as an MCP tool so nexo-desktop's
+ConversationLifecycleService can relay close/delete/archive/app-exit/
+window-close intents to Brain and get a formal acknowledgement.
+
+See src/lifecycle_events.py for the handler contract and
+guardian-claude-desktop-plan.md for the overall architecture.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import lifecycle_events
+
+
+def handle_nexo_lifecycle_event(
+    event_id: str,
+    action: str,
+    conversation_id: str,
+    session_id: str = "",
+    reason: str = "user_action",
+    payload_snapshot: str = "",
+    source: str = "desktop",
+    schema_version: int = 1,
+) -> str:
+    """Record a durable lifecycle event and return the canonical ack.
+
+    Desktop (or any future client) MUST persist the event locally first
+    (NDJSON queue) before calling this tool. The handler is idempotent:
+    re-delivery of the same event_id returns ``already_processed``.
+
+    Args:
+        event_id: UUID minted by the client. Primary idempotency key.
+        action: One of ``close`` / ``delete`` / ``archive`` / ``switch``
+            / ``app-exit`` / ``window-close``.
+        conversation_id: Client-side conversation identifier.
+        session_id: Claude session id that backs the conversation, when
+            known. Optional.
+        reason: Free-form origin tag. Default ``user_action``.
+        payload_snapshot: JSON-encoded snapshot of the conversation at
+            the moment of the click (title, last_message_at, is_active,
+            etc). Accepts an empty string if nothing was snapped.
+        source: Client identifier. Default ``desktop``.
+        schema_version: Event schema version the client emitted. Default 1.
+
+    Returns:
+        JSON string ``{status, event_id, ...}``. ``status`` is one of
+        ``processed`` / ``already_processed`` / ``accepted`` /
+        ``rejected`` / ``retryable_error``.
+    """
+    payload_obj: Any = {}
+    if payload_snapshot:
+        try:
+            parsed = json.loads(payload_snapshot)
+            if isinstance(parsed, dict):
+                payload_obj = parsed
+        except Exception:
+            payload_obj = {"_raw": str(payload_snapshot)[:4096]}
+
+    try:
+        result = lifecycle_events.record_lifecycle_event(
+            event_id=event_id,
+            action=action,
+            conversation_id=conversation_id,
+            session_id=session_id or None,
+            reason=reason or "user_action",
+            payload_snapshot=payload_obj,
+            source=source or "desktop",
+            schema_version=int(schema_version or 1),
+        )
+    except Exception as exc:
+        return json.dumps({
+            "status": "retryable_error",
+            "reason": f"{type(exc).__name__}: {exc}",
+            "handler_threw": True,
+        }, ensure_ascii=False)
+
+    return json.dumps(result, ensure_ascii=False)
+
+
+def handle_nexo_lifecycle_status(event_id: str) -> str:
+    """Read the current delivery_status of a lifecycle event.
+
+    Primarily used by reconciliation at Desktop boot: for each
+    still-pending or retryable event in the local NDJSON queue, ask
+    Brain whether it already processed it (Desktop crashed between the
+    append and the ack) or whether we need to re-submit.
+    """
+    if not event_id:
+        return json.dumps({"status": "rejected", "reason": "missing-event-id"})
+    try:
+        row = lifecycle_events.get_lifecycle_event(event_id)
+    except Exception as exc:
+        return json.dumps({"status": "retryable_error", "reason": f"{type(exc).__name__}: {exc}"})
+    if row is None:
+        return json.dumps({"status": "not_found", "event_id": event_id})
+    return json.dumps(row, ensure_ascii=False)
+
+
+TOOLS = [
+    (
+        handle_nexo_lifecycle_event,
+        "nexo_lifecycle_event",
+        "Record a durable lifecycle event (close/delete/archive/switch/app-exit/window-close) and return a canonical ack.",
+    ),
+    (
+        handle_nexo_lifecycle_status,
+        "nexo_lifecycle_status",
+        "Read the current delivery_status of a lifecycle event. Used by Desktop boot reconciliation.",
+    ),
+]

package/src/presets/entities_universal.json

@@ -103,6 +103,80 @@
         "pattern": "git\\s+(reset\\s+--hard|push\\s+(-f|--force)|clean\\s+-fd?x?)"
       }
     },
+    {
+      "type": "destructive_command",
+      "name": "curl_pipe_shell",
+      "aliases": [
+        "curl | bash",
+        "curl | sh",
+        "wget | bash",
+        "wget | sh"
+      ],
+      "metadata": {
+        "shell": "posix",
+        "severity": "critical",
+        "pattern": "(curl|wget)[^|]*\\|\\s*(sudo\\s+)?(bash|sh|zsh)\\b",
+        "note": "Piping network content straight to shell executes unreviewed code"
+      }
+    },
+    {
+      "type": "destructive_command",
+      "name": "dd_to_device",
+      "aliases": [
+        "dd of=/dev/"
+      ],
+      "metadata": {
+        "shell": "posix",
+        "severity": "critical",
+        "pattern": "\\bdd\\s+.*?\\bof=/dev/\\S+",
+        "note": "dd writing to a block device wipes whatever is there"
+      }
+    },
+    {
+      "type": "destructive_command",
+      "name": "chmod_recursive_wide_open",
+      "aliases": [
+        "chmod -R 777",
+        "chmod -R 666",
+        "chmod -R a+rw"
+      ],
+      "metadata": {
+        "shell": "posix",
+        "severity": "high",
+        "pattern": "\\bchmod\\s+-R\\s+(777|666|a\\+rw)\\b",
+        "note": "Recursive world-writable is almost never intended"
+      }
+    },
+    {
+      "type": "destructive_command",
+      "name": "ssh_remote_overwrite",
+      "aliases": [
+        "ssh host \"cat > file\"",
+        "ssh host \"tee file\"",
+        "ssh host \"sed -i ...\"",
+        "ssh host \"echo ... > file\""
+      ],
+      "metadata": {
+        "shell": "ssh",
+        "severity": "high",
+        "pattern": "\\bssh\\b[^'\"`]*?(?:['\"`])(?:[^'\"`]*?)(?:cat\\s*>>?\\s|tee\\s|sed\\s+-i\\b|echo\\s.*\\s>>?\\s|rm\\s+-\\S*[rRfF])",
+        "note": "Remote-write patterns routed through ssh bypass the local destructive gate"
+      }
+    },
+    {
+      "type": "destructive_command",
+      "name": "scp_rsync_upload",
+      "aliases": [
+        "scp local host:path",
+        "rsync local host:path"
+      ],
+      "metadata": {
+        "shell": "ssh",
+        "severity": "medium",
+        "pattern": "\\b(scp|rsync)\\b[^|&;]*?\\s\\S+\\s+[^:\\s]+:[^\\s]+",
+        "note": "Upload direction mutates remote filesystem"
+      }
+    },
     {
       "type": "legacy_path",
       "name": "claude_hooks_to_nexo",

package/src/scripts/guardian_metrics_aggregate.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""guardian_metrics_aggregate — Plan Consolidado 0.25.
+
+Reads ``~/.nexo/logs/guardian-telemetry.ndjson`` (produced per-enqueue
+by ``guardian_telemetry.log_event``) and the latest drift baseline under
+``~/.nexo/reports/drift-baseline-*.json``, and writes a rolling aggregate
+of KPIs to ``~/.nexo/logs/guardian-metrics.ndjson``.
+
+KPIs (Plan Consolidado 0.25):
+  - capture_rate                           (injected / triggered)
+  - core_rule_violations_per_session       (R13/R14/R16/R25/R30 injects / #sessions)
+  - declared_done_without_evidence_ratio   (R16 hard hits / sessions)
+  - false_positive_correction_rate         (events tagged fp / events total)
+  - avg_minutes_between_guard_check_failures
+
+Pure reader: never writes inside the telemetry file. ``NEXO_HOME`` is
+honoured so tests isolate via tmp_path.
+"""
+from __future__ import annotations
+
+import json
+import os
+import statistics
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable
+
+
+CORE_RULE_IDS = {
+    "R13_pre_edit_guard",
+    "R14_correction_learning",
+    "R16_declared_done",
+    "R25_nora_maria_read_only",
+    "R30_pre_done_evidence_system_prompt",
+}
+
+
+def _nexo_home() -> Path:
+    env = os.environ.get("NEXO_HOME")
+    if env:
+        return Path(env)
+    return Path.home() / ".nexo"
+
+
+def _read_ndjson(path: Path) -> Iterable[dict]:
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    yield json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        return
+
+
+def _read_latest_drift_baseline(home: Path) -> dict | None:
+    reports_dir = home / "reports"
+    if not reports_dir.is_dir():
+        return None
+    candidates = sorted(reports_dir.glob("drift-baseline-*.json"))
+    if not candidates:
+        return None
+    try:
+        return json.loads(candidates[-1].read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def aggregate(home: Path | None = None) -> dict:
+    home = home if home is not None else _nexo_home()
+    telemetry_path = home / "logs" / "guardian-telemetry.ndjson"
+    events = list(_read_ndjson(telemetry_path))
+
+    by_rule: dict[str, dict[str, int]] = {}
+    sessions: set[str] = set()
+    core_violations = 0
+    r16_hard = 0
+    fp_count = 0
+    guard_check_failure_ts: list[float] = []
+
+    for ev in events:
+        rid = str(ev.get("rule_id") or ev.get("rule") or "").strip() or "unknown"
+        event = str(ev.get("event") or "").strip()
+        mode = str(ev.get("mode") or "").strip().lower()
+        session_id = str(ev.get("session_id") or ev.get("sid") or "").strip()
+        if session_id:
+            sessions.add(session_id)
+        bucket = by_rule.setdefault(rid, {"triggered": 0, "injected": 0, "fp": 0})
+        if event in ("trigger", "fire"):
+            bucket["triggered"] += 1
+        elif event in ("enqueue", "inject"):
+            bucket["injected"] += 1
+            bucket["triggered"] += 1
+            if rid in CORE_RULE_IDS:
+                core_violations += 1
+            if rid == "R16_declared_done" and mode == "hard":
+                r16_hard += 1
+        if ev.get("fp") is True:
+            bucket["fp"] += 1
+            fp_count += 1
+        if event == "guard_check_failed":
+            try:
+                guard_check_failure_ts.append(float(ev.get("ts") or 0))
+            except (TypeError, ValueError):
+                pass
+
+    total_triggered = sum(b["triggered"] for b in by_rule.values()) or 0
+    total_injected = sum(b["injected"] for b in by_rule.values()) or 0
+    capture_rate = (total_injected / total_triggered) if total_triggered else 0.0
+
+    guard_check_failure_ts.sort()
+    deltas_min = [
+        (b - a) / 60.0
+        for a, b in zip(guard_check_failure_ts, guard_check_failure_ts[1:])
+        if (b - a) > 0
+    ]
+    avg_min_between = statistics.mean(deltas_min) if deltas_min else None
+
+    n_sessions = len(sessions) or 1
+
+    baseline = _read_latest_drift_baseline(home)
+
+    return {
+        "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "nexo_home": str(home),
+        "events_read": len(events),
+        "sessions_seen": len(sessions),
+        "capture_rate": round(capture_rate, 4),
+        "core_rule_violations_per_session": round(core_violations / n_sessions, 4),
+        "declared_done_without_evidence_ratio": round(r16_hard / n_sessions, 4),
+        "false_positive_correction_rate": round(
+            (fp_count / total_triggered) if total_triggered else 0.0, 4
+        ),
+        "avg_minutes_between_guard_check_failures": avg_min_between,
+        "per_rule": {
+            rid: {
+                "triggered": b["triggered"],
+                "injected": b["injected"],
+                "fp": b["fp"],
+                "baseline_hits": (baseline or {}).get("rule_counts", {}).get(rid, 0),
+            }
+            for rid, b in by_rule.items()
+        },
+        "drift_baseline_source": (
+            str(sorted((home / "reports").glob("drift-baseline-*.json"))[-1])
+            if baseline else None
+        ),
+    }
+
+
+def write_metrics(result: dict, *, home: Path | None = None) -> Path:
+    home = home if home is not None else _nexo_home()
+    logs_dir = home / "logs"
+    logs_dir.mkdir(parents=True, exist_ok=True)
+    path = logs_dir / "guardian-metrics.ndjson"
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(result, ensure_ascii=False) + "\n")
+    return path
+
+
+def main(argv: list[str] | None = None) -> int:
+    result = aggregate()
+    path = write_metrics(result)
+    print(
+        f"guardian_metrics_aggregate: {result['events_read']} events across "
+        f"{result['sessions_seen']} sessions → appended to {path}"
+    )
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main(sys.argv[1:]))