nexo-brain 5.3.26 → 5.3.27

package/src/tools_menu 2.py

@@ -1,229 +0,0 @@
-"""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

@@ -1,88 +0,0 @@
-"""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

@@ -1,363 +0,0 @@
-"""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."