Crate zeph_scheduler 

Cron-based periodic task scheduler with SQLite persistence.

zeph-scheduler drives time-based work inside the Zeph agent. It supports two task execution modes:

• Periodic — tasks defined by a cron expression and re-scheduled after each run.
• One-shot — tasks that run once at a specific DateTime<Utc> and are removed on completion.

Architecture

┌──────────────────────────────────────┐
│              Scheduler               │
│  tasks: Vec<ScheduledTask>           │
│  handlers: HashMap<kind, TaskHandler>│
│  store: JobStore (SQLite)            │
│  shutdown_rx: watch::Receiver<bool>  │
│  task_rx: mpsc::Receiver<Msg>        │
└───────────┬──────────────────────────┘
            │ tick() every N seconds
            ▼
    for each due task → handler.execute()
            │
            ▼
    store.record_run() / store.mark_done()

Quick Start

use tokio::sync::watch;
use zeph_scheduler::{JobStore, Scheduler, ScheduledTask, TaskKind};

// 1. Open the job store.
let store = JobStore::open("sqlite:scheduler.db").await?;

// 2. Create the scheduler.
let (_shutdown_tx, shutdown_rx) = watch::channel(false);
let (mut scheduler, _msg_tx) = Scheduler::new(store, shutdown_rx);

// 3. Register a periodic task (every minute).
let task = ScheduledTask::new(
    "health-check",
    "*/1 * * * *",
    TaskKind::HealthCheck,
    serde_json::Value::Null,
)?;
scheduler.add_task(task);

// 4. Initialise persistence and run.
scheduler.init().await?;
scheduler.run().await;

Cron Expression Format

The scheduler accepts both 5-field (min hour day month weekday) and 6-field (sec min hour day month weekday) cron expressions. Five-field expressions are automatically normalised by prepending "0 " (seconds = 0). Use normalize_cron_expr directly if you need the canonical form.

Shutdown

Send true on the watch::Sender<bool> that was passed to Scheduler::new to trigger a graceful shutdown. The scheduler loop exits on the next tick.

SQLite Persistence

All job definitions and run history are stored in a SQLite database managed by zeph-db migrations. Use JobStore::open to connect or JobStore::new when you already hold a zeph_db::DbPool.

Re-exports

pub use update_check::UpdateCheckHandler;

Modules

update_check

Structs

CustomTaskHandler

TaskHandler that injects a custom prompt into the agent loop.

JobStore

Persistent storage layer for scheduled jobs.

ScheduledTask

A task held in memory by the crate::Scheduler.

ScheduledTaskInfo

Full details for a scheduled task, returned by JobStore::list_jobs_full.

ScheduledTaskRecord

A scheduled task row returned by JobStore::list_jobs.

Scheduler

Cron-based periodic task scheduler.

TaskDescriptor

Descriptor sent over the control channel to register tasks at runtime.

Enums

SchedulerError

Errors that can occur inside the scheduler subsystem.

SchedulerMessage

Messages sent to the Scheduler over its control channel.

TaskKind

Identifies what type of work a scheduled task performs.

TaskMode

Execution mode for a scheduled task.

Traits

TaskHandler

Trait for types that can execute a scheduled task.

Functions

normalize_cron_expr

Normalise a cron expression to the 6-field format required by the cron crate.

sanitize_task_prompt

Sanitise a user-supplied task prompt before injecting it into the agent loop.