nexo-brain 3.1.2 → 3.1.3

package/src/db/_schema.py

@@ -674,6 +674,35 @@ def _m28_automation_runs(conn):
     _migrate_add_index(conn, "idx_automation_runs_status", "automation_runs", "status")
 
 
+def _m29_item_history_and_soft_delete(conn):
+    """Persist reminder/followup history and read-before-mutate tokens."""
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS item_history (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            item_type TEXT NOT NULL,
+            item_id TEXT NOT NULL,
+            event_type TEXT NOT NULL,
+            note TEXT DEFAULT '',
+            actor TEXT DEFAULT '',
+            metadata TEXT DEFAULT '{}',
+            created_at REAL NOT NULL
+        )
+    """)
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS item_read_tokens (
+            token TEXT PRIMARY KEY,
+            item_type TEXT NOT NULL,
+            item_id TEXT NOT NULL,
+            history_seq INTEGER DEFAULT 0,
+            issued_at REAL NOT NULL,
+            expires_at REAL NOT NULL
+        )
+    """)
+    _migrate_add_index(conn, "idx_item_history_lookup", "item_history", "item_type, item_id, created_at")
+    _migrate_add_index(conn, "idx_item_history_item", "item_history", "item_id")
+    _migrate_add_index(conn, "idx_item_read_tokens_lookup", "item_read_tokens", "item_type, item_id, expires_at")
+
+
 MIGRATIONS = [
     (1, "learnings_columns", _m1_learnings_columns),
     (2, "followups_reasoning", _m2_followups_reasoning),
@@ -703,6 +732,7 @@ MIGRATIONS = [
     (26, "protocol_answer_confidence", _m26_protocol_answer_confidence),
     (27, "state_watchers", _m27_state_watchers),
     (28, "automation_runs", _m28_automation_runs),
+    (29, "item_history_and_soft_delete", _m29_item_history_and_soft_delete),
 ]
 
 

package/src/server.py

@@ -24,10 +24,10 @@ from tools_coordination import (
 from tools_reminders import handle_reminders
 from tools_menu import handle_menu
 from tools_reminders_crud import (
-    handle_reminder_create, handle_reminder_update,
-    handle_reminder_complete, handle_reminder_delete,
-    handle_followup_create, handle_followup_update,
-    handle_followup_complete, handle_followup_delete,
+    handle_reminder_create, handle_reminder_get, handle_reminder_update,
+    handle_reminder_complete, handle_reminder_note, handle_reminder_restore, handle_reminder_delete,
+    handle_followup_create, handle_followup_get, handle_followup_update,
+    handle_followup_complete, handle_followup_note, handle_followup_restore, handle_followup_delete,
 )
 from tools_learnings import (
     handle_learning_add, handle_learning_search,
@@ -191,6 +191,8 @@ mcp = FastMCP(
         "React: DIARY REMINDER→write diary, VIBE:NEGATIVE→ultra-concise, AUTO-PRIME→read learnings\n"
         "- **Followups:** NEXO tasks, execute silently. 'done'/'all set'→`nexo_followup_complete` NOW. "
         "Reminders=user's, alert when due\n"
+        "- **Reminder/followup history:** before update/delete/restore/note, call the corresponding "
+        "`nexo_reminder_get` / `nexo_followup_get` first and use its `READ_TOKEN`.\n"
         "- **Observe:** correction→learning. 'tomorrow'→followup. person→entity. open topic→followup 3d\n"
         "- **Trust events:** When user expresses satisfaction/thanks (any language)→`nexo_cognitive_trust(event='explicit_thanks')`. "
         "When user corrects you→`nexo_cognitive_trust(event='correction')`. "
@@ -488,7 +490,7 @@ def nexo_reminders(filter: str = "due") -> str:
     """Check reminders and followups.
 
     Args:
-        filter: 'due' (vencidos/hoy), 'all' (todos activos), 'followups' (solo NEXO followups)
+        filter: 'due', 'all', 'followups', 'completed', 'deleted', 'history', or 'any'
     """
     return handle_reminders(filter)
 
@@ -503,7 +505,7 @@ def nexo_menu() -> str:
     return handle_menu()
 
 
-# ── Reminders CRUD (4 tools) ──────────────────────────────────────
+# ── Reminders CRUD (7 tools) ──────────────────────────────────────
 
 @mcp.tool
 def nexo_reminder_create(id: str, description: str, date: str = "", category: str = "general") -> str:
@@ -519,17 +521,36 @@ def nexo_reminder_create(id: str, description: str, date: str = "", category: st
 
 
 @mcp.tool
-def nexo_reminder_update(id: str, description: str = "", date: str = "", status: str = "", category: str = "") -> str:
+def nexo_reminder_get(id: str) -> str:
+    """Read a reminder with its history and usage rules.
+
+    IMPORTANT: before update/delete/restore/note, call this tool first and use the returned READ_TOKEN.
+    """
+    return handle_reminder_get(id)
+
+
+@mcp.tool
+def nexo_reminder_update(
+    id: str,
+    description: str = "",
+    date: str = "",
+    status: str = "",
+    category: str = "",
+    read_token: str = "",
+) -> str:
     """Update fields of an existing reminder. Only non-empty fields are changed.
 
+    IMPORTANT: call `nexo_reminder_get` first and pass its READ_TOKEN.
+
     Args:
         id: Reminder ID (e.g., R87).
         description: New description (optional).
         date: New date YYYY-MM-DD (optional).
         status: New status (optional).
         category: New category (optional).
+        read_token: Token returned by `nexo_reminder_get`.
     """
-    return handle_reminder_update(id, description, date, status, category)
+    return handle_reminder_update(id, description, date, status, category, read_token)
 
 
 @mcp.tool
@@ -543,16 +564,47 @@ def nexo_reminder_complete(id: str) -> str:
 
 
 @mcp.tool
-def nexo_reminder_delete(id: str) -> str:
-    """Delete a reminder permanently.
+def nexo_reminder_note(id: str, note: str, read_token: str = "", actor: str = "nexo") -> str:
+    """Append a note to reminder history.
+
+    IMPORTANT: call `nexo_reminder_get` first and pass its READ_TOKEN.
+
+    Args:
+        id: Reminder ID (e.g., R87).
+        note: Operational note to append to history.
+        read_token: Token returned by `nexo_reminder_get`.
+        actor: Actor label for the history note.
+    """
+    return handle_reminder_note(id, note, read_token, actor)
+
+
+@mcp.tool
+def nexo_reminder_restore(id: str, read_token: str = "") -> str:
+    """Restore a soft-deleted reminder back to PENDING.
+
+    IMPORTANT: call `nexo_reminder_get` first and pass its READ_TOKEN.
+
+    Args:
+        id: Reminder ID (e.g., R87).
+        read_token: Token returned by `nexo_reminder_get`.
+    """
+    return handle_reminder_restore(id, read_token)
+
+
+@mcp.tool
+def nexo_reminder_delete(id: str, read_token: str = "") -> str:
+    """Soft-delete a reminder.
+
+    IMPORTANT: call `nexo_reminder_get` first and pass its READ_TOKEN.
 
     Args:
         id: Reminder ID (e.g., R87).
+        read_token: Token returned by `nexo_reminder_get`.
     """
-    return handle_reminder_delete(id)
+    return handle_reminder_delete(id, read_token)
 
 
-# ── Followups CRUD (4 tools) ──────────────────────────────────────
+# ── Followups CRUD (7 tools) ──────────────────────────────────────
 
 @mcp.tool
 def nexo_followup_create(id: str, description: str, date: str = "", verification: str = "", reasoning: str = "", recurrence: str = "", priority: str = "medium") -> str:
@@ -577,9 +629,28 @@ def nexo_followup_create(id: str, description: str, date: str = "", verification
 
 
 @mcp.tool
-def nexo_followup_update(id: str, description: str = "", date: str = "", verification: str = "", status: str = "", priority: str = "") -> str:
+def nexo_followup_get(id: str) -> str:
+    """Read a followup with its history and usage rules.
+
+    IMPORTANT: before update/delete/restore/note, call this tool first and use the returned READ_TOKEN.
+    """
+    return handle_followup_get(id)
+
+
+@mcp.tool
+def nexo_followup_update(
+    id: str,
+    description: str = "",
+    date: str = "",
+    verification: str = "",
+    status: str = "",
+    priority: str = "",
+    read_token: str = "",
+) -> str:
     """Update fields of an existing followup. Only non-empty fields are changed.
 
+    IMPORTANT: call `nexo_followup_get` first and pass its READ_TOKEN.
+
     Args:
         id: Followup ID (e.g., NF45).
         description: New description (optional).
@@ -587,13 +658,9 @@ def nexo_followup_update(id: str, description: str = "", date: str = "", verific
         verification: New verification text (optional).
         status: New status (optional).
         priority: critical, high, medium, low (optional).
+        read_token: Token returned by `nexo_followup_get`.
     """
-    result = handle_followup_update(id, description, date, verification, status)
-    if priority in ('critical', 'high', 'medium', 'low'):
-        from db import get_db
-        get_db().execute("UPDATE followups SET priority = ? WHERE id = ?", (priority, id))
-        get_db().commit()
-    return result
+    return handle_followup_update(id, description, date, verification, status, priority, read_token)
 
 
 @mcp.tool
@@ -608,13 +675,44 @@ def nexo_followup_complete(id: str, result: str = "") -> str:
 
 
 @mcp.tool
-def nexo_followup_delete(id: str) -> str:
-    """Delete a followup permanently.
+def nexo_followup_note(id: str, note: str, read_token: str = "", actor: str = "nexo") -> str:
+    """Append a note to followup history.
+
+    IMPORTANT: call `nexo_followup_get` first and pass its READ_TOKEN.
+
+    Args:
+        id: Followup ID (e.g., NF45).
+        note: Operational note to append to history.
+        read_token: Token returned by `nexo_followup_get`.
+        actor: Actor label for the history note.
+    """
+    return handle_followup_note(id, note, read_token, actor)
+
+
+@mcp.tool
+def nexo_followup_restore(id: str, read_token: str = "") -> str:
+    """Restore a soft-deleted followup back to PENDING.
+
+    IMPORTANT: call `nexo_followup_get` first and pass its READ_TOKEN.
+
+    Args:
+        id: Followup ID (e.g., NF45).
+        read_token: Token returned by `nexo_followup_get`.
+    """
+    return handle_followup_restore(id, read_token)
+
+
+@mcp.tool
+def nexo_followup_delete(id: str, read_token: str = "") -> str:
+    """Soft-delete a followup.
+
+    IMPORTANT: call `nexo_followup_get` first and pass its READ_TOKEN.
 
     Args:
         id: Followup ID (e.g., NF45).
+        read_token: Token returned by `nexo_followup_get`.
     """
-    return handle_followup_delete(id)
+    return handle_followup_delete(id, read_token)
 
 
 # ── Learnings CRUD (5 tools) ──────────────────────────────────────

package/src/tools_reminders.py

@@ -19,16 +19,16 @@ def handle_reminders(filter_type: str = "due") -> str:
     """Read reminders and followups from SQLite, return relevant ones.
 
     Args:
-        filter_type: 'due' (vencidos/hoy), 'all' (todos activos), 'followups' (solo followups)
+        filter_type: 'due', 'all', 'followups', 'completed', 'deleted', 'history', 'any'
     """
     parts = []
 
-    if filter_type in ("due", "all"):
+    if filter_type in ("due", "all", "completed", "deleted", "history", "any"):
         r = _format_reminders(filter_type)
         if r:
             parts.append(r)
 
-    if filter_type in ("due", "all", "followups"):
+    if filter_type in ("due", "all", "followups", "completed", "deleted", "history", "any"):
         f = _format_followups(filter_type)
         if f:
             parts.append(f)
@@ -52,7 +52,8 @@ def _format_reminders(filter_type: str) -> str:
         desc = desc.replace("**", "")
         due_marker = " [DUE]" if _is_due(fecha) else ""
         fecha_display = f"({fecha})" if fecha else "(—)"
-        lines.append(f"  {rid} {fecha_display}{due_marker} — {desc[:120]}")
+        status_tag = f" [{status}]" if status and status != "PENDING" else ""
+        lines.append(f"  {rid} {fecha_display}{due_marker}{status_tag} — {desc[:120]}")
         if "RECURRENTE" in status.upper():
             lines.append(f"    Status: {status}")
 
@@ -81,6 +82,8 @@ def _format_followups(filter_type: str) -> str:
         pri = r.get("priority") or "medium"
         pri_icon = {"critical": "🔴", "high": "🟠", "medium": "", "low": "⚪"}.get(pri, "")
         pri_tag = f" {pri_icon}" if pri_icon else ""
-        lines.append(f"  {nfid} {fecha_display}{due_marker}{pri_tag}{rec_tag} — {desc[:120]}")
+        status = r.get("status") or ""
+        status_tag = f" [{status}]" if status and status != "PENDING" else ""
+        lines.append(f"  {nfid} {fecha_display}{due_marker}{pri_tag}{rec_tag}{status_tag} — {desc[:120]}")
 
     return "\n".join(lines)

package/src/tools_reminders_crud.py

@@ -2,13 +2,77 @@
 
 from db import (
     create_reminder, update_reminder, complete_reminder, delete_reminder,
-    get_reminders, get_reminder,
+    restore_reminder, add_reminder_note, get_reminder,
     create_followup, update_followup, complete_followup, delete_followup,
-    get_followups, get_followup,
+    restore_followup, add_followup_note, get_followup,
+    validate_item_read_token,
     find_decisions_by_context_ref, update_decision_outcome,
 )
 
 
+def _require_item_read(item_type: str, item_id: str, read_token: str) -> str | None:
+    ok, message = validate_item_read_token(read_token, item_type, item_id)
+    if ok:
+        return None
+    prefix = "followup" if item_type == "followup" else "reminder"
+    return f"ERROR: {message} Use nexo_{prefix}_get(id='{item_id}') first."
+
+
+def _history_lines(history: list[dict]) -> list[str]:
+    if not history:
+        return ["- (no history)"]
+    lines: list[str] = []
+    for event in history:
+        created_at = event.get("created_at") or "?"
+        event_type = event.get("event_type") or "event"
+        actor = event.get("actor") or "system"
+        note = (event.get("note") or "").strip()
+        suffix = f" — {note}" if note else ""
+        lines.append(f"- {created_at} [{event_type}] ({actor}){suffix}")
+    return lines
+
+
+def _format_reminder_payload(reminder: dict) -> str:
+    lines = [
+        f"REMINDER {reminder['id']}",
+        f"Description: {reminder.get('description') or ''}",
+        f"Date: {reminder.get('date') or '—'}",
+        f"Status: {reminder.get('status') or '—'}",
+        f"Category: {reminder.get('category') or 'general'}",
+    ]
+    history_rules = reminder.get("history_rules") or []
+    if history_rules:
+        lines.append("Usage rules:")
+        lines.extend(f"- {rule}" for rule in history_rules)
+    lines.append("History:")
+    lines.extend(_history_lines(reminder.get("history") or []))
+    if reminder.get("read_token"):
+        lines.append(f"READ_TOKEN: {reminder['read_token']}")
+    return "\n".join(lines)
+
+
+def _format_followup_payload(followup: dict) -> str:
+    lines = [
+        f"FOLLOWUP {followup['id']}",
+        f"Description: {followup.get('description') or ''}",
+        f"Date: {followup.get('date') or '—'}",
+        f"Status: {followup.get('status') or '—'}",
+        f"Verification: {followup.get('verification') or '—'}",
+        f"Reasoning: {followup.get('reasoning') or '—'}",
+        f"Recurrence: {followup.get('recurrence') or '—'}",
+        f"Priority: {followup.get('priority') or 'medium'}",
+    ]
+    history_rules = followup.get("history_rules") or []
+    if history_rules:
+        lines.append("Usage rules:")
+        lines.extend(f"- {rule}" for rule in history_rules)
+    lines.append("History:")
+    lines.extend(_history_lines(followup.get("history") or []))
+    if followup.get("read_token"):
+        lines.append(f"READ_TOKEN: {followup['read_token']}")
+    return "\n".join(lines)
+
+
 # ── Reminders ──────────────────────────────────────────────────────────────────
 
 def handle_reminder_create(id: str, description: str, date: str = '', category: str = 'general') -> str:
@@ -25,8 +89,27 @@ def handle_reminder_create(id: str, description: str, date: str = '', category:
     return f"Reminder created. Date: {date_str}. Category: {category}."
 
 
-def handle_reminder_update(id: str, description: str = '', date: str = '', status: str = '', category: str = '') -> str:
+def handle_reminder_get(id: str) -> str:
+    """Read a reminder with history and return a read token for safe mutations."""
+    result = get_reminder(id=id, include_history=True)
+    if not result:
+        return f"ERROR: Reminder {id} not found."
+    return _format_reminder_payload(result)
+
+
+def handle_reminder_update(
+    id: str,
+    description: str = '',
+    date: str = '',
+    status: str = '',
+    category: str = '',
+    read_token: str = '',
+) -> str:
     """Update one or more fields of an existing reminder."""
+    error = _require_item_read("reminder", id, read_token)
+    if error:
+        return error
+
     fields: dict = {}
     if description:
         fields['description'] = description
@@ -41,8 +124,9 @@ def handle_reminder_update(id: str, description: str = '', date: str = '', statu
         return f"ERROR: No fields specified to update for {id}."
 
     result = update_reminder(id=id, **fields)
-    if not result:
-        return f"ERROR: Reminder {id} not found."
+    if not result or "error" in result:
+        error_msg = result.get("error", f"Reminder {id} not found.") if isinstance(result, dict) else f"Reminder {id} not found."
+        return f"ERROR: {error_msg}"
 
     changed = ', '.join(fields.keys())
     return f"Reminder {id} updated: {changed}."
@@ -57,13 +141,42 @@ def handle_reminder_complete(id: str) -> str:
     return f"Reminder {id} marked COMPLETED."
 
 
-def handle_reminder_delete(id: str) -> str:
-    """Delete a reminder permanently."""
+def handle_reminder_note(id: str, note: str, read_token: str = '', actor: str = 'nexo') -> str:
+    """Append a note to reminder history."""
+    if not note.strip():
+        return "ERROR: note is required."
+    error = _require_item_read("reminder", id, read_token)
+    if error:
+        return error
+    result = add_reminder_note(id=id, note=note.strip(), actor=actor or "nexo")
+    if not result or "error" in result:
+        error_msg = result.get("error", f"Reminder {id} not found.") if isinstance(result, dict) else f"Reminder {id} not found."
+        return f"ERROR: {error_msg}"
+    return f"Reminder {id} note added."
+
+
+def handle_reminder_restore(id: str, read_token: str = '') -> str:
+    """Restore a soft-deleted reminder."""
+    error = _require_item_read("reminder", id, read_token)
+    if error:
+        return error
+    result = restore_reminder(id=id)
+    if not result or "error" in result:
+        error_msg = result.get("error", f"Reminder {id} not found.") if isinstance(result, dict) else f"Reminder {id} not found."
+        return f"ERROR: {error_msg}"
+    return f"Reminder {id} restored to PENDING."
+
+
+def handle_reminder_delete(id: str, read_token: str = '') -> str:
+    """Soft-delete a reminder."""
+    error = _require_item_read("reminder", id, read_token)
+    if error:
+        return error
     result = delete_reminder(id=id)
     if not result:
         return f"ERROR: Reminder {id} not found."
 
-    return f"Reminder {id} deleted."
+    return f"Reminder {id} soft-deleted."
 
 
 # ── Followups ──────────────────────────────────────────────────────────────────
@@ -95,8 +208,28 @@ def handle_followup_create(id: str, description: str, date: str = '', verificati
     return f"Followup created. Date: {date_str}.{rec_str}{warn_str}"
 
 
-def handle_followup_update(id: str, description: str = '', date: str = '', verification: str = '', status: str = '') -> str:
+def handle_followup_get(id: str) -> str:
+    """Read a followup with history and return a read token for safe mutations."""
+    result = get_followup(id=id, include_history=True)
+    if not result:
+        return f"ERROR: Followup {id} not found."
+    return _format_followup_payload(result)
+
+
+def handle_followup_update(
+    id: str,
+    description: str = '',
+    date: str = '',
+    verification: str = '',
+    status: str = '',
+    priority: str = '',
+    read_token: str = '',
+) -> str:
     """Update one or more fields of an existing followup."""
+    error = _require_item_read("followup", id, read_token)
+    if error:
+        return error
+
     fields: dict = {}
     if description:
         fields['description'] = description
@@ -106,16 +239,19 @@ def handle_followup_update(id: str, description: str = '', date: str = '', verif
         fields['verification'] = verification
     if status:
         fields['status'] = status
+    if priority:
+        fields['priority'] = priority
 
     if not fields:
         return f"ERROR: No fields specified to update for {id}."
 
     result = update_followup(id=id, **fields)
-    if not result:
-        return f"ERROR: Followup {id} not found."
+    if not result or "error" in result:
+        error_msg = result.get("error", f"Followup {id} not found.") if isinstance(result, dict) else f"Followup {id} not found."
+        return f"ERROR: {error_msg}"
 
     changed = ', '.join(fields.keys())
-    return f"Followup updated: {changed}."
+    return f"Followup {id} updated: {changed}."
 
 
 def handle_followup_complete(id: str, result: str = '') -> str:
@@ -157,10 +293,39 @@ def handle_followup_complete(id: str, result: str = '') -> str:
     return msg
 
 
-def handle_followup_delete(id: str) -> str:
-    """Delete a followup permanently."""
+def handle_followup_note(id: str, note: str, read_token: str = '', actor: str = 'nexo') -> str:
+    """Append a note to followup history."""
+    if not note.strip():
+        return "ERROR: note is required."
+    error = _require_item_read("followup", id, read_token)
+    if error:
+        return error
+    result = add_followup_note(id=id, note=note.strip(), actor=actor or "nexo")
+    if not result or "error" in result:
+        error_msg = result.get("error", f"Followup {id} not found.") if isinstance(result, dict) else f"Followup {id} not found."
+        return f"ERROR: {error_msg}"
+    return f"Followup {id} note added."
+
+
+def handle_followup_restore(id: str, read_token: str = '') -> str:
+    """Restore a soft-deleted followup."""
+    error = _require_item_read("followup", id, read_token)
+    if error:
+        return error
+    result = restore_followup(id=id)
+    if not result or "error" in result:
+        error_msg = result.get("error", f"Followup {id} not found.") if isinstance(result, dict) else f"Followup {id} not found."
+        return f"ERROR: {error_msg}"
+    return f"Followup {id} restored to PENDING."
+
+
+def handle_followup_delete(id: str, read_token: str = '') -> str:
+    """Soft-delete a followup."""
+    error = _require_item_read("followup", id, read_token)
+    if error:
+        return error
     result = delete_followup(id=id)
     if not result:
         return f"ERROR: Followup {id} not found."
 
-    return f"Followup deleted."
+    return f"Followup {id} soft-deleted."