scheduler

type AuditFunc func(event, scheduleID string, fields map[string]any)

type Backend interface {
	// Start launches any backend-specific goroutines (file backend: the
	// 30s ticker). For backends that delegate timing to an external
	// system (kubernetes backend: the CronJob controller), Start is a
	// no-op. Must be safe to call once per backend instance.
	Start(ctx context.Context)

	// Stop signals the backend to terminate any goroutines launched by
	// Start and waits for them to exit. Idempotent.
	Stop()

	// Reload re-reads any cached state (file backend: the parsed-cron
	// cache). For backends with no cached state (kubernetes backend:
	// each operation hits the API), Reload is a no-op.
	Reload(ctx context.Context)

	// Sync reconciles the backend's state with the declarative list
	// of schedules pulled from forge.yaml. Called once at startup
	// after Start and again on hot-reload. Existing schedules with
	// matching IDs are updated in-place; new ones are added;
	// previously-yaml-sourced schedules no longer in the list are
	// deleted (LLM-sourced schedules are left alone — they're owned
	// by the agent's chat history, not the declarative manifest).
	Sync(ctx context.Context, declared []Schedule) error

	// List returns every active schedule the backend knows about.
	List(ctx context.Context) ([]Schedule, error)

	// Get returns a single schedule by ID, or nil when absent.
	Get(ctx context.Context, id string) (*Schedule, error)

	// Set creates or updates a schedule. Schedule.Source distinguishes
	// declarative (forge.yaml) entries from LLM-set ones; backends use
	// it to enforce RBAC in the kubernetes case and labeling in both.
	Set(ctx context.Context, sched Schedule) error

	// Delete removes a schedule by ID. Returns nil when the schedule
	// did not exist (idempotent).
	Delete(ctx context.Context, id string) error

	// History returns recent run records for a schedule (or all
	// schedules when scheduleID is empty). File backend reads from
	// the SCHEDULES.md history block; kubernetes backend returns
	// empty + a logger.Warn deferring to the audit stream (which
	// already carries schedule_complete events with status +
	// duration).
	History(ctx context.Context, scheduleID string, limit int) ([]HistoryEntry, error)
}

type CronJobManifestInput struct {
	// AgentID is the operator's agent identifier, used as a label and
	// as the prefix of the CronJob's name.
	AgentID string
	// Namespace is the target K8s namespace. Empty defaults to the
	// agent pod's own namespace (resolved at runtime from the pod's
	// downward API or the in-cluster config).
	Namespace string
	// ServiceURL is the in-cluster URL CronJob curl requests target.
	// Typically `http://<agent-svc>.<ns>.svc:<port>/`.
	ServiceURL string
	// AuthSecretName is the K8s Secret holding the internal token the
	// CronJob mounts and sends as Bearer auth. Defaults to
	// `<agent-id>-internal-token` matching `forge auth secret-yaml`.
	AuthSecretName string
	// TriggerImage is the container image the CronJob runs to make
	// the curl request. Defaults to `curlimages/curl:8.10.1`.
	TriggerImage string
	// Schedule is the Forge schedule entry to materialize.
	Schedule Schedule
}

type CronSchedule struct {
	Minute bitset
	Hour   bitset
	Dom    bitset
	Month  bitset
	Dow    bitset
}

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

type HistoryEntry struct {
	Timestamp     time.Time `json:"timestamp"`
	ScheduleID    string    `json:"schedule_id"`
	Status        string    `json:"status"` // completed, error, skipped
	Duration      string    `json:"duration"`
	CorrelationID string    `json:"correlation_id"`
	Error         string    `json:"error,omitempty"`
}

type IntervalSchedule struct {
	Interval time.Duration
}

type Logger interface {
	Info(msg string, fields map[string]any)
	Warn(msg string, fields map[string]any)
	Error(msg string, fields map[string]any)
}

type ParsedSchedule interface {
	Next(after time.Time) time.Time
}

type Schedule struct {
	ID            string    `json:"id"`
	Cron          string    `json:"cron"`
	Task          string    `json:"task"`
	Skill         string    `json:"skill,omitempty"`
	Channel       string    `json:"channel,omitempty"`        // channel adapter name (e.g. "slack", "telegram")
	ChannelTarget string    `json:"channel_target,omitempty"` // destination ID (channel ID, chat ID)
	Source        string    `json:"source"`                   // "yaml" or "llm"
	Enabled       bool      `json:"enabled"`
	Created       time.Time `json:"created"`
	LastRun       time.Time `json:"last_run,omitempty"`
	LastStatus    string    `json:"last_status,omitempty"` // completed, error, running, skipped
	RunCount      int       `json:"run_count"`
}

type ScheduleStore interface {
	// List returns all schedules.
	List(ctx context.Context) ([]Schedule, error)
	// Get returns a single schedule by ID, or nil if not found.
	Get(ctx context.Context, id string) (*Schedule, error)
	// Set creates or updates a schedule.
	Set(ctx context.Context, sched Schedule) error
	// Delete removes a schedule by ID.
	Delete(ctx context.Context, id string) error
	// RecordRun records a history entry for a completed schedule execution.
	RecordRun(ctx context.Context, entry HistoryEntry) error
	// History returns recent history entries, optionally filtered by schedule ID.
	History(ctx context.Context, scheduleID string, limit int) ([]HistoryEntry, error)
}

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

type TaskDispatcher func(ctx context.Context, sched Schedule) error