nexo-brain 7.1.0 → 7.1.2

package/src/autonomy_mandate.py

@@ -0,0 +1,260 @@
+"""Runtime state + enforcement for operator autonomy mandates.
+
+When the operator states `autonomía total`, `sin esperas`, `todo ya`, or an
+equivalent marker, the agent must stop deferring in-scope work to the future
+via `nexo_followup_create`. This module captures that mandate as a small
+JSON state file under `$NEXO_HOME/runtime/data/autonomy_mandate.json`, and
+exposes helpers the CRUD layer uses before creating a followup.
+
+Design notes:
+
+* State is session-scoped, not global — the mandate decays when the session
+  ends or after `DEFAULT_TTL_SECONDS` whichever comes first.
+* Detection is intentionally simple (substring match on a marker list). The
+  S4 incident that motivated this guardrail only needed a coarse trigger.
+* The block is surgical: a followup is rejected only when the call pattern
+  matches the procrastination shape the operator flagged (owner=user or
+  date within 7 days). Long-horizon commitments (>7 days) and shared/agent
+  followups pass through, because those are not what the operator was
+  pushing back on.
+* Three explicit exceptions stay allowed even under the mandate:
+  (a) a download >1GB, (b) a credential the operator must physically enter,
+  (c) a presence-dependent session with María or Nora. These are declared
+  by keywords inside `description` or the explicit `exception` kwarg.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from dataclasses import dataclass
+from datetime import date, datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+STATE_PATH = NEXO_HOME / "runtime" / "data" / "autonomy_mandate.json"
+
+# Marker list per NF-DS-45569A27. Case-insensitive substring match.
+MARKERS = (
+    "autonomía total",
+    "autonomia total",
+    "sin esperas",
+    "todo ya",
+    "no esperes",
+    "no te escondas",
+    "llevo 3 veces",
+    "lo quiero ya",
+)
+
+# Default mandate TTL. Longer than a normal working session but short enough
+# that a stale state does not block followups weeks later.
+DEFAULT_TTL_SECONDS = 6 * 60 * 60  # 6h
+
+# Exception keywords — when any appear in the description (or the explicit
+# `exception` parameter), the followup is allowed even under an active
+# mandate.
+EXCEPTION_KEYWORDS = (
+    ">1gb", ">1 gb", "> 1gb", "> 1 gb",
+    "large download", "descarga grande",
+    "credential", "credencial", "operator must enter",
+    "el operador introduce", "api key rotation",
+    "maría", "maria",
+    "nora",
+    "sesión presencial", "sesion presencial", "in-person",
+)
+
+PROCRASTINATION_WINDOW_DAYS = 7
+
+
+@dataclass
+class MandateState:
+    active: bool
+    session_id: str
+    set_at: float
+    expires_at: float
+    marker: str
+    source: str
+
+    def remaining_seconds(self, now: Optional[float] = None) -> float:
+        now = time.time() if now is None else now
+        return max(0.0, self.expires_at - now)
+
+    def to_dict(self) -> dict:
+        return {
+            "active": self.active,
+            "session_id": self.session_id,
+            "set_at": self.set_at,
+            "expires_at": self.expires_at,
+            "marker": self.marker,
+            "source": self.source,
+        }
+
+
+def _detect_marker(text: str) -> Optional[str]:
+    if not text:
+        return None
+    lowered = text.lower()
+    for marker in MARKERS:
+        if marker in lowered:
+            return marker
+    return None
+
+
+def _ensure_dir() -> None:
+    STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+
+def load_state() -> Optional[MandateState]:
+    """Return the current mandate state or None if absent/expired."""
+    try:
+        raw = json.loads(STATE_PATH.read_text())
+    except FileNotFoundError:
+        return None
+    except (OSError, json.JSONDecodeError):
+        return None
+    try:
+        st = MandateState(
+            active=bool(raw.get("active")),
+            session_id=str(raw.get("session_id", "")),
+            set_at=float(raw.get("set_at", 0.0)),
+            expires_at=float(raw.get("expires_at", 0.0)),
+            marker=str(raw.get("marker", "")),
+            source=str(raw.get("source", "")),
+        )
+    except (TypeError, ValueError):
+        return None
+    if not st.active or st.expires_at <= time.time():
+        return None
+    return st
+
+
+def set_mandate(
+    session_id: str,
+    marker: str,
+    source: str = "manual",
+    ttl_seconds: int = DEFAULT_TTL_SECONDS,
+) -> MandateState:
+    _ensure_dir()
+    now = time.time()
+    st = MandateState(
+        active=True,
+        session_id=str(session_id or "").strip(),
+        set_at=now,
+        expires_at=now + max(60, int(ttl_seconds)),
+        marker=marker,
+        source=source,
+    )
+    STATE_PATH.write_text(json.dumps(st.to_dict(), ensure_ascii=False, indent=2))
+    return st
+
+
+def clear_mandate() -> None:
+    try:
+        STATE_PATH.unlink()
+    except FileNotFoundError:
+        pass
+
+
+def maybe_ingest_from_text(
+    text: str,
+    session_id: str,
+    source: str = "auto",
+    ttl_seconds: int = DEFAULT_TTL_SECONDS,
+) -> Optional[MandateState]:
+    """Scan free-form text for a mandate marker and persist if found.
+
+    Used by heartbeat / hook paths that capture operator messages so the
+    mandate can be set transparently, without a separate explicit tool.
+    Returns the new state when a marker was detected, otherwise None.
+    """
+    marker = _detect_marker(text or "")
+    if not marker:
+        return None
+    return set_mandate(
+        session_id=session_id,
+        marker=marker,
+        source=source,
+        ttl_seconds=ttl_seconds,
+    )
+
+
+def _description_has_exception(description: str, exception: str) -> bool:
+    haystack = f"{description or ''}\n{exception or ''}".lower()
+    return any(kw in haystack for kw in EXCEPTION_KEYWORDS)
+
+
+def _parse_target_date(raw: str) -> Optional[date]:
+    if not raw:
+        return None
+    m = re.match(r"(\d{4})-(\d{2})-(\d{2})", raw.strip())
+    if not m:
+        return None
+    try:
+        return date(int(m.group(1)), int(m.group(2)), int(m.group(3)))
+    except ValueError:
+        return None
+
+
+def _days_until(target: date, today: Optional[date] = None) -> int:
+    today = today or datetime.now(timezone.utc).date()
+    return (target - today).days
+
+
+def check_followup_against_mandate(
+    *,
+    owner: str = "",
+    date: str = "",
+    description: str = "",
+    exception: str = "",
+    state: Optional[MandateState] = None,
+) -> Optional[str]:
+    """Return a human-readable error string when the followup should be
+    rejected under an active mandate, otherwise None.
+
+    The caller is responsible for turning the string into a tool-level
+    error. `state` is injectable for tests; production callers leave it
+    None so the current on-disk state is consulted.
+    """
+    st = state if state is not None else load_state()
+    if st is None:
+        return None
+
+    if _description_has_exception(description, exception):
+        return None
+
+    owner_norm = (owner or "").strip().lower()
+    offending_owner = owner_norm == "user"
+
+    target = _parse_target_date(date)
+    within_window = False
+    if target is not None:
+        days = _days_until(target)
+        if 0 <= days < PROCRASTINATION_WINDOW_DAYS:
+            within_window = True
+
+    if not (offending_owner or within_window):
+        return None
+
+    reasons = []
+    if offending_owner:
+        reasons.append("owner=user")
+    if within_window:
+        reasons.append(f"date within {PROCRASTINATION_WINDOW_DAYS} days")
+
+    lines = [
+        "ERROR: Autonomy mandate active — nexo_followup_create blocked.",
+        f"Marker: '{st.marker}' (source={st.source}, session={st.session_id or 'n/a'}).",
+        f"Reason: {' + '.join(reasons)}.",
+        "This followup looks like procrastination inside the current scope.",
+        "Do the work now via nexo_task_open, or promote it to a goal/workflow.",
+        "Exceptions that stay allowed even under the mandate:",
+        "  - Download >1GB that must finish before the next step.",
+        "  - Credential the operator must physically enter.",
+        "  - Presence-dependent session with María or Nora.",
+        "Pass exception='<reason>' or reference one of the keywords in the",
+        "description to override. Do not use force='true' for this.",
+    ]
+    return "\n".join(lines)

package/src/bootstrap_docs.py

@@ -30,6 +30,7 @@ def _resolve_templates_dir(module_file: str | os.PathLike[str]) -> Path:
 
 
 TEMPLATES_DIR = _resolve_templates_dir(__file__)
+DEFAULT_ASSISTANT_NAME = "Nova"
 
 CORE_LABEL = "******CORE******"
 USER_LABEL = "******USER******"
@@ -64,6 +65,16 @@ def _default_nexo_home() -> Path:
     return resolve_nexo_home(os.environ.get("NEXO_HOME", str(_user_home() / ".nexo")))
 
 
+def _read_json_file(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    try:
+        payload = json.loads(path.read_text())
+    except Exception:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
 def _resolve_operator_name(nexo_home: Path, explicit: str = "") -> str:
     explicit = (explicit or "").strip()
     if explicit:
@@ -71,6 +82,16 @@ def _resolve_operator_name(nexo_home: Path, explicit: str = "") -> str:
     env_name = os.environ.get("NEXO_NAME", "").strip()
     if env_name:
         return env_name
+    calibration = _read_json_file(nexo_home / "personal" / "brain" / "calibration.json")
+    user_payload = calibration.get("user")
+    if isinstance(user_payload, dict):
+        candidate = str(user_payload.get("assistant_name", "")).strip()
+        if candidate:
+            return candidate
+    for key in ("assistant_name", "identity", "operator_name"):
+        candidate = str(calibration.get(key, "")).strip()
+        if candidate:
+            return candidate
     version_file = nexo_home / "version.json"
     if version_file.is_file():
         try:
@@ -79,7 +100,7 @@ def _resolve_operator_name(nexo_home: Path, explicit: str = "") -> str:
                 return candidate
         except Exception:
             pass
-    return "NEXO"
+    return DEFAULT_ASSISTANT_NAME
 
 
 def _read_version(text: str, pattern: str) -> str:

package/src/cli.py

@@ -576,6 +576,129 @@ def _scripts_status(args):
     return 0
 
 
+def _automations_list(args):
+    from script_registry import list_operator_automations
+
+    rows = list_operator_automations(include_all=bool(getattr(args, "all", False)))
+    if args.json:
+        print(json.dumps({"ok": True, "automations": rows}, indent=2, ensure_ascii=False))
+        return 0
+    if not rows:
+        print("No automations registered.")
+        return 0
+    for row in rows:
+        state = "enabled" if row.get("enabled", True) else "disabled"
+        availability = "ready" if row.get("available", True) else "setup required"
+        schedule = str(row.get("effective_schedule_label") or row.get("first_schedule_label") or "—")
+        print(f"{row.get('name')} [{state}] · {availability} · {schedule}")
+    return 0
+
+
+def _automations_set_enabled(args, enabled):
+    from script_registry import set_automation_enabled
+
+    result = set_automation_enabled(args.name, enabled)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result.get("ok") else 1
+    if not result.get("ok"):
+        print(result.get("error", "Failed to toggle automation"), file=sys.stderr)
+        return 1
+    verb = "enabled" if enabled else "disabled"
+    print(f"Automation {result['name']} {verb}.")
+    return 0
+
+
+def _automations_status(args):
+    from script_registry import get_automation_status
+
+    result = get_automation_status(args.name)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result.get("ok") else 1
+    if not result.get("ok"):
+        print(result.get("error", "Failed to read automation status"), file=sys.stderr)
+        return 1
+    state = "enabled" if result.get("enabled") else "DISABLED"
+    print(f"{result.get('name')} [{result.get('classification')}] -> {state}")
+    blocked_reason = (result.get("blocked_reason") or "").strip()
+    if blocked_reason:
+        print(f"  blocked: {blocked_reason}")
+    schedule_label = (result.get("effective_schedule_label") or "").strip()
+    if schedule_label:
+        schedule_source = (result.get("schedule_source") or "manifest").strip()
+        print(f"  schedule: {schedule_label} ({schedule_source})")
+    extra = (result.get("operator_extra_instructions") or "").strip()
+    if extra:
+        print(f"  extra instructions: {extra[:160]}")
+    return 0
+
+
+def _automations_set_instructions(args):
+    from script_registry import set_automation_instructions
+
+    if getattr(args, "clear", False):
+        text = ""
+    elif getattr(args, "stdin", False):
+        try:
+            text = sys.stdin.read()
+        except Exception as exc:
+            msg = f"Could not read instructions from stdin: {exc}"
+            if args.json:
+                print(json.dumps({"ok": False, "error": msg}, ensure_ascii=False))
+            else:
+                print(msg, file=sys.stderr)
+            return 1
+    else:
+        text = getattr(args, "text", None) or ""
+
+    result = set_automation_instructions(args.name, text)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result.get("ok") else 1
+    if not result.get("ok"):
+        print(result.get("error", "Failed to update automation instructions"), file=sys.stderr)
+        return 1
+    if result.get("cleared"):
+        print(f"Extra instructions cleared for {result['name']}.")
+    else:
+        print(f"Extra instructions updated for {result['name']}.")
+    return 0
+
+
+def _automations_set_schedule(args):
+    from script_registry import set_automation_schedule
+
+    interval_seconds = None
+    daily_at = None
+    if getattr(args, "every_minutes", None) is not None:
+        interval_seconds = int(args.every_minutes) * 60
+    elif getattr(args, "every_seconds", None) is not None:
+        interval_seconds = int(args.every_seconds)
+    elif getattr(args, "daily_at", None):
+        daily_at = str(args.daily_at).strip()
+
+    result = set_automation_schedule(
+        args.name,
+        interval_seconds=interval_seconds,
+        daily_at=daily_at,
+        clear=bool(getattr(args, "reset", False)),
+    )
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result.get("ok") else 1
+    if not result.get("ok"):
+        print(result.get("error", "Failed to update automation cadence"), file=sys.stderr)
+        return 1
+    label = str(result.get("effective_schedule_label") or "").strip()
+    source = str(result.get("schedule_source") or "manifest").strip()
+    if label:
+        print(f"Schedule updated for {result['name']}: {label} ({source})")
+    else:
+        print(f"Schedule updated for {result['name']}.")
+    return 0
+
+
 def _scripts_remove(args):
     from script_registry import remove_personal_script
 
@@ -2264,7 +2387,7 @@ def main():
     create_p.add_argument("--json", action="store_true", help="JSON output")
 
     # scripts classify
-    classify_p = scripts_sub.add_parser("classify", help="Classify all files in NEXO_HOME/scripts")
+    classify_p = scripts_sub.add_parser("classify", help="Classify all files in NEXO_HOME/personal/scripts")
     classify_p.add_argument("--json", action="store_true", help="JSON output")
 
     # scripts sync
@@ -2348,6 +2471,48 @@ def main():
     call_p.add_argument("--input", default="{}", help="JSON input payload")
     call_p.add_argument("--json-output", action="store_true", help="Force JSON output")
 
+    automations_parser = sub.add_parser("automations", help="Manage Desktop-facing automations")
+    automations_sub = automations_parser.add_subparsers(dest="automations_command")
+
+    automations_list_p = automations_sub.add_parser("list", help="List operator-facing automations")
+    automations_list_p.add_argument("--all", action="store_true", help="Include support/debug automation rows as well")
+    automations_list_p.add_argument("--json", action="store_true", help="JSON output")
+
+    automations_enable_p = automations_sub.add_parser("enable", help="Enable an automation")
+    automations_enable_p.add_argument("name", help="Automation name or path")
+    automations_enable_p.add_argument("--json", action="store_true", help="JSON output")
+
+    automations_disable_p = automations_sub.add_parser("disable", help="Disable an automation")
+    automations_disable_p.add_argument("name", help="Automation name or path")
+    automations_disable_p.add_argument("--json", action="store_true", help="JSON output")
+
+    automations_status_p = automations_sub.add_parser("status", help="Read automation status")
+    automations_status_p.add_argument("name", help="Automation name or path")
+    automations_status_p.add_argument("--json", action="store_true", help="JSON output")
+
+    automations_instructions_p = automations_sub.add_parser(
+        "instructions",
+        help="Set or clear operator extra instructions for an automation",
+    )
+    automations_instructions_p.add_argument("name", help="Automation name or path")
+    automations_instructions_group = automations_instructions_p.add_mutually_exclusive_group(required=True)
+    automations_instructions_group.add_argument("--text", help="Instruction text to persist")
+    automations_instructions_group.add_argument("--stdin", action="store_true", help="Read instruction text from stdin")
+    automations_instructions_group.add_argument("--clear", action="store_true", help="Clear any persisted extra instructions")
+    automations_instructions_p.add_argument("--json", action="store_true", help="JSON output")
+
+    automations_schedule_p = automations_sub.add_parser(
+        "schedule",
+        help="Change the cadence of an operator-facing automation",
+    )
+    automations_schedule_p.add_argument("name", help="Automation name or path")
+    automations_schedule_group = automations_schedule_p.add_mutually_exclusive_group(required=True)
+    automations_schedule_group.add_argument("--every-minutes", type=int, help="Run the automation every N minutes")
+    automations_schedule_group.add_argument("--every-seconds", type=int, help="Run the automation every N seconds")
+    automations_schedule_group.add_argument("--daily-at", type=str, help="Run the automation every day at HH:MM (24h)")
+    automations_schedule_group.add_argument("--reset", action="store_true", help="Restore the shipped default cadence")
+    automations_schedule_p.add_argument("--json", action="store_true", help="JSON output")
+
     # -- update --
     update_parser = sub.add_parser("update", help="Update installed runtime")
     update_parser.add_argument("--json", action="store_true", help="JSON output")
@@ -2638,6 +2803,21 @@ def main():
         else:
             scripts_parser.print_help()
             return 0
+    elif args.command == "automations":
+        if args.automations_command == "list":
+            return _automations_list(args)
+        elif args.automations_command == "enable":
+            return _automations_set_enabled(args, True)
+        elif args.automations_command == "disable":
+            return _automations_set_enabled(args, False)
+        elif args.automations_command == "status":
+            return _automations_status(args)
+        elif args.automations_command == "instructions":
+            return _automations_set_instructions(args)
+        elif args.automations_command == "schedule":
+            return _automations_set_schedule(args)
+        automations_parser.print_help()
+        return 0
     elif args.command == "chat":
         return _chat(args)
     elif args.command == "export":