nexo-brain 5.3.20 → 5.3.21

package/src/tools_menu 2.py

@@ -0,0 +1,229 @@
+"""Menu generator — operations center."""
+
+from datetime import datetime, timedelta
+import json
+import os
+import subprocess
+from user_context import get_context as _get_ctx
+import sys
+from pathlib import Path
+from tools_sessions import handle_status
+from tools_reminders import handle_reminders
+from db import get_db
+
+
+def _get_date_str() -> str:
+    """Get formatted date in Madrid timezone."""
+    try:
+        result = subprocess.run(
+            ["date", "+%A %d %B %Y, %H:%M"],
+            capture_output=True, text=True,
+            env={"PATH": "/usr/bin:/bin"}
+        )
+        return result.stdout.strip()
+    except Exception:
+        return datetime.now().strftime("%Y-%m-%d %H:%M")
+
+
+MENU_ITEMS = [
+    ("Projects", [
+        ("1", "Projects - Review project status"),
+        ("9", "Claude Agent VPS - Review autonomous changes"),
+    ]),
+    ("Advertising", [
+        ("7", "Google Ads - Manage campaigns"),
+        ("7b", "Meta Ads - Manage Facebook/Instagram campaigns"),
+        ("7c", "Ads Tracking - Combined Google+Meta review"),
+    ]),
+    ("Shopify", [
+        ("4", "Shopify Theme Sync - Sync theme"),
+        ("5", "Shopify Scripts - Run periodic scripts"),
+        ("6", "Change Shopify Promotion"),
+    ]),
+    ("Server & Infrastructure", [
+        ("2", "Server - Health check your-server.example.com"),
+        ("3", "WhatsApp Logs - Review logs your-whatsapp-account"),
+        ("11", "File Tracker - PHP file report"),
+        ("12", "Google Cloud - Spend, usage and GCP status"),
+    ]),
+    ("Communication & Monitoring", [
+        ("8", "Recovery Optimizer - Weekly AI analysis (MONDAY)"),
+        ("10", "Recovery Monitor - Email/WA recovery status (24h)"),
+        ("13", "Review Monitor - Email/WA review status"),
+        ("14", "WhatsApp Full Analysis - Global statistics"),
+        ("15", "Google Analytics - Review web analytics"),
+        ("16", "Email Review - Check inboxes and spam"),
+    ]),
+    ("Reports & SEO", [
+        ("17", "Search Console Audit (every 2 weeks)"),
+        ("18", "Sitemap resubmission (every 30 days)"),
+        ("19", "SEO meta verification"),
+        ("20", "Weekly Email Report (Sundays)"),
+    ]),
+]
+
+
+def _get_dashboard_alerts() -> list[dict]:
+    """Run proactive dashboard and return alerts."""
+    try:
+        nexo_home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+        script = nexo_home / "scripts" / "nexo-proactive-dashboard.py"
+        if not script.exists():
+            return []
+        result = subprocess.run(
+            [sys.executable, str(script), "--json"],
+            capture_output=True, text=True, timeout=10
+        )
+        if result.stdout.strip():
+            return json.loads(result.stdout)
+    except Exception:
+        pass
+    return []
+
+
+def _get_memory_review_summary() -> dict:
+    """Return counts of due memory reviews."""
+    try:
+        conn = get_db()
+        now_epoch = datetime.now().timestamp()
+        now_iso = datetime.now().isoformat(timespec="seconds")
+        due_learnings = conn.execute(
+            "SELECT COUNT(*) FROM learnings WHERE review_due_at IS NOT NULL AND status != 'superseded' AND review_due_at <= ?",
+            (now_epoch,)
+        ).fetchone()[0]
+        due_decisions = conn.execute(
+            "SELECT COUNT(*) FROM decisions WHERE review_due_at IS NOT NULL AND status != 'reviewed' AND review_due_at <= ?",
+            (now_iso,)
+        ).fetchone()[0]
+        return {
+            "learnings": due_learnings,
+            "decisions": due_decisions,
+            "total": due_learnings + due_decisions,
+        }
+    except Exception:
+        return {"learnings": 0, "decisions": 0, "total": 0}
+
+
+def handle_menu() -> str:
+    """Generate the full operations menu with alerts."""
+    date_str = _get_date_str()
+    W = 56  # inner width
+
+    lines = []
+    lines.append("╔" + "═" * W + "╗")
+    lines.append("║" + f"{_get_ctx().assistant_name} — OPERATIONS CENTER".center(W) + "║")
+    lines.append("║" + date_str.center(W) + "║")
+    lines.append("╠" + "═" * W + "╣")
+
+    # Proactive dashboard alerts
+    dashboard_alerts = _get_dashboard_alerts()
+    memory_reviews = _get_memory_review_summary()
+    due = handle_reminders("due")
+    has_alerts = dashboard_alerts or memory_reviews["total"] > 0 or (due and "No reminders" not in due)
+
+    if has_alerts:
+        lines.append("║" + "  PROACTIVE ALERTS".ljust(W) + "║")
+        lines.append("╠" + "═" * W + "╣")
+
+        if dashboard_alerts:
+            for alert in dashboard_alerts[:10]:  # Top 10
+                sev = alert.get("severity", "low")
+                icon = {"high": "!!!", "medium": " ! ", "low": " . "}.get(sev, " . ")
+                text = alert.get("title", "")[:W - 8]
+                lines.append("║" + f"  {icon} {text}".ljust(W) + "║")
+            if len(dashboard_alerts) > 10:
+                more = len(dashboard_alerts) - 10
+                lines.append("║" + f"  ... and {more} more alerts".ljust(W) + "║")
+
+        if memory_reviews["total"] > 0:
+            text = (
+                f"MEMORY: {memory_reviews['total']} pending reviews "
+                f"({memory_reviews['decisions']} decisions, {memory_reviews['learnings']} learnings)"
+            )[:W - 4]
+            lines.append("║" + f"  !  {text}".ljust(W) + "║")
+
+        if due and "No reminders" not in due:
+            for reminder_line in due.split("\n"):
+                if reminder_line.strip():
+                    truncated = reminder_line[:W - 2]
+                    lines.append("║" + f"  {truncated}".ljust(W) + "║")
+
+        lines.append("╠" + "═" * W + "╣")
+
+    # Menu categories
+    for category, items in MENU_ITEMS:
+        lines.append("║" + f"  {category.upper()}".ljust(W) + "║")
+        lines.append("║" + "─" * W + "║")
+        for num, desc in items:
+            entry = f"  {num:>3}. {desc}"
+            lines.append("║" + entry.ljust(W) + "║")
+        lines.append("╠" + "═" * W + "╣")
+
+    # Backlog: ideas, future projects, undated or distant tasks
+    try:
+        conn = get_db()
+        cutoff = (datetime.now() + timedelta(days=7)).strftime("%Y-%m-%d")
+        # Reminders without date (backlog/ideas)
+        no_date = conn.execute(
+            "SELECT id, description, category FROM reminders WHERE status LIKE 'PENDING%' AND (date IS NULL OR date='') ORDER BY category, id"
+        ).fetchall()
+        # Reminders with date > 7 days ahead (future)
+        future = conn.execute(
+            "SELECT id, description, date, category FROM reminders WHERE status LIKE 'PENDING%' AND date > ? ORDER BY date",
+            (cutoff,)
+        ).fetchall()
+        # Followups without date
+        nf_no_date = conn.execute(
+            "SELECT id, description FROM followups WHERE status NOT LIKE 'COMPLETED%' AND status NOT IN ('DELETED','archived','blocked','waiting') AND (date IS NULL OR date='') ORDER BY id"
+        ).fetchall()
+
+        if no_date or future or nf_no_date:
+            lines.append("║" + "  BACKLOG / IDEAS / FUTURE".ljust(W) + "║")
+            lines.append("║" + "─" * W + "║")
+
+            if no_date:
+                by_cat = {}
+                for r in no_date:
+                    cat = (r["category"] or "general").capitalize()
+                    by_cat.setdefault(cat, []).append(r)
+                for cat, items in by_cat.items():
+                    lines.append("║" + f"  [{cat}]".ljust(W) + "║")
+                    for r in items:
+                        short = r["description"][:W - 10]
+                        lines.append("║" + f"    {r['id']}: {short}".ljust(W) + "║")
+
+            if future:
+                lines.append("║" + f"  [Scheduled]".ljust(W) + "║")
+                for r in future:
+                    short = r["description"][:W - 18]
+                    lines.append("║" + f"    {r['id']} ({r['date']}): {short}".ljust(W) + "║")
+
+            if nf_no_date:
+                lines.append("║" + f"  [Pending followups]".ljust(W) + "║")
+                for r in nf_no_date:
+                    short = r["description"][:W - 12]
+                    lines.append("║" + f"    {r['id']}: {short}".ljust(W) + "║")
+
+            lines.append("╠" + "═" * W + "╣")
+    except Exception as e:
+        lines.append("║" + f"  ⚠ Error backlog: {e}".ljust(W) + "║")
+        lines.append("╠" + "═" * W + "╣")
+
+    # Active sessions
+    sessions = handle_status()
+    if "No sessions" not in sessions:
+        lines.append("║" + "  ACTIVE SESSIONS".ljust(W) + "║")
+        lines.append("║" + "─" * W + "║")
+        for s_line in sessions.split("\n"):
+            if s_line.strip() and "ACTIVE SESSIONS" not in s_line:
+                truncated = s_line[:W - 2]
+                lines.append("║" + f"  {truncated}".ljust(W) + "║")
+        lines.append("╠" + "═" * W + "╣")
+
+    # Replace last ╠═╣ with bottom border
+    if lines[-1].startswith("╠"):
+        lines[-1] = "╚" + "═" * W + "╝"
+    else:
+        lines.append("╚" + "═" * W + "╝")
+
+    return "\n".join(lines)

package/src/tools_reminders 2.py

@@ -0,0 +1,88 @@
+"""Reminders and followups reader — reads from SQLite database."""
+
+from db import get_reminders, get_followups
+from datetime import date
+
+
+def _is_due(date_str: str) -> bool:
+    """Check if a date string is today or in the past."""
+    if not date_str:
+        return False
+    try:
+        d = date.fromisoformat(date_str.strip()[:10])
+        return d <= date.today()
+    except (ValueError, IndexError):
+        return False
+
+
+def handle_reminders(filter_type: str = "due") -> str:
+    """Read reminders and followups from SQLite, return relevant ones.
+
+    Args:
+        filter_type: 'due', 'all', 'followups', 'completed', 'deleted', 'history', 'any'
+    """
+    parts = []
+
+    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", "completed", "deleted", "history", "any"):
+        f = _format_followups(filter_type)
+        if f:
+            parts.append(f)
+
+    result = "\n\n".join(parts)
+    return result if result else "No pending reminders."
+
+
+def _format_reminders(filter_type: str) -> str:
+    """Format reminders from database."""
+    rows = get_reminders(filter_type)
+    if not rows:
+        return ""
+
+    lines = ["REMINDERS:"]
+    for r in rows:
+        rid = r.get("id", "?")
+        fecha = r.get("date") or ""
+        desc = r.get("description", "")
+        status = r.get("status", "")
+        desc = desc.replace("**", "")
+        due_marker = " [DUE]" if _is_due(fecha) else ""
+        fecha_display = f"({fecha})" if fecha else "(—)"
+        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}")
+
+    return "\n".join(lines)
+
+
+def _format_followups(filter_type: str) -> str:
+    """Format followups from database."""
+    rows = get_followups(filter_type)
+    if not rows:
+        return ""
+
+    lines = ["FOLLOWUPS NEXO:"]
+    for r in rows:
+        nfid = r.get("id", "?")
+        fecha = r.get("date") or ""
+        desc = r.get("description", "")
+        desc = desc.replace("**", "")
+        due_marker = " [DUE]" if _is_due(fecha) else ""
+        fecha_display = f"({fecha})" if fecha else "(—)"
+        rec = r.get("recurrence") or ""
+        rec_tag = f" [♻️ {rec}]" if rec else ""
+        pri = r.get("priority") or "medium"
+        pri_icon = {"critical": "🔴", "high": "🟠", "medium": "", "low": "⚪"}.get(pri, "")
+        pri_tag = f" {pri_icon}" if pri_icon else ""
+        impact = float(r.get("impact_score") or 0)
+        impact_tag = f" [impact {impact:.1f}]" if impact > 0 else ""
+        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}{impact_tag}{rec_tag}{status_tag} — {desc[:120]}")
+
+    return "\n".join(lines)

package/src/tools_reminders_crud 2.py

@@ -0,0 +1,363 @@
+"""CRUD handlers for reminders and followups — operates on SQLite via db.py."""
+
+from db import (
+    create_reminder, update_reminder, complete_reminder, delete_reminder,
+    restore_reminder, add_reminder_note, get_reminder,
+    create_followup, update_followup, complete_followup, delete_followup,
+    restore_followup, add_followup_note, get_followup,
+    validate_item_read_token,
+    find_decisions_by_context_ref, update_decision_outcome,
+    set_linked_outcomes_met,
+)
+
+
+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:
+    """Create a new reminder. id must start with 'R'."""
+    if not id.startswith('R'):
+        return f"ERROR: Reminder ID must start with 'R' (received: '{id}')."
+
+    result = create_reminder(id=id, description=description, date=date or None, category=category)
+    if not result or "error" in result:
+        error_msg = result.get("error", "unknown") if isinstance(result, dict) else "unknown"
+        return f"ERROR: {error_msg}"
+
+    date_str = date if date else 'no date'
+    return f"Reminder created. Date: {date_str}. Category: {category}."
+
+
+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
+    if date:
+        fields['date'] = date
+    if status:
+        fields['status'] = status
+    if category:
+        fields['category'] = category
+
+    if not fields:
+        return f"ERROR: No fields specified to update for {id}."
+
+    result = update_reminder(id=id, **fields)
+    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}."
+
+
+def handle_reminder_complete(id: str) -> str:
+    """Mark a reminder as completed."""
+    result = complete_reminder(id=id)
+    if not result or "error" in result:
+        return f"ERROR: Reminder {id} not found."
+
+    return f"Reminder {id} marked COMPLETED."
+
+
+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} soft-deleted."
+
+
+# ── Followups ──────────────────────────────────────────────────────────────────
+
+def handle_followup_create(
+    id: str,
+    description: str,
+    date: str = '',
+    verification: str = '',
+    reasoning: str = '',
+    recurrence: str = '',
+    priority: str = 'medium',
+) -> str:
+    """Create a new NEXO followup. id must start with 'NF'.
+
+    Args:
+        id: Unique ID starting with 'NF'
+        description: What to verify/do
+        date: Target date YYYY-MM-DD (optional)
+        verification: How to verify completion (optional)
+        reasoning: WHY this followup exists — what decision/context led to it
+        recurrence: Recurrence pattern (optional). Formats: 'weekly:monday', 'monthly:1', 'quarterly'.
+                    When completed, auto-creates the next occurrence.
+    """
+    if not id.startswith('NF'):
+        return f"ERROR: Followup ID must start with 'NF' (received: '{id}')."
+
+    result = create_followup(
+        id=id,
+        description=description,
+        date=date or None,
+        verification=verification,
+        reasoning=reasoning,
+        recurrence=recurrence or None,
+        priority=priority or "medium",
+    )
+    if not result or "error" in result:
+        error_msg = result.get("error", "unknown") if isinstance(result, dict) else "unknown"
+        return f"ERROR: {error_msg}"
+
+    date_str = date if date else 'no date'
+    rec_str = f" Recurrence: {recurrence}." if recurrence else ""
+    priority_str = f" Priority: {priority or 'medium'}."
+    warning = result.get("warning", "")
+    warn_str = f"\n{warning}" if warning else ""
+    return f"Followup created. Date: {date_str}.{priority_str}{rec_str}{warn_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
+    if date:
+        fields['date'] = date
+    if verification:
+        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 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 {id} updated: {changed}."
+
+
+def handle_followup_complete(id: str, result: str = '') -> str:
+    """Mark a followup as completed, optionally recording the result.
+    Also auto-updates any decision that references this followup in context_ref.
+    If the followup is recurring, auto-creates the next occurrence."""
+    from db import get_db
+    # Check recurrence before completing (complete may rename the ID)
+    conn = get_db()
+    row = conn.execute("SELECT recurrence FROM followups WHERE id = ?", (id,)).fetchone()
+    has_recurrence = row and row["recurrence"]
+
+    db_result = complete_followup(id=id, result=result)
+    if not db_result or "error" in db_result:
+        return f"ERROR: Followup {id} not found."
+
+    # Emit trust event: task completed successfully
+    try:
+        from cognitive._trust import adjust_trust
+        adjust_trust("task_completed", f"Followup {id} completed")
+    except Exception:
+        pass
+
+    # Auto-link: find decisions whose context_ref matches this followup ID
+    msg = f"Followup {id} marked COMPLETED."
+    if has_recurrence:
+        # The new one was auto-created by complete_followup
+        new_row = conn.execute("SELECT date FROM followups WHERE id = ?", (id,)).fetchone()
+        if new_row:
+            msg += f" ♻️ Next auto-created for {new_row['date']}."
+    linked_decisions = find_decisions_by_context_ref(id)
+    if linked_decisions:
+        outcome_text = result if result else f"Followup {id} completed"
+        for dec in linked_decisions:
+            update_decision_outcome(dec['id'], outcome_text)
+        dec_ids = ', '.join(f"#{d['id']}" for d in linked_decisions)
+        msg += f" Decision(s) {dec_ids} updated with automatic outcome."
+
+    try:
+        linked_outcomes = set_linked_outcomes_met(
+            "followup",
+            id,
+            metric_source="followup_status",
+            actual_value=1.0,
+            actual_value_text=result if result else f"Followup {id} completed",
+            note="Linked followup completed.",
+        )
+    except Exception:
+        linked_outcomes = []
+    if linked_outcomes:
+        msg += f" Linked outcomes met: {len(linked_outcomes)}."
+
+    return msg
+
+
+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 {id} soft-deleted."