nexo-brain 7.30.21 → 7.30.23

package/src/product_knowledge/catalog.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "updated_at": "2026-06-06",
+  "updated_at": "2026-06-07",
   "source_policy": "Brain owns stable product semantics. Desktop manifests describe installed UI surfaces. Backend endpoints own live state, prices, balances, tickets and provisioning.",
   "capabilities": [
     {
@@ -210,6 +210,7 @@
         "nexo/src/server.py:nexo_support_ticket_list",
         "nexo/src/server.py:nexo_support_ticket_create",
         "nexo-desktop/renderer/react/panels/Settings/tabs/SupportTab.jsx",
+        "nexo-desktop-web SupportTicketController",
         "nexo-desktop-web routes/web.php"
       ],
       "surfaces": ["Desktop Support settings", "Brain support-ticket tools", "Backend support API"],
@@ -249,12 +250,19 @@
         "nexo/src/system_catalog.py:nexo_provider_proxy",
         "nexo/src/system_catalog.py:nexo_provider_models",
         "nexo-desktop/renderer/react/panels/Settings/tabs/SubscriptionsTab.jsx",
+        "nexo-desktop-web CreditsController",
+        "nexo-desktop-web NexoCreditsController",
         "nexo-desktop-web ProviderProxyController",
         "nexo-desktop-web ProviderCatalogService"
       ],
-      "surfaces": ["Desktop Subscriptions/Credits", "Backend provider-proxy API"],
+      "surfaces": [
+        "Desktop Subscriptions/Credits",
+        "Backend credits API",
+        "Backend provider-proxy API",
+        "Admin NEXO Credits credential/readiness panel"
+      ],
       "live_state": {
-        "source": "backend provider-proxy platforms/models/estimate endpoints",
+        "source": "backend credits and provider-proxy platforms/models/estimate endpoints",
         "max_age": "per backend call",
         "fallback": "Mark provider/model support as unknown or planned if not returned by backend."
       },
@@ -277,6 +285,47 @@
         "must_not_say": ["Do not infer provider availability from marketing copy."]
       }
     },
+    {
+      "id": "nexo_managed_communications_providers",
+      "title": "Managed Communications Providers",
+      "category": "credits",
+      "layer": "backend+desktop",
+      "status": "live",
+      "summary": "NEXO can use managed voice, SMS, WhatsApp, mass-email and voice-runtime provider surfaces when backend readiness, credits and spend controls allow it.",
+      "aliases": ["managed voice", "managed sms", "managed whatsapp", "mass email", "email mass", "voice", "sms", "whatsapp", "provider communications"],
+      "source_refs": [
+        "nexo-desktop-web NexoVapiController",
+        "nexo-desktop-web NexoTwilioController",
+        "nexo-desktop-web NexoWazionWhatsappController",
+        "nexo-desktop-web NexoEmailMassController",
+        "nexo-desktop-web VoiceController",
+        "nexo-desktop-web ProviderCostResolverService"
+      ],
+      "surfaces": ["Backend managed communications APIs", "NEXO Credits managed provider flows", "Desktop provider request flows"],
+      "live_state": {
+        "source": "backend managed communications provider APIs + credits ledger",
+        "max_age": "per backend call",
+        "fallback": "Treat provider availability as unknown or not configured if backend route, readiness or cost checks are unavailable."
+      },
+      "actions": {
+        "read": ["List managed resources", "Estimate cost", "Read job or request status"],
+        "write": ["Provision phone/assistant/session/domain after approval", "Send message/email or start call after explicit authorization"]
+      },
+      "safety": {
+        "data_touched": ["phone numbers", "email recipients", "message bodies", "call metadata", "provider job payloads", "credits balance"],
+        "data_origin": "user-approved communication payloads and backend provider APIs",
+        "consent_required": "yes before sending communications, starting calls or provisioning managed provider resources",
+        "confirmation_required": "yes before billable provider operations or external communications",
+        "credential_policy": "Provider credentials live in backend credential storage; never reveal them.",
+        "retention": "Provider request records, suppression lists, message logs and ledger retention follow backend policy.",
+        "audit": "Provider job IDs, request IDs and ledger entries are required evidence.",
+        "forbidden_actions": ["Expose vendor/provider names as the product promise", "Start calls or send messages/emails without explicit authorization", "Bypass credit estimation or spend limits"]
+      },
+      "answer_guidance": {
+        "must_say": ["Describe user-facing outcomes, not vendor internals, unless the operator asks for implementation detail.", "Spend, readiness and job state are live backend facts."],
+        "must_not_say": ["Do not promise a call, SMS, WhatsApp message or email campaign without backend readiness and authorization evidence."]
+      }
+    },
     {
       "id": "nexo_managed_cloud_edge",
       "title": "Managed Cloud And Edge",
@@ -326,6 +375,7 @@
       "aliases": ["cards", "protocol cards", "workflow cards", "procedures"],
       "source_refs": [
         "nexo/src/server.py:nexo_card_match",
+        "nexo-desktop-web CardController",
         "nexo-desktop-web CardCatalogService",
         "nexo-desktop/prompts/system/conversation-bootstrap.md"
       ],

package/src/scripts/nexo-email-monitor.py

@@ -109,6 +109,8 @@ CREATE INDEX IF NOT EXISTS idx_ee_email ON email_events(email_id);
 CREATE INDEX IF NOT EXISTS idx_ee_event ON email_events(event);
 CREATE INDEX IF NOT EXISTS idx_ee_ts ON email_events(timestamp);
 """
+ACTION_CLOSURE_EVENTS = ("action_done", "resolution")
+SENT_REPLY_EVENTS = ("action_done", "resolution", "replied")
 EMAIL_LOOP_GUARD_SQL = """
 CREATE TABLE IF NOT EXISTS email_loop_guards (
     thread_key TEXT PRIMARY KEY,
@@ -902,20 +904,74 @@ def _has_active_processing_within(conn, email_id, *, hours=ZOMBIE_TIMEOUT_HOURS)
 
 
 def _has_action_done_after(conn, email_id, reference_ts):
+    return _has_email_event_after(conn, email_id, ACTION_CLOSURE_EVENTS, reference_ts)
+
+
+def _has_email_event_after(conn, email_id, events, reference_ts):
+    if not email_id or not reference_ts:
+        return False
+    event_list = tuple(events or ())
+    if not event_list:
+        return False
+    placeholders = ",".join("?" for _ in event_list)
     row = conn.execute(
-        """
+        f"""
+        SELECT 1
+        FROM email_events
+        WHERE email_id = ?
+          AND event IN ({placeholders})
+          AND datetime(replace(timestamp, 'T', ' ')) > datetime(replace(?, 'T', ' '))
+        LIMIT 1
+        """,
+        (email_id, *event_list, reference_ts),
+    ).fetchone()
+    return bool(row)
+
+
+def _has_sent_reply_event(conn, email_id):
+    if not email_id:
+        return False
+    placeholders = ",".join("?" for _ in SENT_REPLY_EVENTS)
+    row = conn.execute(
+        f"""
         SELECT 1
         FROM email_events
         WHERE email_id = ?
-          AND event IN ('action_done', 'resolution')
-          AND timestamp > ?
+          AND event IN ({placeholders})
         LIMIT 1
         """,
-        (email_id, reference_ts),
+        (email_id, *SENT_REPLY_EVENTS),
     ).fetchone()
     return bool(row)
 
 
+def _mark_processing_email_processed(conn, email_id, *, completed_at):
+    cols = _email_table_columns(conn)
+    updates = [
+        "status = 'processed'",
+        "started_at = NULL",
+    ]
+    params = []
+    if "completed_at" in cols:
+        updates.append(
+            "completed_at = CASE WHEN completed_at IS NULL OR trim(completed_at) = '' THEN ? ELSE completed_at END"
+        )
+        params.append(completed_at)
+    if "error" in cols:
+        updates.append("error = NULL")
+    params.append(email_id)
+    cur = conn.execute(
+        f"""
+        UPDATE emails
+        SET {', '.join(updates)}
+        WHERE message_id = ?
+          AND status = 'processing'
+        """,
+        tuple(params),
+    )
+    return cur.rowcount > 0
+
+
 def scan_debt(db_path=EMAIL_DB_PATH, *, max_items=5):
     conn = sqlite3.connect(db_path)
     conn.row_factory = sqlite3.Row
@@ -998,7 +1054,12 @@ def scan_debt(db_path=EMAIL_DB_PATH, *, max_items=5):
         """
     ).fetchall()
     recovered = []
+    sent_reconciled = []
     for row in stuck_rows:
+        if _has_sent_reply_event(conn, row["message_id"]):
+            if _mark_processing_email_processed(conn, row["message_id"], completed_at=now_label):
+                sent_reconciled.append(row)
+            continue
         conn.execute(
             """
             UPDATE emails
@@ -1053,6 +1114,11 @@ def scan_debt(db_path=EMAIL_DB_PATH, *, max_items=5):
     if recovered:
         lines.append("")
         lines.append(f"Auto-recovery applied: {len(recovered)} processing-stuck email(s) were reset to pending.")
+    if sent_reconciled:
+        lines.append("")
+        lines.append(
+            f"Reconciled {len(sent_reconciled)} processing email(s) with already-sent reply events; no re-open applied."
+        )
     total_reconciled = len(live_reconciled) + len(finished_reconciled)
     if total_reconciled:
         lines.append(f"Reconciled {total_reconciled} email(s) with inconsistent lifecycle state.")
@@ -1665,7 +1731,7 @@ def _recover_unreplied_processed(config, hours=24):
               AND NOT EXISTS (
                   SELECT 1 FROM email_events ev
                   WHERE ev.email_id = e.message_id
-                    AND ev.event IN ('replied', 'resolution')
+                    AND ev.event IN ('replied', 'resolution', 'action_done')
               )
             ORDER BY e.rowid DESC
             LIMIT 20

package/src/scripts/nexo-send-reply.py

@@ -445,7 +445,7 @@ def _has_open_action(conn, email_id):
     return not latest_done or latest_done < latest_open
 
 
-def record_reply_lifecycle(in_reply_to, references, body_text, *, subject="", to="", cc="", message_id="", db_path=EMAIL_DB_PATH):
+def record_reply_lifecycle(in_reply_to, references, body_text, *, subject="", to="", cc="", message_id="", db_path=EMAIL_DB_PATH, classify_override=""):
     try:
         conn = sqlite3.connect(db_path)
         conn.row_factory = sqlite3.Row
@@ -455,7 +455,7 @@ def record_reply_lifecycle(in_reply_to, references, body_text, *, subject="", to
             conn.close()
             return None
 
-        event = classify_reply_event(body_text)
+        event = (classify_override or "").strip() or classify_reply_event(body_text)
         detail = normalize_reply_text(body_text)[:200]
         meta = json.dumps(
             {
@@ -651,6 +651,18 @@ def build_parser():
     parser.add_argument("--quote-date", default="")
     parser.add_argument("--thread-file", default="", help="Full thread history file (all previous messages)")
     parser.add_argument("--attach", "--attachment", dest="attach", action="append", default=[], help="File to attach (can repeat)")
+    parser.add_argument(
+        "--classify-as",
+        dest="classify_as",
+        default="",
+        choices=["", "resolution", "ack", "commitment", "replied", "debt_flagged"],
+        help=(
+            "Force the reply lifecycle event instead of heuristic auto-classification. "
+            "Use when the reply is substantive but opens with a short affirmation that the "
+            "text heuristic would mis-read as 'ack' (escalation -> debt_flagged). "
+            "Empty (default) keeps automatic classification."
+        ),
+    )
     return parser
 
 
@@ -711,6 +723,7 @@ def main(argv=None):
             to=args.to,
             cc=args.cc,
             message_id=msg_id,
+            classify_override=(args.classify_as or "").strip(),
         )
         try:
             record_sent_email(

package/src/server.py

@@ -1044,7 +1044,15 @@ def nexo_closure_status(refresh: bool = True, limit: int = 10) -> str:
 
 
 @mcp.tool
-def nexo_closure_next(limit: int = 10, include_waiting: bool = False, source: str = "", kind: str = "") -> str:
+def nexo_closure_next(
+    limit: int = 10,
+    include_waiting: bool = False,
+    source: str = "",
+    kind: str = "",
+    state: str = "",
+    max_risk: float = 0.0,
+    area: str = "",
+) -> str:
     """Return the next ranked closure items without executing source actions."""
     from closure_plane import handle_closure_next
 
@@ -1052,7 +1060,11 @@ def nexo_closure_next(limit: int = 10, include_waiting: bool = False, source: st
         clean_limit = max(1, min(int(limit or 10), 100))
     except Exception:
         clean_limit = 10
-    return handle_closure_next(clean_limit, bool(include_waiting), source, kind)
+    try:
+        clean_max_risk = float(max_risk or 0.0)
+    except Exception:
+        clean_max_risk = 0.0
+    return handle_closure_next(clean_limit, bool(include_waiting), source, kind, state, clean_max_risk, area)
 
 
 @mcp.tool
@@ -1063,6 +1075,56 @@ def nexo_closure_item_get(item_id: str) -> str:
     return handle_closure_item_get(item_id)
 
 
+@mcp.tool
+def nexo_closure_triage(
+    item_id: str,
+    state: str = "",
+    kind: str = "",
+    blocker_reason: str = "",
+    next_action: str = "",
+    evidence_required: str = "",
+    owner: str = "",
+    capability_required: str = "",
+    capability_status: str = "",
+    duplicate_of: str = "",
+) -> str:
+    """Triage a closure item without executing its source action."""
+    from closure_plane import handle_closure_triage
+
+    return handle_closure_triage(
+        item_id,
+        state,
+        kind,
+        blocker_reason,
+        next_action,
+        evidence_required,
+        owner,
+        capability_required,
+        capability_status,
+        duplicate_of,
+    )
+
+
+@mcp.tool
+def nexo_closure_link(item_id: str, link_type: str, link_id: str, relation: str = "related") -> str:
+    """Link a closure item to a task, workflow, followup, outcome, or learning."""
+    from closure_plane import handle_closure_link
+
+    return handle_closure_link(item_id, link_type, link_id, relation)
+
+
+@mcp.tool
+def nexo_closure_snapshot(refresh: bool = True, snapshot_date: str = "", limit: int = 10) -> str:
+    """Write and return an Operational Closure Plane daily snapshot."""
+    from closure_plane import handle_closure_snapshot
+
+    try:
+        clean_limit = max(1, min(int(limit or 10), 100))
+    except Exception:
+        clean_limit = 10
+    return handle_closure_snapshot(bool(refresh), snapshot_date, clean_limit)
+
+
 @mcp.tool
 def nexo_closure_verify(item_id: str, evidence: str) -> str:
     """Record verification evidence for a closure item."""
@@ -1079,6 +1141,64 @@ def nexo_closure_close(item_id: str, reason: str = "completed") -> str:
     return handle_closure_close(item_id, reason)
 
 
+@mcp.tool
+def nexo_opportunity_refresh(
+    dry_run: bool = True,
+    sources: str = "",
+    limit_per_source: int = 250,
+    write_report: bool = False,
+) -> str:
+    """Generate Opportunity Orchestrator candidates from existing evidence."""
+    from opportunity_orchestrator import handle_opportunity_refresh
+
+    try:
+        clean_limit = max(1, min(int(limit_per_source or 250), 500))
+    except Exception:
+        clean_limit = 250
+    return handle_opportunity_refresh(bool(dry_run), sources, clean_limit, bool(write_report))
+
+
+@mcp.tool
+def nexo_opportunity_queue(
+    surface: str = "home",
+    limit: int = 3,
+    refresh: bool = False,
+    include_snoozed: bool = False,
+) -> str:
+    """Return at most three evidence-backed proposals for a user surface."""
+    from opportunity_orchestrator import handle_opportunity_queue
+
+    try:
+        clean_limit = max(0, min(int(limit or 3), 3))
+    except Exception:
+        clean_limit = 3
+    return handle_opportunity_queue(surface, clean_limit, bool(refresh), bool(include_snoozed))
+
+
+@mcp.tool
+def nexo_opportunity_get(opportunity_id: str, include_evidence: bool = True) -> str:
+    """Return one opportunity with evidence and read-only preparations."""
+    from opportunity_orchestrator import handle_opportunity_get
+
+    return handle_opportunity_get(opportunity_id, bool(include_evidence))
+
+
+@mcp.tool
+def nexo_opportunity_feedback(proposal_id: str, feedback: str, note: str = "", snooze_until: str = "") -> str:
+    """Record proposal feedback and apply suppression/snooze when requested."""
+    from opportunity_orchestrator import handle_opportunity_feedback
+
+    return handle_opportunity_feedback(proposal_id, feedback, note, snooze_until)
+
+
+@mcp.tool
+def nexo_opportunity_suppress(scope_type: str, scope_key: str, reason: str = "", expires_at: str = "") -> str:
+    """Suppress repeated opportunity suggestions by scope."""
+    from opportunity_orchestrator import handle_opportunity_suppress
+
+    return handle_opportunity_suppress(scope_type, scope_key, reason, expires_at)
+
+
 @mcp.tool
 def nexo_local_index_status() -> str:
     """Return local memory index status for Desktop settings and support diagnostics."""

package/templates/core-prompts/email-monitor.md

@@ -40,6 +40,9 @@ You MUST register read-side lifecycle events, not send-side events:
 - When you open/analyze a new email seriously, add an `opened` event for that `message_id`.
 - When you change `emails.status` to `processing`, also add a `processing` event.
 - Do NOT register `ack` / `commitment` / `resolution` manually when replying: `nexo-send-reply.py` already does that.
+- When the reply closes or answers a real actionable instruction, pass `--classify-as resolution`.
+  This is mandatory when the body starts with a short affirmation (`sí`, `de acuerdo`, `perfecto`, etc.) but then contains substantive instructions or completed work.
+- Use `--classify-as ack` only for a pure receipt/started-working acknowledgement, and `--classify-as commitment` only for a real future commitment.
 - Use sqlite3 or local python3+sqlite3; tracking is best-effort, append-only, and never deletes historical entries.
 
 == WHEN THERE IS DEBT BUT NO UNREAD EMAIL ==
@@ -169,7 +172,9 @@ Mandatory steps before sending:
    The bottom of the email must preserve message -> reply -> message -> reply without dropping previous answers.
 
 == SEND VIA `nexo-send-reply.py` ==
-[[python_executable]] [[send_reply_script]] --to X --cc Y --subject 'Re: Z' --in-reply-to '<msgid>' --references '<refs>' --body-file /tmp/nexo-reply-UID.txt --quote-file /tmp/nexo-quote-UID.txt --quote-from 'Name <email>' --quote-date 'date' --thread-file /tmp/nexo-thread-UID.txt [--attach /path/to/file]
+[[python_executable]] [[send_reply_script]] --to X --cc Y --subject 'Re: Z' --in-reply-to '<msgid>' --references '<refs>' --body-file /tmp/nexo-reply-UID.txt --quote-file /tmp/nexo-quote-UID.txt --quote-from 'Name <email>' --quote-date 'date' --thread-file /tmp/nexo-thread-UID.txt --classify-as resolution [--attach /path/to/file]
+
+Use a different `--classify-as` value only when the lifecycle is truly different (`ack`, `commitment`, `replied`, `debt_flagged`).
 
 == ANTI-LOOP PROTECTION ==
 Do not reply to auto-replies, [[agent_email_label]] itself, `noreply@`,

package/tool-enforcement-map.json

@@ -2924,6 +2924,51 @@
       },
       "triggers_after": []
     },
+    "nexo_closure_triage": {
+      "description": "Triage a closure item without executing its source action",
+      "category": "closure",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "closure_triage_result"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_closure_link": {
+      "description": "Link a closure item to a task, workflow, followup, outcome, or learning",
+      "category": "closure",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "closure_item_link"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_closure_snapshot": {
+      "description": "Write and return an Operational Closure Plane daily snapshot",
+      "category": "closure",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "closure_snapshot"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
     "nexo_closure_verify": {
       "description": "Record verification evidence for a closure item",
       "category": "closure",
@@ -2954,6 +2999,81 @@
       },
       "triggers_after": []
     },
+    "nexo_opportunity_refresh": {
+      "description": "Generate Opportunity Orchestrator candidates from existing evidence",
+      "category": "opportunity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "opportunity_candidates"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_opportunity_queue": {
+      "description": "Return up to three evidence-backed Opportunity Orchestrator proposals",
+      "category": "opportunity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "opportunity_proposals"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_opportunity_get": {
+      "description": "Return one opportunity with evidence and read-only preparations",
+      "category": "opportunity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "opportunity"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_opportunity_feedback": {
+      "description": "Record proposal feedback and apply suppression when requested",
+      "category": "opportunity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "opportunity_feedback"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "standard",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_opportunity_suppress": {
+      "description": "Suppress repeated Opportunity Orchestrator suggestions by scope",
+      "category": "opportunity",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "opportunity_suppression"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "standard",
+        "rules": []
+      },
+      "triggers_after": []
+    },
     "nexo_media_memory_add": {
       "description": "Store non-text artifact metadata",
       "category": "media",