nexo-brain 7.1.7 → 7.1.8

package/src/plugins/protocol.py

@@ -972,6 +972,7 @@ def handle_task_open(
     stakes: str = "",
     context_hint: str = "",
     description: str = "",
+    ack_rules: str = "",
 ) -> str:
     """Open a protocol task with heartbeat, guard, rules, and Cortex already captured.
 
@@ -1216,6 +1217,46 @@ def handle_task_open(
         "preventive_followup": preventive_followup,
         "next_action": next_action,
     }
+
+    # G7 (Francisco 2026-04-22): allow inline acknowledgement of blocking
+    # guard rules so the operator does not have to chain a separate
+    # `nexo_task_acknowledge_guard` call. ``ack_rules`` accepts any of:
+    #   "#95,#156"   "95,156"   "95 156"   "[95, 156]"
+    # and delegates to ``handle_task_acknowledge_guard`` which already
+    # validates that every blocking rule is covered.
+    if ack_rules and isinstance(ack_rules, str) and ack_rules.strip():
+        raw = ack_rules.replace("#", "").strip()
+        _resolved_task_id = str(response.get("task_id") or "").strip()
+        _has_blocking = bool(
+            (response.get("guard") or {}).get("has_blocking")
+        )
+        if _has_blocking and _resolved_task_id:
+            ack_result_raw = handle_task_acknowledge_guard(
+                sid=sid,
+                task_id=_resolved_task_id,
+                learning_ids=raw,
+            )
+            try:
+                ack_payload = json.loads(ack_result_raw)
+            except Exception:
+                ack_payload = {"ok": False, "error": "ack_guard_parse_failed"}
+            response["ack_guard"] = ack_payload
+            if ack_payload.get("ok"):
+                # Refresh the blocking flag + next_action so the caller
+                # sees the post-ack state instead of the stale pre-ack one.
+                response["guard"] = response.get("guard") or {}
+                response["guard"]["acknowledged_inline"] = True
+                response["next_action"] = (
+                    "Blocking guard rules acknowledged inline via task_open."
+                )
+        else:
+            response["ack_guard"] = {
+                "ok": False,
+                "skipped": True,
+                "reason": (
+                    "No blocking guard rules on this task — ack_rules had nothing to acknowledge."
+                ),
+            }
     return json.dumps(response, ensure_ascii=False, indent=2)
 
 

package/src/scripts/backfill_task_owner.py

@@ -87,6 +87,70 @@ def _load_user_name(calibration_path: Path) -> str:
         return ""
 
 
+_CLASSIFIER_LABELS = (
+    "user_decision_required",
+    "waiting_for_external_response",
+    "agent_automation_cron",
+    "other_shared",
+)
+_CLASSIFIER_CONFIDENCE_FLOOR = 0.55
+
+
+def _load_local_classifier():
+    """Lazy import the zero-shot classifier. Returns None if unavailable."""
+    try:
+        # classifier_local lives next to the ``scripts`` dir at runtime; add
+        # the parent so both in-repo (``src/``) and installed
+        # (``~/.nexo/core/``) layouts find it.
+        here = Path(__file__).resolve().parent
+        for candidate in (here.parent, here.parent.parent):
+            sys_path = str(candidate)
+            if sys_path not in sys.path:
+                sys.path.insert(0, sys_path)
+        from classifier_local import (  # type: ignore
+            LocalZeroShotClassifier,
+            is_local_classifier_available_with_install_state,
+        )
+    except Exception:
+        return None
+    try:
+        if not is_local_classifier_available_with_install_state():
+            return None
+        return LocalZeroShotClassifier()
+    except Exception:
+        return None
+
+
+def _classify_with_local_llm(description: str, classifier) -> str | None:
+    """Ask the local zero-shot classifier to pick a semantic owner label.
+
+    Returns the mapped owner string ('user', 'waiting', 'agent', 'shared')
+    or None when the classifier is unavailable, low-confidence, or the text
+    is too short to be worth invoking the model. The 40-character floor
+    mirrors classifier_local's own noise-discard threshold and keeps the
+    migration-time batch cheap.
+    """
+    if classifier is None:
+        return None
+    text = (description or "").strip()
+    if len(text) < 40:
+        return None
+    try:
+        result = classifier.classify(text, _CLASSIFIER_LABELS)
+    except Exception:
+        return None
+    if result is None:
+        return None
+    if result.confidence < _CLASSIFIER_CONFIDENCE_FLOOR:
+        return None
+    return {
+        "user_decision_required": "user",
+        "waiting_for_external_response": "waiting",
+        "agent_automation_cron": "agent",
+        "other_shared": "shared",
+    }.get(result.label)
+
+
 def classify(
     *,
     item_id: str,
@@ -94,8 +158,17 @@ def classify(
     category: str,
     recurrence: str,
     user_name: str,
+    classifier=None,
 ) -> str:
-    """Return one of 'user', 'waiting', 'agent', 'shared'."""
+    """Return one of 'user', 'waiting', 'agent', 'shared'.
+
+    The structural signals (id prefix, category, recurrence) stay rule-based
+    because they are unambiguous and cheap. The textual signals (waiting /
+    agent / user intent from the description) prefer the local zero-shot
+    classifier when available; the Spanish/English keyword regexes stay as
+    a graceful fallback so installs without the classifier model still
+    migrate correctly.
+    """
     tid = (item_id or "").strip().lower()
     if tid.startswith("nf-protocol-"):
         return "user"
@@ -110,6 +183,9 @@ def classify(
     desc = description or ""
     desc_low = desc.lower()
 
+    # Operator-name proximity remains a structural signal — if the row
+    # explicitly calls out <OperatorName> deciding/reviewing/etc., we trust
+    # that without burning an LLM call.
     if user_name:
         name_low = user_name.lower()
         user_verbs = "|".join(re.escape(v) for v in _USER_VERBS_ES + _USER_VERBS_EN)
@@ -120,6 +196,10 @@ def classify(
         if name_verb_rx.search(desc_low):
             return "user"
 
+    llm_label = _classify_with_local_llm(desc, classifier)
+    if llm_label is not None:
+        return llm_label
+
     for rx in _compile(_WAITING_PHRASES):
         if rx.search(desc_low):
             return "waiting"
@@ -189,6 +269,10 @@ def run(
     if not db_path.exists():
         raise SystemExit(f"nexo.db not found at {db_path}")
     user_name = _load_user_name(calibration_path)
+    # Load the zero-shot classifier once up front so the migration loop does
+    # not pay repeated import/init overhead. Returns None on installs without
+    # transformers/model — the regex fallback still produces correct owners.
+    classifier = _load_local_classifier()
 
     conn = sqlite3.connect(str(db_path))
     try:
@@ -207,6 +291,7 @@ def run(
                     category=row["category"],
                     recurrence=row["recurrence"],
                     user_name=user_name,
+                    classifier=classifier,
                 )
                 plans.append({"table": table, "id": row["id"], "owner": owner})
 

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

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""Deep Sleep phase: auto-drain stale ``protocol_debt`` rows.
+
+Block K G2 (Francisco 2026-04-22): the debt table accumulates
+``unacknowledged_guard_blocking`` + ``missing_cortex_evaluation`` rows
+faster than the operator can resolve them by hand (20 open in 48h,
+0 auto-resolved). This phase runs nightly and classifies every
+``resolved_at IS NULL`` row into three buckets:
+
+  - ``stale``: older than STALE_AGE_DAYS (default 7) *and* the
+    referenced ``task_id`` either does not exist any more or is
+    closed. Auto-resolved with a ``deep_sleep/stale_auto_drain``
+    resolution note so the morning briefing still shows a clean
+    audit trail.
+  - ``still_valid``: the referenced task is still active. Left
+    untouched — the operator will resolve it alongside the task.
+  - ``requires_user``: newer than STALE_AGE_DAYS, or referenced task
+    is unknown. Emitted as a ``morning_briefing_item`` so the operator
+    sees a consolidated list instead of discovering them one by one.
+
+Design invariants:
+
+  - Idempotent: re-running on the same day re-emits the same set of
+    auto-resolves without double-writing (``resolved_at IS NULL`` filter
+    skips rows already drained).
+  - Read-modify-write wrapped in ``BEGIN IMMEDIATE`` so a concurrent
+    operator writer cannot race-overwrite ``resolved_at``.
+  - Backup-safe: writes an audit JSON to
+    ``runtime/operations/deep-sleep/$DATE-protocol-debt-drain.json``
+    before (and regardless of) mutation so we can always inspect what
+    was drained.
+
+Environment:
+    NEXO_HOME (optional) — root of the NEXO installation.
+    NEXO_DEBT_DRAIN_STALE_DAYS (optional) — override stale cutoff.
+    NEXO_DEBT_DRAIN_DRY_RUN=1 — classify + emit JSON but do not write.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parents[2])))
+if str(NEXO_CODE) not in sys.path:
+    sys.path.insert(0, str(NEXO_CODE))
+
+import paths  # noqa: E402  (sys.path tweaked above)
+
+DEFAULT_STALE_AGE_DAYS = 7
+AUTO_DRAIN_NOTE = "deep_sleep/stale_auto_drain"
+
+
+def _stale_cutoff_days() -> int:
+    raw = os.environ.get("NEXO_DEBT_DRAIN_STALE_DAYS", "").strip()
+    if not raw:
+        return DEFAULT_STALE_AGE_DAYS
+    try:
+        value = int(raw)
+    except ValueError:
+        return DEFAULT_STALE_AGE_DAYS
+    return max(1, value)
+
+
+def _resolve_db_path() -> Path:
+    try:
+        return paths.db_path()
+    except Exception:
+        return NEXO_HOME / "runtime" / "data" / "nexo.db"
+
+
+def _resolve_ops_dir() -> Path:
+    try:
+        return paths.operations_dir() / "deep-sleep"
+    except Exception:
+        return NEXO_HOME / "runtime" / "operations" / "deep-sleep"
+
+
+def _parse_ts(value: str) -> datetime | None:
+    if not value:
+        return None
+    raw = str(value).strip()
+    # Try the three shapes SQLite's ``datetime('now')`` + direct ISO
+    # formatters commonly produce. strptime itself rejects trailing noise,
+    # so there is no need to pre-truncate the input (earlier revisions did
+    # and silently dropped the seconds because ``len('%Y-%m-%d %H:%M:%S')``
+    # is smaller than the rendered value).
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(raw, fmt)
+        except Exception:
+            continue
+    # Some rows drop fractional seconds or timezone — try a lenient fallback
+    # before giving up so we do not over-eagerly bucket them as
+    # requires_user.
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except Exception:
+        return None
+
+
+def _task_is_open(conn: sqlite3.Connection, task_id: str) -> bool | None:
+    """Return True if the task is open, False if closed, None if unknown."""
+    if not task_id:
+        return None
+    try:
+        row = conn.execute(
+            "SELECT status FROM protocol_tasks WHERE task_id = ?",
+            (task_id,),
+        ).fetchone()
+    except sqlite3.OperationalError:
+        return None
+    if row is None:
+        return None
+    status = str(row[0] or "").strip().lower()
+    # ``open`` is the canonical live state. Everything else (``closed``,
+    # ``cancelled``, ``completed``, …) means the task is no longer pinning
+    # the debt.
+    return status == "open"
+
+
+def classify_debt(
+    *,
+    created_at: str,
+    task_id: str,
+    now: datetime,
+    task_open: bool | None,
+    stale_age_days: int,
+) -> str:
+    """Return one of ``stale`` / ``still_valid`` / ``requires_user``.
+
+    Pure function — easy to unit-test without an open DB. Rules:
+
+      - Task known to be open → ``still_valid`` regardless of age (the
+        operator will resolve it together with the task).
+      - Task closed OR task_id absent/unknown AND debt older than
+        ``stale_age_days`` → ``stale`` (auto-drainable).
+      - Anything else → ``requires_user`` (surface in briefing).
+    """
+    if task_open is True:
+        return "still_valid"
+    created_dt = _parse_ts(created_at)
+    if created_dt is None:
+        # Unparseable timestamp: best to surface for the operator rather
+        # than silently discard.
+        return "requires_user"
+    age = now - created_dt
+    if age < timedelta(days=stale_age_days):
+        return "requires_user"
+    # Old enough + task closed/unknown → safe to drain.
+    return "stale"
+
+
+def run(
+    *,
+    db_path: Path | None = None,
+    ops_dir: Path | None = None,
+    stale_age_days: int | None = None,
+    dry_run: bool | None = None,
+    now: datetime | None = None,
+) -> dict:
+    db_path = db_path or _resolve_db_path()
+    ops_dir = ops_dir or _resolve_ops_dir()
+    stale_age_days = stale_age_days if stale_age_days is not None else _stale_cutoff_days()
+    if dry_run is None:
+        dry_run = os.environ.get("NEXO_DEBT_DRAIN_DRY_RUN", "").strip() == "1"
+    now = now or datetime.utcnow()
+
+    report: dict = {
+        "db_path": str(db_path),
+        "stale_age_days": stale_age_days,
+        "dry_run": bool(dry_run),
+        "ran_at": now.strftime("%Y-%m-%d %H:%M:%S"),
+        "totals": {"stale": 0, "still_valid": 0, "requires_user": 0},
+        "drained_ids": [],
+        "requires_user_summary": [],
+    }
+
+    if not db_path.exists():
+        report["error"] = "db_path_missing"
+        return report
+
+    conn = sqlite3.connect(str(db_path))
+    try:
+        conn.row_factory = sqlite3.Row
+        conn.execute("BEGIN IMMEDIATE")
+        rows = conn.execute(
+            "SELECT id, session_id, task_id, debt_type, severity, evidence, created_at "
+            "FROM protocol_debt WHERE resolved_at IS NULL"
+        ).fetchall()
+        by_type: dict[str, int] = {}
+        for row in rows:
+            task_open = _task_is_open(conn, str(row["task_id"] or ""))
+            bucket = classify_debt(
+                created_at=str(row["created_at"] or ""),
+                task_id=str(row["task_id"] or ""),
+                now=now,
+                task_open=task_open,
+                stale_age_days=stale_age_days,
+            )
+            report["totals"][bucket] = report["totals"].get(bucket, 0) + 1
+            if bucket == "stale":
+                report["drained_ids"].append(int(row["id"]))
+                if not dry_run:
+                    conn.execute(
+                        "UPDATE protocol_debt SET resolved_at = ?, resolution = ? "
+                        "WHERE id = ? AND resolved_at IS NULL",
+                        (
+                            now.strftime("%Y-%m-%d %H:%M:%S"),
+                            AUTO_DRAIN_NOTE,
+                            int(row["id"]),
+                        ),
+                    )
+            elif bucket == "requires_user":
+                by_type[str(row["debt_type"])] = by_type.get(str(row["debt_type"]), 0) + 1
+        # Consolidate requires_user into a per-type summary so the morning
+        # briefing stays short even when the backlog is long.
+        report["requires_user_summary"] = [
+            {"debt_type": debt_type, "count": count}
+            for debt_type, count in sorted(by_type.items(), key=lambda x: -x[1])
+        ]
+        if dry_run:
+            conn.execute("ROLLBACK")
+        else:
+            conn.execute("COMMIT")
+    except Exception as exc:
+        try:
+            conn.execute("ROLLBACK")
+        except Exception:
+            pass
+        report["error"] = f"{type(exc).__name__}: {exc}"
+    finally:
+        conn.close()
+
+    # Persist the audit JSON even when drained_ids is empty so the daily
+    # Deep Sleep surface always has a file to reference.
+    try:
+        ops_dir.mkdir(parents=True, exist_ok=True)
+        audit_path = ops_dir / f"{now.strftime('%Y-%m-%d')}-protocol-debt-drain.json"
+        audit_path.write_text(json.dumps(report, indent=2, ensure_ascii=False))
+        report["audit_path"] = str(audit_path)
+    except Exception as exc:
+        report["audit_write_error"] = f"{type(exc).__name__}: {exc}"
+
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    report = run()
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if "error" not in report else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/scripts/nexo_personal_automation.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Stable automation helper that routes prompts through the configured
+NEXO backend (agent_runner / run_automation_text) instead of hardcoding
+provider CLIs such as ``claude -p``.
+
+Block E.6 / NF-DS-857651BA promoted this module from personal/scripts to
+core so every NEXO install exposes the same primitive to its scripts,
+plugins, and skills. The behaviour is unchanged from the personal copy;
+only the import bootstrap learns both layouts:
+
+  - repo checkout (``nexo/src/scripts/…``): ``_repo_root`` is
+    ``nexo/`` and templates live at ``nexo/templates/``.
+  - installed runtime (``~/.nexo/core/scripts/…``): ``_repo_root`` is
+    ``~/.nexo/`` and templates live at ``~/.nexo/templates/``.
+
+Both paths are probed so dev and live operators get identical behaviour.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+_script_dir = Path(__file__).resolve().parent
+_repo_src = _script_dir.parent  # ``src`` in repo, ``core`` in runtime
+_repo_root = _repo_src.parent   # ``nexo`` in repo, ``~/.nexo`` in runtime
+
+if str(_repo_src) not in sys.path:
+    sys.path.insert(0, str(_repo_src))
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+DEFAULT_ALLOWED_TOOLS = "Read,Write,Edit,Glob,Grep,Bash,mcp__nexo__*"
+
+# Templates live next to the code at repo time and at ``~/.nexo/templates``
+# once installed. Probe both and surface whichever exists first so the
+# helper works without the operator having to keep ``NEXO_HOME`` in sync
+# with the repo checkout during development.
+for _candidate in (_repo_root / "templates", NEXO_HOME / "templates"):
+    _cand = str(_candidate)
+    if _candidate.exists() and _cand not in sys.path:
+        sys.path.insert(0, _cand)
+
+try:
+    from client_preferences import resolve_user_model
+    _USER_MODEL = resolve_user_model()
+except Exception:
+    _USER_MODEL = ""
+
+from nexo_helper import run_automation_text as _run_automation_text
+
+
+def run_personal_automation_text(
+    prompt: str,
+    *,
+    model: str = "",
+    cwd: str = "",
+    timeout: int = 21600,
+    allowed_tools: str = DEFAULT_ALLOWED_TOOLS,
+    append_system_prompt: str = "",
+) -> str:
+    """Run ``prompt`` through the configured NEXO automation backend.
+
+    ``model`` empty → use whichever model the operator's calibration has
+    selected (``resolve_user_model``); providers that ignore the field
+    (Claude Code bundled) stay happy with an empty string.
+    ``cwd`` empty → inherit the current working directory.
+    Every other kwarg passes through verbatim.
+    """
+    effective_model = model or _USER_MODEL or "opus"
+    return _run_automation_text(
+        prompt,
+        model=effective_model,
+        cwd=cwd or "",
+        timeout=timeout,
+        allowed_tools=allowed_tools,
+        append_system_prompt=append_system_prompt,
+    )
+
+
+__all__ = [
+    "DEFAULT_ALLOWED_TOOLS",
+    "NEXO_HOME",
+    "run_personal_automation_text",
+]