schedule

package
v0.15.0 Latest Latest
Warning

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

Go to latest
Published: Sep 8, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package schedule stores conversation-scoped scheduled prompts and fires them back into the conversation they were created in.

Why a relay needs this at all

Host-level cron (and its friendlier cousins) can already run a command at a time. What it cannot do is deliver into a CONVERSATION: a scheduled prompt here re-enters the same conv the schedule was created from, so the agent answering it has the topic's whole history, and its answer streams into that topic through the relay's ordinary path. That context is the entire reason this exists, and it is why "just shell out to cron" is the wrong layer. Host chores stay in host cron; only conversation-scoped work belongs here.

Shape

A Store owns a JSON file, a tick loop, and a Fire callback supplied by the relay. Fire is called SYNCHRONOUSLY for the whole turn the scheduled prompt starts — it must not return until that turn is over — because that is what makes the recursion depth of a schedule created *by* a scheduled turn exactly knowable (see Add).

Runaway control

A scheduled prompt whose turn schedules another is unbounded recursion that costs real money. Three independent bounds apply, and all three are on by default:

  • MaxDepth caps the length of a schedule→turn→schedule chain. An item created outside any firing turn has depth 1; one created inside a firing turn has its parent's depth plus one, and Add refuses anything above MaxDepth. Every chain therefore terminates. Attribution starts when Fire is CALLED, not when the turn it starts begins, so a relay that makes Fire queue behind a human turn will attribute that human turn's schedules to the waiting item. That over-restricts rather than under-restricts, which is the direction a safety bound should err in.
  • MaxPerConv and MaxTotal cap how many items can be armed at once, so breadth is bounded even where depth is not reached.
  • MinInterval floors a repeat, so `every` cannot become a busy loop.

None of that removes the need for a human to be able to LOOK: List is what the relay's `!schedules` command renders, and Remove is what kills one.

Index

Constants

View Source
const (
	DefaultMaxDepth    = 3
	DefaultMaxPerConv  = 10
	DefaultMaxTotal    = 100
	DefaultMinInterval = time.Minute
	DefaultTick        = time.Second
	// MaxTextLen bounds one scheduled prompt. A schedule is stored
	// forever and replayed unattended; an unbounded blob is a way to
	// make every future turn expensive by accident.
	MaxTextLen = 4000
)

Defaults for Config. Every one of these is a safety bound, not a tuning knob; raise them deliberately.

Variables

View Source
var ErrGone = errors.New("schedule: conversation is gone")

ErrGone is returned by a Fire callback whose conversation no longer exists — retired with `!new`, or in a channel the relay has stopped serving. The item is removed rather than retried: a schedule for a conversation nobody can reach is pure cost.

Functions

This section is empty.

Types

type Config

type Config struct {
	// Path is the JSON file the store persists to. Required.
	Path string
	// Fire delivers one due item into its conversation. It MUST block
	// for the whole turn the prompt starts; see the package doc.
	// Returning ErrGone removes the item. Required.
	Fire func(ctx context.Context, it Item) error

	// MaxDepth, MaxPerConv, MaxTotal and MinInterval bound runaway
	// scheduling; zero means the corresponding Default above.
	MaxDepth    int
	MaxPerConv  int
	MaxTotal    int
	MinInterval time.Duration

	// Tick is how often the loop looks for due items. Zero means
	// DefaultTick. Ignored when Ticks is set.
	Tick time.Duration
	// Ticks, when non-nil, replaces the internal ticker. Tests drive
	// it by hand so no test ever waits on a wall clock.
	Ticks <-chan time.Time

	// Now is the clock. Defaults to time.Now.
	Now func() time.Time
	// Logf receives operational messages.
	Logf func(format string, args ...any)
}

Config configures a Store.

type Item

type Item struct {
	// ID is short, opaque and unique across the store. It is what a
	// human types into `!unschedule`.
	ID string `json:"id"`
	// Conv is the relay's opaque conversation token, exactly as the
	// command broker uses it. The store never parses it.
	Conv string `json:"conv"`
	// Text is the prompt injected into the conversation on fire.
	Text string `json:"text"`
	// At is when it next fires (UTC).
	At time.Time `json:"at"`
	// Every, when non-zero, re-arms the item this far after each fire.
	Every time.Duration `json:"every,omitempty"`
	// Depth is the recursion depth: 1 for an item armed by a human
	// turn, parent+1 for one armed inside a firing scheduled turn.
	Depth int `json:"depth"`
	// Fires counts completed fires, so a human can see a repeat working.
	Fires int `json:"fires,omitempty"`
	// Created is when the item was armed (UTC).
	Created time.Time `json:"created"`
}

Item is one armed schedule. It is the type both front ends speak — the relay's `!schedules` listing and the agent's list_schedules tool — so there is exactly one shape and nothing to drift.

func (Item) MarshalJSON

func (i Item) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Item) UnmarshalJSON

func (i *Item) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Store

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

Store is the persisted set of armed schedules. Safe for concurrent use.

func Open

func Open(cfg Config) (*Store, error)

Open loads the store at cfg.Path, creating an empty one when the file does not exist. A corrupt file is an error, not a silent reset: an operator must see that armed work was lost.

func (*Store) Add

func (s *Store) Add(conv, text string, at time.Time, every time.Duration) (Item, error)

Add arms a new schedule for conv.

depth is derived, never supplied: it is one more than the depth of the scheduled turn currently firing in this conversation, or 1 when no scheduled turn is running. That is the whole recursion guard, and it works precisely because Fire blocks for the duration of the turn.

func (*Store) List

func (s *Store) List(conv string) []Item

List returns the armed items for conv, soonest first. An empty conv lists every conversation's, which is what an operator wants.

func (*Store) Remove

func (s *Store) Remove(conv, id string) error

Remove disarms an item. conv scopes the lookup: a conversation can only ever cancel its own schedules, which matters because the id is short and a caller could otherwise guess into another conversation. An empty conv removes by id regardless of owner (operator scope).

func (*Store) Run

func (s *Store) Run(ctx context.Context)

Run drives the fire loop until ctx is done. It returns once every in-flight fire has finished, so a relay can shut down cleanly.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL