Production infrastructure for AI agents

systemprompt.io • GitHub • Documentation

systemprompt-scheduler

Core scheduler module for systemprompt.io OS - background jobs and cron tasks.

Overview

Part of the App layer in the systemprompt.io architecture.

Background job scheduling and execution module. Discovers jobs via the inventory crate and executes them on configurable cron schedules.

File Structure

src/
├── lib.rs                                    # Public exports
├── jobs/
│   ├── mod.rs                                # Job exports
│   ├── behavioral_analysis.rs                # Analyzes fingerprint behavior patterns
│   ├── cleanup_empty_contexts.rs             # Removes empty conversation contexts
│   ├── cleanup_inactive_sessions.rs          # Closes inactive sessions
│   ├── database_cleanup.rs                   # Orphaned logs, MCP, OAuth cleanup
│   └── malicious_ip_blacklist.rs             # Detects and blacklists malicious IPs
├── models/
│   └── mod.rs                                # JobStatus, SchedulerError, ScheduledJob
├── repository/
│   ├── mod.rs                                # SchedulerRepository facade
│   ├── analytics/
│   │   └── mod.rs                            # Analytics cleanup queries
│   ├── jobs/
│   │   └── mod.rs                            # Scheduled job CRUD operations
│   └── security/
│       └── mod.rs                            # IP session queries for malicious detection
└── services/
    ├── mod.rs                                # Service exports
    ├── service_management.rs                 # Service lifecycle management
    ├── scheduling/
    │   └── mod.rs                            # SchedulerService - job discovery and execution
    └── orchestration/
        ├── mod.rs                            # Orchestration exports
        ├── process_cleanup.rs                # Process management utilities
        ├── reconciler.rs                     # Service state reconciliation
        ├── state_manager.rs                  # Service state verification
        ├── state_types.rs                    # DesiredStatus, RuntimeStatus, ServiceAction
        └── verified_state.rs                 # VerifiedServiceState with builder pattern

Modules

jobs/

Background jobs that implement the Job trait from systemprompt-traits. Each job is registered via inventory::submit! for automatic discovery.

models/

Domain types for the scheduler:

• JobStatus - Enum: Success, Failed, Running
• SchedulerError - Error types with thiserror derive
• ScheduledJob - Database model for job tracking

repository/

Data access layer for scheduler operations:

• SchedulerRepository - Facade combining job and analytics repositories
• JobRepository - CRUD for scheduled_jobs table
• AnalyticsRepository - Cleanup queries for user_contexts
• SecurityRepository - IP session queries for malicious IP detection

services/

scheduling/

SchedulerService - Core scheduler that:

• Discovers jobs via inventory crate
• Registers jobs with tokio-cron-scheduler
• Tracks job execution status
• Uses SystemSpan for structured logging

service_management/

ServiceManagementService - Service lifecycle operations:

• Query services by type
• Stop services (graceful or forced)
• Cleanup orphaned services

orchestration/

State machine for service reconciliation:

• ServiceStateManager - Verifies actual runtime state vs database state
• ServiceReconciler - Executes actions to reconcile desired vs actual state
• VerifiedServiceState - Immutable state snapshot with builder pattern
• ProcessCleanup - Low-level process management (kill, check port, etc.)

State types:

• DesiredStatus - Enabled | Disabled
• RuntimeStatus - Running | Starting | Stopped | Crashed | Orphaned
• ServiceAction - None | Start | Stop | Restart | CleanupDb | CleanupProcess

Job Discovery

Jobs are discovered via the inventory crate. Any crate can register jobs:

inventory::submit! { &MyCustomJob }

The scheduler discovers all registered jobs at startup and schedules them based on configuration.

Dependencies

Usage

use systemprompt_scheduler::{SchedulerService, SchedulerConfig};

let config = SchedulerConfig::from_context(&app_context);
let service = SchedulerService::new(config, db_pool, app_context)?;
service.start().await?;

Installation

Add to your Cargo.toml:

[dependencies]
systemprompt-scheduler = "0.0.1"

License

FSL-1.1-ALv2 - See LICENSE for details.