Scheduler Tools Plugin

The Scheduler Tools plugin lets the agent (or you, through it) create, inspect, and manage scheduled agent runs — one-off (run_at) or recurring (cron). Each run fires as a fresh conversation seeded with the stored prompt; there is no context carry-over between runs.

Configuration

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

Parameter	Type	Default	Description
`enabled`	bool	`true`	Enable or disable the plugin.
`allow_cron`	bool	`true`	Allow recurring (cron) schedules. When `false`, only one-off `run_at` runs are permitted.
`default_timezone`	string	`"UTC"`	IANA timezone for interpreting cron expressions.
`run_history_retention_days`	int	`365`	How long to keep finished run history — and the per-run conversations, which are soft-deleted first — before a maintenance sweep purges them. `0` or negative keeps history forever.
`retention_sweep_interval_seconds`	float	`86400`	How often the maintenance sweep runs (retention purge plus stale-run cleanup). A restart also sweeps immediately.
`stale_run_threshold_seconds`	float	`3600`	A run that has been `running` with no progress longer than this is treated as stuck and marked failed.
`target_agents`	string	`"main"`	Which agents get the scheduler tools: `"main"`, `"subagent"`, or `"all"`. Default keeps scheduling off subagents (their tool calls have no human reading them). A scheduled run itself is a main agent, so it can still manage schedules.

Tools

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 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

You can only see and modify your own schedules.
A card in the conversation shows when a scheduled run starts and finishes.
Per-schedule timeout_seconds overrides the job queue's default timeout.
For multi-worker, knowledge-base-coordinated long-running intents built on top of the scheduler, see the Goals plugin.