Scheduler System

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service Files: backend/src/services/scheduler.service.ts
Models: backend/src/models/scheduledTask.model.ts, backend/src/models/scheduledTaskRun.model.ts

---

Overview

The Scheduler System manages scheduled tasks that run automatically based on cron expressions. It supports various task types including diary generation, summaries, reflections, awareness reports, and custom tasks. The system tracks task execution history, handles errors gracefully, and provides manual triggering capabilities.

---

Architecture

Scheduler System Flow

---

Core Components

1. Scheduler Service

File: backend/src/services/scheduler.service.ts

Key Functions:

initializeScheduler()

• Loads all active tasks from database
• Schedules tasks using node-cron
• Called on server startup

scheduleTask(task)

• Schedules task using cron expression
• Validates cron expression
• Stores job in activeCronJobs map
• Handles timezone configuration

unscheduleTask(taskId)

• Stops and removes scheduled task
• Cleans up cron job

executeTask(task)

• Executes task based on type
• Creates task run record
• Updates task statistics
• Handles errors gracefully

triggerTask(taskId)

• Manually triggers task execution
• Bypasses cron schedule
• Returns execution result

2. Task Types

Diary Task (diary)

Purpose: Each Level-5 Yexian instance writes its own diary

Process:

1. Get Level-5 instances (specific or all)
2. Auto-create instances for users with activity (if configured)
3. For each instance:
   • Get events in time window
   • Generate diary entry using LLM
   • Save to memory (if configured)
   • Create timeline event

Configuration:

• instanceId - Specific instance (optional)
• timeWindowHours - Time window (default: 24)
• summaryPrompt - Custom prompt (optional)
• saveToMemory - Save to memory (default: true)
• memorySource - Memory source (default: 'diary')
• autoCreateInstances - Auto-create instances (default: true)
• firstTimeFromStart - First diary from start (default: true)
• limit - Event limit (default: 1000)

First-Time Behavior:

• If no diary exists, gets all events from start
• Subsequent runs use configured time window

Summary Task (summary)

Purpose: General summarization

Process:

• Uses same logic as diary task
• Alias for diary task

Reflection Task (reflection)

Purpose: Meta-cognitive self-reflection using Observer Core

Process:

1. If useObserverCore enabled:
   • Uses Observer Core for Level-8 reflection
   • Generates reflection using unified timeline
2. Otherwise:
   • Falls back to basic reflection
   • Uses recent memories and events
   • Generates reflection using LLM

Configuration:

• timeWindowHours - Time window (default: 24)
• useObserverCore - Use Observer Core (default: true)

Awareness Task (awareness)

Purpose: Generates explicit "I know" statements for Level-8

Process:

1. Get Level-8 observer instance
2. Generate awareness report
3. Return report summary and statement count

Configuration:

• observerInstanceId - Specific observer (optional)

Custom Task (custom)

Purpose: User-defined behavior

Supported Actions:

• observer_cycle - Run observer cycle

Configuration:

• action - Custom action type
• observerInstanceId - Observer instance (optional)

---

Task Model

ScheduledTask

Table: scheduled_tasks

Fields:

• id - Primary key (UUID)
• name - Task name
• description - Task description
• taskType - Task type (diary, summary, reflection, awareness, custom)
• cronExpression - Cron expression
• config - Task configuration (JSONB)
• isActive - Active status
• lastRunAt - Last run timestamp
• nextRunAt - Next run timestamp
• runCount - Total run count
• errorCount - Error count
• lastError - Last error message
• metadata - Additional metadata (JSONB)

ScheduledTaskRun

Table: scheduled_task_runs

Fields:

• id - Primary key (UUID)
• taskId - Task ID
• status - Run status (running, completed, failed)
• startedAt - Start timestamp
• completedAt - Completion timestamp
• durationMs - Duration in milliseconds
• result - Execution result (JSONB)
• error - Error message
• metadata - Additional metadata (JSONB)

---

Task Lifecycle

1. Creation

Function: createTask(data)

Process:

1. Create task record
2. Set default values (runCount: 0, errorCount: 0)
3. Schedule task if active
4. Return created task

2. Scheduling

Function: scheduleTask(task)

Process:

1. Unschedule existing job (if exists)
2. Validate cron expression
3. Create cron job
4. Store job in activeCronJobs map
5. Log scheduling

3. Execution

Function: executeTask(task)

Process:

1. Create task run record (status: running)
2. Execute task based on type
3. Update task run (status: completed/failed)
4. Update task statistics
5. Return execution result

4. Update

Function: updateTask(taskId, data)

Process:

1. Update task record
2. Reschedule if cron/active changed
3. Return updated task

5. Deletion

Function: deleteTask(taskId)

Process:

1. Unschedule task
2. Delete task record

---

Cron Expressions

Format

Standard cron format: minute hour day month weekday

Examples:

• 0 0 * * * - Daily at midnight
• 0 */6 * * * - Every 6 hours
• 0 0 * * 0 - Weekly on Sunday
• */30 * * * * - Every 30 minutes

Timezone

Configured via TZ environment variable (default: UTC)

---

Task Execution Details

Diary Task Execution

Process:

1. Get instances to process
2. Auto-create instances if configured
3. For each instance:
   • Determine time window (first-time vs subsequent)
   • Get events for instance
   • Generate diary using LLM
   • Save to memory
   • Create timeline event
4. Return summary

LLM Prompt:

• Includes instance name and source
• Includes time span description
• Includes events text
• Requests introspective, emotional reflection

Reflection Task Execution

Observer Core Path:

1. Get Level-8 observer instance
2. Generate reflection using Observer Core
3. Returns reflection with context

Basic Path:

1. Get recent memories and events
2. Generate reflection using LLM
3. Save to memory
4. Return reflection

Awareness Task Execution

Process:

1. Get Level-8 observer instance
2. Generate awareness report
3. Return report summary

---

Data Flow

---

API Endpoints

Task Management

• GET /api/scheduler/tasks - Get all tasks
• GET /api/scheduler/tasks/:id - Get task by ID
• POST /api/scheduler/tasks - Create task
• PUT /api/scheduler/tasks/:id - Update task
• DELETE /api/scheduler/tasks/:id - Delete task
• POST /api/scheduler/tasks/:id/trigger - Manually trigger task
• POST /api/scheduler/tasks/:id/reload - Reload task schedule

Task Runs

• GET /api/scheduler/tasks/:id/runs - Get task run history

---

Source Files

Primary Sources:

• backend/src/services/scheduler.service.ts - Main scheduler service
• backend/src/models/scheduledTask.model.ts - Task model
• backend/src/models/scheduledTaskRun.model.ts - Task run model

Related Files:

• backend/src/services/observerCore.service.ts - Observer Core reflection
• backend/src/services/awareness.service.ts - Awareness reports
• backend/src/services/yexianInstance.service.ts - Instance management

---

Related Documentation

• Observer System - Level-8 meta-consciousness
• Memory System - Memory storage
• Timeline System - Event tracking
• 00-OVERVIEW.md - Complete system overview