cron

package
v0.1.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 10, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

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

View Source 
const DeleteToolName = "delete_recurring_task"
View Source 
const HistoryToolName = "history_recurring_task"
View Source 
const ListToolName = "list_recurring_tasks"
View Source 
const ToggleToolName = "toggle_recurring_task"
View Source 
const ToolName = "create_recurring_task"
View Source 
const TriggerToolName = "trigger_recurring_task"

Variables

This section is empty.

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.

func NewDeleteRecurringTaskTool added in v0.1.7 

func NewDeleteRecurringTaskTool(store ICronStore) tool.Tool

func NewHistoryRecurringTaskTool added in v0.1.7 

func NewHistoryRecurringTaskTool(store ICronStore) tool.Tool

func NewListRecurringTasksTool added in v0.1.7 

func NewListRecurringTasksTool(store ICronStore) tool.Tool

func NewToggleRecurringTaskTool added in v0.1.7 

func NewToggleRecurringTaskTool(store ICronStore) tool.Tool

func NewTriggerRecurringTaskTool added in v0.1.7 

func NewTriggerRecurringTaskTool(store ICronStore, dispatcher EventDispatcher) tool.Tool

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)
	// GetTask returns a single cron task by ID.
	GetTask(ctx context.Context, id uuid.UUID) (*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
	// SetEnabled updates the enabled flag for a task (pause/resume).
	SetEnabled(ctx context.Context, taskID uuid.UUID, enabled bool) 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)
	// RecentRuns returns the most recent runs for a specific cron task.
	RecentRuns(ctx context.Context, req RecentRunsRequest) ([]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 RecentRunsRequest added in v0.1.7 

type RecentRunsRequest struct {
	TaskID uuid.UUID
	Limit  int
}

RecentRunsRequest specifies how many recent runs to retrieve for a specific task.

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) GetTask added in v0.1.7 

func (s *Store) GetTask(ctx context.Context, id uuid.UUID) (*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) ListTasks 

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

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) RecentRuns added in v0.1.7 

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

RecentRuns returns the most recent runs for a specific cron task, ordered by started_at descending.

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) SetEnabled added in v0.1.7 

func (s *Store) SetEnabled(ctx context.Context, taskID uuid.UUID, enabled bool) error

SetEnabled updates the enabled flag for a task.

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 tools can be passed directly to tools.NewRegistry.

func NewToolProvider 

func NewToolProvider(store ICronStore) *ToolProvider

NewToolProvider creates a ToolProvider for cron management tools.

func (*ToolProvider) GetTools 

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

GetTools returns the cron management tool suite: create, list, delete, history, toggle (pause/resume), and trigger (run-now).

func (*ToolProvider) SetDispatcher added in v0.1.7 

func (p *ToolProvider) SetDispatcher(dispatcher EventDispatcher)

SetDispatcher injects the EventDispatcher after construction. This is needed because the dispatcher is created in app.Start() after the tool registry is built. When set, the trigger_recurring_task tool becomes available.

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.

Source Files

View all Source files

Directories

Path Synopsis
Code generated by counterfeiter.
 Code generated by counterfeiter.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.