Heartbeat Loops & Wakeup Triggers

The dLAN Assistant operates on a "Pulse and Trigger" architecture. Heartbeats provide proactive, interval-based intelligence, while Wakeups provide reactive, event-driven responses.

💓 Heartbeat Loops (assistant/heartbeat.go)

These routines maintain system health and provide "Background Thinking" - waking specific agents at intervals to check for pending work.

Agent-Specific Work Loops

System Heartbeats

Security & Monitoring Heartbeats

Quiet Hour Focus

Nikki and Lenore work loops respect quiet hours (20:00-08:00):

// Work loops skip execution during quiet hours
if isQuietHour() {
    return // Skip Nikki/Lenore work loop checks
}

Heartbeat Optimization (April 2026)

🔄 Background Services (Other Polling Systems)

Telemetry Poller (assistant/telemetry_poller.go)

• Interval: 5 minutes
• Purpose: Polls all system modules to keep dashboard/AI context updated
• Polled Systems:
  • Proxmox (CPU, RAM, containers)
  • cPanel dashboard (hosting stats)
  • CoinStats (crypto prices)
  • Pelican (network stats)
  • Virtdash (virtualization)

GitLab Poller (assistant/gitlab_poller.go)

• Trigger: Called by Gilfoyle heartbeat (5m day / 60m night)
• Purpose: Detects GitLab pushes, queues for 3 AM Security Ritual
• State: Persisted to assistant/logs/gitlab_poller_state.json
• Features: Batches multiple pushes, tracks event IDs

CCTV Monitor (assistant/cctv_monitor.go)

• Interval: 2 minutes (polling)
• Triggers: Doorbell press, Person detection, Motion anomalies
• Action: Summons RoboCop for analysis
• Overnight Check: Daily at 07:45

⚡ Wakeup Triggers (assistant/wakeup.go)

The wakeup system is a Unified Event Router that provides reactive, near-instantaneous responses to external events. It runs on port 7142.

Event Sources & Handlers

1. UniFi Presence (Arrival/Departure)

• Source: UniFi Controller API polling every 3 minutes
• Logic: Detects MAC address of tracked devices (Dan, Liz)
• Debounce: 10 min for arrival, 30 min for departure
• Action: Triggers "Welcome Home" briefings with persona-aware greetings

User Routing:

2. YouTube PubSubHubbub

• Endpoint: /api/events/youtube
• Source: YouTube channel subscriptions via PubSubHubbub
• Action: Notifies appropriate agent (typically Nikki) of new content
• Use Case: Proactive notifications when subscribed channels upload

3. Home Assistant / Google Home

• Endpoint: /api/events/ha
• Source: Home Assistant automations, Google Home commands
• Payload: { "command": "...", "user": "...", "entity_id": "...", "new_state": "..." }
• Action: Process voice commands, state change triggers

4. Vonage Inbound SMS

• Endpoint: /api/events/vonage/inbound
• Source: Vonage webhook for inbound SMS
• RBAC: Only responds to known contacts (Guest/Banned rejected)
• Action: Routes SMS to preferred agent (default: Sasha), sends SMS reply

5. Generic Wakeup API

• Endpoint: /api/wakeup
• Method: POST
• Payload:

{
  "agent": "nikki",
  "user": "dan",
  "platform": "whatsapp",
  "prompt": "Good morning! Check the servers.",
  "task_id": "optional-task-reference"
}

• Action: Wakes any agent with custom prompt - enables external apps/servers to trigger the assistant

6. WHMCS Ticket Watcher

• Source: WHMCS API polling (started from wakeup.go line 180)
• Logic: Tracks last processed ticket ID, processes new tickets only
• Action: Notifies Nova agent with deep context about new tickets
• State: assistant/whmcs_state.json
• Implementation: assistant/whmcs_client.go - runs as background goroutine

7. CCTV Event (RoboCop Integration)

• Source: Reolink NVR AI Detection
• Trigger: EventTypeDoorbell, EventTypePerson
• Action: Captures tactical snapshot, summons RoboCop for analysis

🛠️ External Integration Examples

Wake Any Agent from External System

# Wake Nikki for a custom task
curl -X POST http://localhost:7142/api/wakeup \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "nikki",
    "user": "dan",
    "platform": "whatsapp",
    "prompt": "External trigger: Backup completed on server XYZ"
  }'

# Wake Sasha for infrastructure check
curl -X POST http://localhost:7142/api/wakeup \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "sasha",
    "user": "dan",
    "platform": "discord",
    "prompt": "Check Proxmox cluster health"
  }'

Home Assistant Integration

# automation.yaml
- alias: "AI Assistant Trigger"
  trigger:
    - platform: state
      entity_id: binary_sensor.motion_office
  action:
    - service: http.post
      data:
        url: "http://localhost:7142/api/events/ha"
        payload:
          command: "Motion detected in office"
          user: "dan"
          entity_id: "binary_sensor.motion_office"
          new_state: "on"

⏰ Two Scheduling Systems

1. Heartbeats (Internal - No User Control)

• Hardcoded intervals in heartbeat.go
• Wake specific agents to check for pending work
• Cannot be disabled by users
• Examples: Nikki work loop, Architect audits, RoboCop CCTV

2. Scheduler (User-Configurable - scheduler.go)

• SQLite-backed persistent task storage
• Users can add tasks via API: /api/schedule-task
• Supports both one-time (execute_at) and recurring (cron_spec)
• Tasks persist across restarts
• Dashboard shows at: Mission Control → Scheduler

Adding a scheduled task:

curl -X POST http://localhost:9999/api/schedule-task \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "nikki",
    "task": "Daily report for Master Dan",
    "cron_spec": "0 8 * * *"
  }'

📅 Actual Scheduled Tasks (from scheduler.db)

Nikki's Daily Routine

Nikki's Weekly Routine

Nikki's Nightly Routine

Lenore's Routine

Sasha's Routine

Nova's Routine

CEO/Business Hive

Memory/System

Miscellaneous

Total scheduled tasks in database: 40+

📦 Skills Import Capability

While this is a private system (not open-source) with no community marketplace, the architecture supports importing skills from external sources:

Supported Import Formats

Import Process

1. Skill Discovery: Find skill in external format (SKILL.md, JSON, GitHub)
2. Format Conversion: Map to internal tool definition format:

   # tool_name
   ## Description
   ...
   ## Parameters
   {"type": "object", ...}
   ## Access
   MasterAdmin, Partner
   

3. Tool Implementation: Create shell script or Go handler for execution
4. RBAC Gating: Set appropriate access roles
5. Live Injection: No restart needed - tools loaded from filesystem

Example: Converting OpenClaw Skill

# OpenClaw SKILL.md format:
# # skill_name
# ## What it does
# ## Triggers
# ## Actions

# Convert to dLANDiscord tool format:
# assistant/prompts/tools/shared/skill_name.md

This enables the system to leverage the broader AI agent ecosystem's skill libraries without maintaining a public marketplace.

Session Reliability (April 2026)

Planner Session get_capabilities Fix

Issue: WhatsApp-initiated planner sessions failed because LLMs returned empty/text responses without calling get_capabilities. Scheduled/playbook sessions worked because they forced the call in code.

Fix: ProcessReActLoop in planner.go now forces get_capabilities for ALL planner sessions regardless of source (WhatsApp, scheduled, playbook, etc.).

Location: assistant/planner.go — ProcessReActLoop initial tool injection

Shared Tools Full Definitions

Issue: shared_tools capability returned only tool names, not full definitions.

Fix: GetSystemCapabilities in assistant.go now returns complete Tool structs with name, description, and parameters.

🚀 System Startup (main.go)

These services start when the application boots:

Boot Sequence

// main.go line ~174
assistant.StartHeartbeat()      // All heartbeat loops
assistant.StartWakeupSystem()   // UniFi presence polling
assistant.StartWakeupServer()   // Port 7142 API

// Scheduler
scheduler, err := assistant.NewScheduler("./scheduler.db")
scheduler.Start()
assistant.GlobalScheduler = scheduler

// Observability
observabilityDB, err := assistant.NewObservabilityDB("./observability.db")
assistant.GlobalObservabilityDB = observabilityDB

Best Practices

• Isolation: When adding new heartbeat, assign to relevant agent persona for clean telemetry
• Adaptive Polling: Background tasks should slow at night (except security rituals)
• Error Handling: Heartbeat loops must use recover() or clean error logging to prevent crashes
• Capability Injection: Ensure planner agents have access to system capabilities before planning
• External Triggers: Use /api/wakeup for any external system integration needs
• RBAC: Always validate user roles in event handlers (Guest/Banned rejected)

Panic Recovery (May 18, 2026)

All heartbeat and scheduler goroutines are now wrapped with safeGo() — a helper that wraps recover() + debug.Stack() logging. This prevents silent goroutine deaths:

• All 18 heartbeat loops now use safeGo() for panic recovery
• Main scheduler goroutine has recover() at line 665 in scheduler.go
• Per-tick recovery around checkAndExecuteDueTasks() calls
• SQLite WAL mode enabled on scheduler DB (busy_timeout=5000) to prevent SQLITE_BUSY errors

This fixed the May 18 scheduler crash that stopped all scheduled tasks.

Key Files

Cross-References

• Key-Packages/assistant/overview.md
• Tools-Skills-Memory.md
• Welcome Home Pipeline
• Scheduler & Heartbeat