Scheduler Tools Plugin

The Scheduler Tools plugin exposes the core scheduler to the agent as tools, so the agent (or the user, through it) can create, inspect, and manage scheduled agent runs — one-off (run_at) or recurring (cron). Each run fires as a fresh conversation seeded with a stored prompt.

Configuration

plugins:
  - module: codumentor.plugins.scheduler_tools
    class: SchedulerToolsPlugin
    priority: 10
    args:
      enabled: true
      allow_cron: true
      default_timezone: UTC
      run_history_retention_days: 90

Parameters

enabled (optional): Whether the plugin is active (default: true)
allow_cron (optional): Allow recurring (cron) schedules; when false, only one-off run_at runs are permitted (default: true)
default_timezone (optional): IANA timezone for interpreting cron expressions (default: "UTC")
run_history_retention_days (optional): How long to keep run history in the plugin's SQLite store (default: 90)
stale_run_threshold_seconds (optional): A running row with no progress for longer than this is treated as a zombie and failed by the startup sweep (default: 3600)

Tool Reference

Tool	Description
`schedule_agent_run`	Create a one-off (`run_at`) or recurring (`cron`) scheduled run; returns a `schedule_id`
`list_scheduled_tasks`	List the caller's schedules (optional status filter)
`get_scheduled_task`	Full detail for one schedule, including reconciled last-run state
`update_scheduled_task`	Change timing, timezone, title, or prompt
`pause_scheduled_task` / `resume_scheduled_task`	Pause or resume a schedule
`snooze_scheduled_task`	Postpone the next fire to a given time
`cancel_scheduled_task`	Permanently cancel a schedule
`list_scheduled_runs`	List prior runs of a schedule (most recent first)
`get_scheduled_run_output`	Fetch a run's prompt, final answer, and turn summary

Notes

Thin protocol: every run is a fresh conversation with the stored prompt as its first message — there is no context carry-over between runs.
Job-queue backed: runs are scheduled_agent_run jobs on the core queue; a per-schedule timeout_seconds overrides the queue's default. get_scheduled_task reconciles queue state with the run store to surface zombie ("running" but the job finished) and never-claimed ("enqueued but no worker picked it up") cases.
Ownership: users can only see and modify their own schedules.
A TUI transcript card renders run_started / run_finished events. Run history is kept in a plugin-local SQLite store (pruned per run_history_retention_days), separate from the conversation store.
For multi-worker, KB-coordinated long-running intents built on top of the scheduler, see the Goals plugin.