cron

Documentation

Overview

Package cron provides a recurring task scheduler whose task definitions and execution history are persisted in a GORM-backed database. Instead of relying on an in-memory runner such as robfig/cron/v3, it polls the database for due tasks and uses adhocore/gronx for cron expression parsing and next-run calculation. Users define cron jobs through configuration files or dynamically via the create_recurring_task LLM tool. Every execution is recorded in the cron_history table for audit purposes, giving Genie a mechanism for scheduling and auditing recurring automated tasks.

Package cron re-exports model types from pkg/db for convenience. The actual GORM models live in pkg/db to avoid import cycles (pkg/cron → pkg/agui → pkg/db).

Index

• Constants
• func NewCreateRecurringTaskTool(store ICronStore) tool.Tool
• type Config
  • func (cfg Config) NewScheduler(store ICronStore, dispatcher EventDispatcher) *Scheduler
• type CreateTaskRequest
• type CronEntry
• type CronHistory
• type CronTask
• type DeleteTaskRequest
• type EventDispatcher
• type ICronStore
• type IScheduler
• type ListTasksRequest
• type RecentFailuresRequest
• type RecordRunRequest
• type Scheduler
  • func (s *Scheduler) HealthCheck(ctx context.Context) []agui.HealthResult
  • func (s *Scheduler) Start(ctx context.Context) error
  • func (s *Scheduler) Stop() error
• type Store
  • func NewStore(db *gorm.DB) *Store
  • func (s *Store) CleanupHistory(ctx context.Context, olderThan time.Duration) (int64, error)
  • func (s *Store) CreateTask(ctx context.Context, req CreateTaskRequest) (*CronTask, error)
  • func (s *Store) DeleteTask(ctx context.Context, req DeleteTaskRequest) error
  • func (s *Store) DueTasks(ctx context.Context, now time.Time) ([]CronTask, error)
  • func (s *Store) ListTasks(ctx context.Context, req ListTasksRequest) ([]CronTask, error)
  • func (s *Store) MarkTriggered(ctx context.Context, taskID uuid.UUID, triggeredAt time.Time) error
  • func (s *Store) RecentFailures(ctx context.Context, req RecentFailuresRequest) ([]CronHistory, error)
  • func (s *Store) RecordRun(ctx context.Context, req RecordRunRequest) (*CronHistory, error)
  • func (s *Store) SetNextRun(ctx context.Context, taskID uuid.UUID, nextRun time.Time) error
  • func (s *Store) UpdateRun(ctx context.Context, req UpdateRunRequest) error
• type ToolProvider
  • func NewToolProvider(store ICronStore) *ToolProvider
  • func (p *ToolProvider) GetTools() []tool.Tool
• type UpdateRunRequest

Constants

const ToolName = "create_recurring_task"

Functions

func NewCreateRecurringTaskTool

func NewCreateRecurringTaskTool(store ICronStore) tool.Tool

NewCreateRecurringTaskTool creates a tool that allows LLM agents to dynamically schedule recurring tasks. The tool validates the cron expression, persists the task to the database, computes the first NextRunAt, and the DB ticker will pick it up on the next cycle.

Types

type Config

type Config struct {
	Tasks []CronEntry `yaml:"tasks,omitempty" toml:"tasks,omitempty"`
}

Config holds the cron scheduler configuration. The Enabled flag controls whether the scheduler starts at all. Tasks lists the statically configured cron jobs; additional tasks can be created at runtime via the create_recurring_task tool.

func (Config) NewScheduler

func (cfg Config) NewScheduler(
	store ICronStore,
	dispatcher EventDispatcher,
) *Scheduler

NewScheduler creates a Scheduler with the given store, configuration, and event dispatcher. The dispatcher is called for each cron task that becomes due, routing it through the background worker pipeline.

type CreateTaskRequest

type CreateTaskRequest struct {
	Name       string
	Expression string
	Action     string
	Source     string // "config" or "tool"
}

CreateTaskRequest holds the parameters for creating a new cron task.

type CronEntry

type CronEntry struct {
	Name       string `yaml:"name,omitempty" toml:"name,omitempty"`
	Expression string `yaml:"expression,omitempty" toml:"expression,omitempty"`
	Action     string `yaml:"action,omitempty" toml:"action,omitempty"` // prompt sent to the agent, or "genie:report" for activity report
}

CronEntry represents a single cron task definition from the configuration file. Users add entries under [cron.tasks] in their .genie.toml or .genie.yaml. When Action is "genie:report", the built-in activity report runs instead of the agent: it reads recent audit log events, writes a markdown report to ~/.genie/reports/<agent_name>/<YYYYMMDD>_<name>.md, and stores the summary in vector memory for future reference.

type CronHistory

type CronHistory = db.CronHistory

CronHistory is a type alias for the GORM model defined in pkg/db.

type CronTask

type CronTask = db.CronTask

CronTask is a type alias for the GORM model defined in pkg/db.

type DeleteTaskRequest

type DeleteTaskRequest struct {
	ID uuid.UUID
}

DeleteTaskRequest identifies the cron task to delete.

type EventDispatcher

type EventDispatcher func(ctx context.Context, req agui.EventRequest) (string, error)

EventDispatcher is a function that dispatches a cron event for processing. Returns a run ID and an error. This decouples the cron scheduler from the concrete BackgroundWorker (and thus pkg/agui), avoiding import cycles.

type ICronStore

type ICronStore interface {
	// ListTasks returns all cron tasks, optionally filtered to enabled-only.
	ListTasks(ctx context.Context, req ListTasksRequest) ([]CronTask, error)
	// CreateTask persists a new cron task, upserting on name conflict.
	CreateTask(ctx context.Context, req CreateTaskRequest) (*CronTask, error)
	// DeleteTask removes a cron task by ID.
	DeleteTask(ctx context.Context, req DeleteTaskRequest) error
	// DueTasks returns all enabled tasks whose NextRunAt <= now.
	DueTasks(ctx context.Context, now time.Time) ([]CronTask, error)
	// MarkTriggered sets LastTriggeredAt for a task.
	MarkTriggered(ctx context.Context, taskID uuid.UUID, triggeredAt time.Time) error
	// SetNextRun updates the pre-computed NextRunAt for a task.
	SetNextRun(ctx context.Context, taskID uuid.UUID, nextRun time.Time) error
	// RecordRun creates a new cron_history entry for an execution.
	RecordRun(ctx context.Context, req RecordRunRequest) (*CronHistory, error)
	// UpdateRun updates a cron_history entry when execution completes.
	UpdateRun(ctx context.Context, req UpdateRunRequest) error
	// RecentFailures returns the most recent failed cron runs.
	RecentFailures(ctx context.Context, req RecentFailuresRequest) ([]CronHistory, error)
	// CleanupHistory deletes cron_history entries older than the given duration.
	CleanupHistory(ctx context.Context, olderThan time.Duration) (int64, error)
}

ICronStore defines the repository interface for cron task persistence. Implementations must be safe for concurrent use.

type IScheduler

type IScheduler interface {
	agui.BGWorker
	Stop() error
}

type ListTasksRequest

type ListTasksRequest struct {
	EnabledOnly bool
}

ListTasksRequest specifies filters for listing cron tasks.

type RecentFailuresRequest

type RecentFailuresRequest struct {
	Limit int
}

RecentFailuresRequest specifies how many recent failures to retrieve.

type RecordRunRequest

type RecordRunRequest struct {
	TaskID   uuid.UUID
	TaskName string
	Status   db.CronStatus // "running", "success", "failed"
	Error    string
	RunID    string
}

RecordRunRequest holds the parameters for recording a cron execution.

type Scheduler

type Scheduler struct {
	// contains filtered or unexported fields
}

Scheduler is a simple DB-polling ticker that checks every minute for cron tasks whose NextRunAt has passed. It dispatches due tasks via EventDispatcher, records execution history, and computes the next run time.

This approach avoids an in-memory cron scheduler: the database is the single source of truth, making it naturally restart-safe.

func (*Scheduler) HealthCheck

func (s *Scheduler) HealthCheck(ctx context.Context) []agui.HealthResult

HealthCheck queries the store for recent cron failures and returns a per-task health summary. Used by the heartbeat ticker to detect problems.

func (*Scheduler) Start

func (s *Scheduler) Start(ctx context.Context) error

Start upserts config-defined tasks, computes initial NextRunAt values, and begins the ticker loop that polls the DB every minute.

func (*Scheduler) Stop

func (s *Scheduler) Stop() error

Stop gracefully shuts down the ticker and waits for in-flight task goroutines to complete. Safe to call multiple times.

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store implements ICronStore backed by GORM. It provides CRUD operations for cron tasks and audit history.

func NewStore

func NewStore(db *gorm.DB) *Store

NewStore creates a new GORM-backed cron store. The caller is responsible for running AutoMigrate before using the store.

func (*Store) CleanupHistory

func (s *Store) CleanupHistory(ctx context.Context, olderThan time.Duration) (int64, error)

CleanupHistory deletes cron_history entries older than the given duration. Should be called periodically to prevent unbounded table growth.

func (*Store) CreateTask

func (s *Store) CreateTask(ctx context.Context, req CreateTaskRequest) (*CronTask, error)

CreateTask persists a new cron task. If a task with the same name already exists, it updates the expression, action, and source fields (upsert semantics).

func (*Store) DeleteTask

func (s *Store) DeleteTask(ctx context.Context, req DeleteTaskRequest) error

DeleteTask removes a cron task by ID. Without this method, tasks could not be cleaned up or unscheduled.

func (*Store) DueTasks

func (s *Store) DueTasks(ctx context.Context, now time.Time) ([]CronTask, error)

DueTasks returns all enabled tasks whose NextRunAt is at or before `now`. This is the core query for the DB-driven cron ticker.

func (*Store) ListTasks

func (s *Store) ListTasks(ctx context.Context, req ListTasksRequest) ([]CronTask, error)

ListTasks returns all cron tasks, optionally filtered to enabled-only. Without this method, the scheduler would have no way to discover which tasks to register on startup.

func (*Store) MarkTriggered

func (s *Store) MarkTriggered(ctx context.Context, taskID uuid.UUID, triggeredAt time.Time) error

MarkTriggered sets the LastTriggeredAt timestamp for a task.

func (*Store) RecentFailures

func (s *Store) RecentFailures(ctx context.Context, req RecentFailuresRequest) ([]CronHistory, error)

RecentFailures returns the most recent failed cron runs, ordered by started_at descending. Used by the heartbeat health check to surface cron problems. Without this method, the heartbeat would have no visibility into cron reliability.

func (*Store) RecordRun

func (s *Store) RecordRun(ctx context.Context, req RecordRunRequest) (*CronHistory, error)

RecordRun creates a new cron_history entry marking the start of an execution. Returns the history entry so callers can later update it via UpdateRun. Without this method, there would be no audit trail for cron executions.

func (*Store) SetNextRun

func (s *Store) SetNextRun(ctx context.Context, taskID uuid.UUID, nextRun time.Time) error

SetNextRun updates the pre-computed NextRunAt for a task.

func (*Store) UpdateRun

func (s *Store) UpdateRun(ctx context.Context, req UpdateRunRequest) error

UpdateRun updates a cron_history entry when execution completes, setting the finished_at timestamp, final status, and any error message. Without this method, runs would remain in "running" state forever.

type ToolProvider

type ToolProvider struct {
	// contains filtered or unexported fields
}

ToolProvider wraps an ICronStore and satisfies the tools.ToolProviders interface so the cron tool can be passed directly to tools.NewRegistry.

func NewToolProvider

func NewToolProvider(store ICronStore) *ToolProvider

NewToolProvider creates a ToolProvider for the create_recurring_task tool.

func (*ToolProvider) GetTools

func (p *ToolProvider) GetTools() []tool.Tool

GetTools returns the cron recurring task tool.

type UpdateRunRequest

type UpdateRunRequest struct {
	HistoryID uuid.UUID
	Status    db.CronStatus
	Error     string
	RunID     string
}

UpdateRunRequest holds the parameters for updating a completed cron run.