systemprompt-scheduler 0.21.1

Background jobs, cron tasks, and job-extension dispatch for systemprompt.io AI governance infrastructure. Tokio-backed scheduling for the MCP governance pipeline.
Documentation

Production infrastructure for AI agents

Website · Documentation · Guides · Core · Template · Discord

systemprompt-scheduler

Crates.io Docs.rs License: BSL-1.1 codecov

The maintenance and enforcement work that keeps a self-hosted deployment healthy runs here, inside your own binary. Session cleanup, orphaned-record reaping, and malicious-IP blacklisting run as background jobs on cron schedules, discovered at compile time through the inventory crate and dispatched with panic isolation on a Tokio runtime.

Layer: App, orchestrates domain modules. Part of the systemprompt-core workspace.

Overview

Jobs are discovered through inventory and executed on configurable cron schedules. Alongside job execution, the crate reconciles long-running service state: it compares the desired configuration against the observed runtime and takes the action that closes the gap.

Infrastructure · Self-Hosted Deployment

Modules

Module Purpose
jobs Background jobs implementing the Job trait, each registered via inventory
services/scheduling SchedulerService job discovery and execution, plus dispatch, bootstrap, distributed lock, and job owners resolution
services/job_execution Single-job execution path with status tracking
services/service_management ServiceManagementService lifecycle operations (query, stop, cleanup)
services/orchestration Service state reconciliation (ServiceStateVerifier, ServiceReconciler, VerifiedServiceState, cross-platform process_cleanup)
services/plans Declarative service plans consumed by the reconciler
models JobConfig, JobStatus, ScheduledJob, SchedulerConfig
repository SchedulerRepository facade over job, analytics, and security queries
error SchedulerError, SchedulerResult
extension SchedulerExtension (schemas, registered jobs)

Jobs

Each job implements the Job trait from systemprompt-traits and is registered via inventory for automatic discovery.

Job Schedule Description
CleanupInactiveSessionsJob Every 10 min Closes sessions inactive for 1 hour
CleanupEmptyContextsJob Every 2 hours Removes conversation contexts with no messages
DatabaseCleanupJob Daily at 3 AM Deletes orphaned logs, MCP executions, expired OAuth tokens
BehavioralAnalysisJob Hourly Analyses fingerprint patterns, flags suspicious activity, bans repeat offenders
MaliciousIpBlacklistJob Every 6 hours Detects high-volume, scanner, datacenter, and high-risk country IPs
GhostSessionCleanupJob Periodic Reaps abandoned ghost sessions left by disconnected clients
NoJsCleanupJob Periodic Prunes no-JavaScript fingerprint rows past retention

Service reconciliation

ServiceStateVerifier (in services/orchestration/state_verifier.rs) compares observed runtime state against the database record; ServiceReconciler executes the action that reconciles desired versus actual state.

Type Values
DesiredStatus Enabled, Disabled
RuntimeStatus Running, Starting, Stopped, Crashed, Orphaned
ServiceAction None, Start, Stop, Restart, CleanupDb, CleanupProcess

Usage

[dependencies]
systemprompt-scheduler = "0.21"

Job Discovery

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

use systemprompt_provider_contracts::submit_job;

submit_job!(MyCustomJob);

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

use systemprompt_scheduler::{SchedulerService, SchedulerConfig};

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

Dependencies

Crate Purpose
systemprompt-runtime AppContext
systemprompt-database Database pool and repositories
systemprompt-extension Extension trait
systemprompt-logging SystemSpan for tracing
systemprompt-analytics SessionRepository, FingerprintRepository
systemprompt-users BannedIpRepository
systemprompt-traits Job trait definition
systemprompt-provider-contracts submit_job! macro and provider registry
systemprompt-identifiers ScheduledJobId
systemprompt-models Config types
tokio-cron-scheduler Cron scheduling runtime
nix (unix) POSIX process signals for orchestration cleanup

License

BSL-1.1 (Business Source License). Source-available for evaluation, testing, and non-production use. Production use requires a commercial license. Each version converts to Apache 2.0 four years after publication. See LICENSE.

systemprompt.io · Documentation · Guides · Live Demo · Template · crates.io · docs.rs · Discord

App layer · Own how your organization uses AI.