Assistant Scheduler and Heartbeat

The scheduler and heartbeat systems are the proactive core of the dLANDiscord Assistant, enabling autonomous background tasks, periodic maintenance, and resilient system-wide audits.

1. The Persistent Scheduler (scheduler.go)

The Scheduler is a robust, SQLite-backed task runner designed for both precise one-off executions and recurring cron-based jobs.

Key Logic & Functions

• NewScheduler(): Initializes the SQLite database (scheduler.db) and starts the tick loop (every 10 seconds).
• AddScheduledTask(): Persists a new task with its target agent, prompt, and cron spec.
• checkAndExecuteDueTasks(): The core brain of the tick loop. It scans the DB for tasks where execute_at is in the past, spawns an asynchronous goroutine for execution, and updates the state to InProgress.
• ExecuteScheduledTask(): Spawns a persona-aware ChatSession and runs the ReAct loop. It implements strict Panic Recovery; if an execution crashes, the system catches the panic, logs it, and marks the task as Failed instead of crashing the whole application.

Evolution: Zombie Cleanup

As seen in Git commit 4688e175, the system was enhanced with CleanupStaleRunningExecutions(). This function identifies "zombie" tasks (executions stuck in InProgress for more than 2x their timeout) and automatically terminates them to free up resources.

2. Heartbeat Loops (heartbeat.go)

The Heartbeat system manages "internal" proactive routines that don't necessarily originate from a user request.

3. Wakeup API and Event Router (wakeup.go)

The Wakeup server (Port :7142) acts as the Unified Event Router - the bridge between external triggers and proactive agents.

Event Sources

Features

• Arrival Enrichment: When a user arrives home (detected via UniFi), the triggerWelcomeHome function provides the agent with an "Arrival Snapshot"—a summary of all significant system events that occurred while the user was away.
• Resilience: The executeWakeupTask function uses a 10-minute timeout and a circuit-breaker to prevent external network spikes (like a YouTube PubSub storm) from overwhelming the local LLM.
• External Wakeup: Any external system can trigger any agent via POST to /api/wakeup:

{ "agent": "nikki", "user": "dan", "platform": "whatsapp", "prompt": "..." }

Component Diagram: Proactive Pipeline

graph TD
    S[Scheduler DB] --> |Tick| Runner[Task Runner]
    H[Heartbeat Loops] --> |Signal| Runner
    W[Wakeup API] --> |Signal| Runner
    
    Runner --> |Spawn| Session[ChatSession]
    Session --> |Execute| Agent[Nikki / Sasha / Oracle]
    Agent --> |Result| Notify[Omnichannel Notifier]
    
    subgraph "Error Recovery"
        Runner --> Panic[Panic Recovery]
        Runner --> Zombie[Zombie Cleanup]
    end

Guidance for AI Agents

• Schedule Proactively: If a user asks you to "remind me in 2 hours," use the schedule_task tool. This persists the request even if the current session is closed or the server restarts.
• Audit SITREPs: Review the execution_logs in Mission Control to see how your background "twins" are performing their maintenance tasks.

Cross-References

• Features/assistant/observability-and-logging.md
• Features/assistant/welcome-home-pipeline.md