schedule

type Cron interface {
	Next(t time.Time) (time.Time, bool)
}

type Engine interface {
	ParseCron(expr string) (Cron, error)
	NextFire(job Job, after time.Time) (time.Time, bool)
}

type Job struct {
	ID     string    `json:"id"`
	Kind   string    `json:"kind,omitempty"`
	Cron   string    `json:"cron,omitempty"`
	FireAt time.Time `json:"fireAt,omitzero"`
	Prompt string    `json:"prompt,omitempty"`
	// Script is a workspace-relative bash script. When set, the job runs the
	// script directly instead of starting an agent turn.
	Script string `json:"script,omitempty"`
	Source string `json:"source"`
	// LastRun anchors the schedule. A new job is stamped at creation time so its
	// first fire is the next real boundary rather than immediately.
	LastRun time.Time `json:"lastRun,omitzero"`
	Fired   bool      `json:"fired,omitempty"`
	// InFlightAt marks a one-shot job claimed by Due but not yet MarkFired;
	// the zero time means unclaimed.
	InFlightAt time.Time `json:"inFlightAt,omitzero"`
	// Note is free-form context the agent can leave for its future self.
	Note string `json:"note,omitempty"`
	// Route is the delivery context captured when tool/schedule creates the job,
	// so a fire can route outbound messages (e.g. send) back to the origin inbox.
	Route      Route  `json:"route,omitzero"`
	ChannelKey string `json:"channelKey,omitempty"`
}

type Registry interface {
	List(ctx context.Context) ([]Job, error)
	// Add stores a job, assigning an ID when the given one is empty. It returns
	// the stored job.
	Add(ctx context.Context, job Job) (Job, error)
	// Remove deletes a job by ID, reporting whether it existed.
	Remove(ctx context.Context, id string) (bool, error)
	// SyncSource replaces every job with the given source, leaving other sources
	// alone. Used to reconcile config-declared jobs on startup.
	SyncSource(ctx context.Context, source string, jobs []Job) error
	// Due returns the enabled jobs whose next fire time has arrived, and stamps
	// them as run at now. Missed boundaries are skipped rather than backfilled.
	Due(ctx context.Context, now time.Time) ([]Job, error)
	// MarkFired records that a one-shot job has been handled while retaining it
	// for audit/listing.
	MarkFired(ctx context.Context, id string) error
}

type Route struct {
	DeliverySessionID string `json:"deliverySessionId,omitempty"`
	PlatformID        string `json:"platformId,omitempty"`
	UserID            string `json:"userId,omitempty"`
	AgentID           string `json:"agentId,omitempty"`
}

type Runtime interface {
	Start(context.Context, SubmitFunc) error
	Stop(context.Context) error
}

type SubmitFunc = func(ctx context.Context, event agentkit.MessageEvent) error