Assistant Notification System

The assistant module features a robust, omnichannel notification framework for delivering alerts, reports, and agent results across multiple platforms.

Omnichannel Support

The system can deliver notifications through several channels, coordinated by assistant/notifications.go:

WhatsApp: Primary channel for mobile DMs and group alerts.
Discord: Used for community updates and technical alerts.
Telegram: High-performance channel for administrative alerts.
SMS (Vonage): Fallback for critical alerts to known contacts.
Email (SMTP): For long-form reports and technical SITREPs.

Notification Types

1. User Notifications (`notify_user`)

A general-purpose tool that allows agents to send messages to specific users or groups. It supports Markdown and platform-specific formatting.

2. Async Completion Notifications

Triggered when a background task (delegated via call_agent_async) completes. These use Zombie Contexts to find the original user even if the session has expired.

3. System Alerts

Proactive alerts generated by the Architect or NOC Intelligence systems. These are often routed to specific "God-Tier" channels for immediate attention.

Notification Routing Logic

The system uses a NotificationRequest structure to route messages:

Platform Detection: Identifies the target platform from the ChatID or user profile.
Persona Formatting: For agent results, the notification is wrapped in the agent's persona (e.g., "Nikki here! I've finished the audit...").
Fallback Logic: If a primary platform is unreachable, the system can attempt delivery via a secondary channel (e.g., WhatsApp → SMS).

Component Diagram: Notification Routing

graph TD
    A[Agent / System] --> NR[Notification Request]
    NR --> Router[Notification Router]
    
    subgraph "Channels"
        Router --> WA[WhatsApp Client]
        Router --> DI[Discord Client]
        Router --> TG[Telegram Client]
        Router --> SN[SMS / Vonage]
        Router --> EM[Email Provider]
    end
    
    WA --> U([User])
    DI --> U
    TG --> U
    SN --> U
    EM --> U

Key Files & Functions

assistant/notifications.go: The central router and handleNotifyUser implementation.
assistant/vonage.go: Direct SMS integration.
assistant/email_provider.go: SMTP integration.
NotifyUserAsyncComplete(): Fallback logic for asynchronous results.

Guidance for AI Agents

Use the Right Channel: Use notify_user for standard messages. For critical, time-sensitive alerts, consider mentioning the user's role or using a high-priority flag.
Persona Integrity: When notifying a user of a sub-agent's result, ensure the notification sounds like it's coming from that sub-agent.