Documentation
¶
Overview ¶
Package cron implements scheduled task management for vibecoding. Cron jobs are persisted in sessions.db and executed by spawning agents.
Index ¶
- Variables
- func NormalizeJobSchedule(job *CronJob) error
- func ParseSchedule(schedule string, from time.Time) (next time.Time, isOneShot bool, err error)
- type CronJob
- type CronStore
- type CronTool
- func (t *CronTool) Description() string
- func (t *CronTool) Execute(ctx context.Context, params map[string]any) (tools.ToolResult, error)
- func (t *CronTool) Name() string
- func (t *CronTool) Parameters() json.RawMessage
- func (t *CronTool) PromptGuidelines() []string
- func (t *CronTool) PromptSnippet() string
- type JobCompletionObserver
- type JobHandler
- type SQLiteCronStore
- func (s *SQLiteCronStore) ClaimDue(id string, now time.Time) (bool, error)
- func (s *SQLiteCronStore) Create(job CronJob) (*CronJob, error)
- func (s *SQLiteCronStore) Delete(id string) error
- func (s *SQLiteCronStore) Get(id string) (*CronJob, error)
- func (s *SQLiteCronStore) List() ([]CronJob, error)
- func (s *SQLiteCronStore) Update(job CronJob) error
- type Scheduler
- func NewScheduler(store CronStore, manager *agent.AgentManager, interval time.Duration) *Scheduler
- func NewSchedulerWithSessionDir(store CronStore, manager *agent.AgentManager, interval time.Duration, ...) *Scheduler
- func NewSchedulerWithSessionDirAndHandler(store CronStore, manager *agent.AgentManager, interval time.Duration, ...) *Scheduler
- func (s *Scheduler) IsRunning() bool
- func (s *Scheduler) RunNow(id string) error
- func (s *Scheduler) SetCompletionObserver(observer func(sessionID, response string, runErr error))
- func (s *Scheduler) SetJobCompletionObserver(observer JobCompletionObserver)
- func (s *Scheduler) SetMaintenancePolicy(policy agentruntime.MaintenancePolicy)
- func (s *Scheduler) Start()
- func (s *Scheduler) Stop()
Constants ¶
This section is empty.
Variables ¶
var ErrJobAlreadyRunning = fmt.Errorf("cron job is already running")
ErrJobAlreadyRunning is returned by RunNow when the stored job still holds a fresh running claim.
Functions ¶
func NormalizeJobSchedule ¶
NormalizeJobSchedule validates a job's mode and schedule and computes its NextRun. It is the canonical normalization for management surfaces that create or update jobs: an empty mode defaults to yolo, only agent/yolo are accepted, and an empty (or @once) schedule marks the job one-shot with no next run.
func ParseSchedule ¶
ParseSchedule parses a human-readable schedule string into a next-run time. Supported formats:
"" → one-shot (no next run) "@once" → one-shot (same as empty) "@every 30m" → every 30 minutes "@every 2h" → every 2 hours "@every 1d" → every 1 day "@hourly" → every 1 hour "@daily" → every 24 hours (midnight) "@weekly" → every 7 days "@monthly" → 1st of next month
Types ¶
type CronJob ¶
type CronJob struct {
ID string `json:"id"`
SessionID string `json:"session_id,omitempty"`
Name string `json:"name"` // Short description
Prompt string `json:"prompt"` // Task prompt for sub-agent
Schedule string `json:"schedule"` // Schedule: @daily, @every 30m, 5-field cron, or empty for one-shot
OneShot bool `json:"oneshot,omitempty"` // If true, auto-disable after first run
Mode string `json:"mode"` // "agent" or "yolo"
WorkDir string `json:"work_dir,omitempty"`
A2ATarget string `json:"a2a_target,omitempty"` // A2A server URL (if set, send task via A2A protocol)
A2AToken string `json:"a2a_token,omitempty"` // Bearer token for A2A server
Enabled bool `json:"enabled"`
CreatedAt time.Time `json:"created_at"`
LastRun time.Time `json:"last_run,omitempty"`
NextRun time.Time `json:"next_run,omitempty"`
RunCount int `json:"run_count"`
LastStatus string `json:"last_status,omitempty"` // "success", "failed", "running"
LastError string `json:"last_error,omitempty"`
}
CronJob represents a scheduled task.
func UserVisibleJobs ¶
UserVisibleJobs removes Runtime-owned maintenance jobs from a job list headed for a user-facing surface (the cron tool, the serve API, and ACP management). Those jobs are host storage housekeeping: they are scheduled, claimed, and completed through the same lifecycle as any other job, but they are not automation tasks the user authored, their prompt is not a prompt, and a front- end that rendered them would offer edit/delete controls for something the user cannot meaningfully evaluate. Filtering the projection keeps the scheduler's authoritative store untouched.
type CronStore ¶
type CronStore interface {
List() ([]CronJob, error)
Get(id string) (*CronJob, error)
Create(job CronJob) (*CronJob, error)
Update(job CronJob) error
Delete(id string) error
}
CronStore is the interface for cron job persistence.
func NewSessionScopedStore ¶
type CronTool ¶
type CronTool struct {
// contains filtered or unexported fields
}
CronTool provides cron job management for the agent.
func NewCronTool ¶
NewCronTool creates a new cron management tool.
func (*CronTool) Description ¶
func (*CronTool) Parameters ¶
func (t *CronTool) Parameters() json.RawMessage
func (*CronTool) PromptGuidelines ¶
func (*CronTool) PromptSnippet ¶
type JobCompletionObserver ¶
JobCompletionObserver receives the completed job itself so management surfaces can project job identity (ID/name) alongside the run outcome. It complements the session-scoped completion observer and fires for every local job run, including jobs without a bound session.
type JobHandler ¶
JobHandler may claim execution for a persisted job before the Scheduler falls back to its ordinary local-agent/A2A behavior. It lets Runtime-owned maintenance work reuse cron's claim, recovery, status, and completion lifecycle without creating an adapter-specific timer or scheduler.
Returning handled=false delegates to the built-in Cron Agent execution. A handled job receives the same final store update and observers as any normal cron job.
type SQLiteCronStore ¶
type SQLiteCronStore struct {
// contains filtered or unexported fields
}
SQLiteCronStore persists cron jobs in the shared sessions.db database. Query construction lives in dao.CronDAO; this type only maps persistence records to the cron domain model.
func NewSQLiteCronStore ¶
func NewSQLiteCronStore(sessionDir string) *SQLiteCronStore
NewSQLiteCronStore creates a SQLite-backed cron store rooted at sessionDir.
func (*SQLiteCronStore) ClaimDue ¶
ClaimDue atomically marks a due job as running. Only the caller that updates a row may execute it, preventing duplicate runs across scheduler instances.
func (*SQLiteCronStore) Create ¶
func (s *SQLiteCronStore) Create(job CronJob) (*CronJob, error)
Create adds a new cron job.
func (*SQLiteCronStore) Delete ¶
func (s *SQLiteCronStore) Delete(id string) error
Delete removes a cron job.
func (*SQLiteCronStore) Get ¶
func (s *SQLiteCronStore) Get(id string) (*CronJob, error)
Get returns a cron job by ID.
func (*SQLiteCronStore) List ¶
func (s *SQLiteCronStore) List() ([]CronJob, error)
List returns all cron jobs.
func (*SQLiteCronStore) Update ¶
func (s *SQLiteCronStore) Update(job CronJob) error
Update updates an existing cron job.
type Scheduler ¶
type Scheduler struct {
// contains filtered or unexported fields
}
Scheduler checks for due cron jobs and executes them via sub-agents.
func NewScheduler ¶
NewScheduler creates a new cron scheduler.
func NewSchedulerWithSessionDir ¶
func NewSchedulerWithSessionDir(store CronStore, manager *agent.AgentManager, interval time.Duration, sessionDir string) *Scheduler
NewSchedulerWithSessionDir creates a scheduler that can attach scheduled local runs to existing sessions by session ID.
func NewSchedulerWithSessionDirAndHandler ¶
func NewSchedulerWithSessionDirAndHandler(store CronStore, manager *agent.AgentManager, interval time.Duration, sessionDir string, handler JobHandler) *Scheduler
NewSchedulerWithSessionDirAndHandler creates a scheduler with an optional Runtime-owned job handler. Existing callers should use NewSchedulerWithSessionDir unless they have a durable non-Agent job that must share the canonical Cron lifecycle.
func (*Scheduler) RunNow ¶
RunNow triggers one immediate manual execution of a stored job without waiting for the next scheduler tick. It reuses the claim path so last_run / running stamping and cross-process coordination stay identical to scheduled runs, and executes asynchronously; completion surfaces through the installed completion observers. Stopping the scheduler cancels a manual run that has not finished yet.
func (*Scheduler) SetCompletionObserver ¶
SetCompletionObserver installs a callback for completed local cron runs. The callback is invoked after the job has produced its final response.
func (*Scheduler) SetJobCompletionObserver ¶
func (s *Scheduler) SetJobCompletionObserver(observer JobCompletionObserver)
SetJobCompletionObserver installs a job-scoped completion callback.
func (*Scheduler) SetMaintenancePolicy ¶
func (s *Scheduler) SetMaintenancePolicy(policy agentruntime.MaintenancePolicy)
SetMaintenancePolicy installs the resolved Runtime maintenance policy this scheduler projects and executes. Callers that never set one keep the defaults, so maintenance stays available to every entry point without each of them having to opt in.
Source Files