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 ¶
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 ¶
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 ¶
MarshalJSON implements json.Marshaler.
func (*Item) UnmarshalJSON ¶
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 ¶
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 ¶
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 ¶
List returns the armed items for conv, soonest first. An empty conv lists every conversation's, which is what an operator wants.
func (*Store) Rekey ¶ added in v0.43.0
Rekey moves every item armed for conversation from to conversation to, and returns how many it moved.
A relay whose conversation token can change — zulip-acp keys a conversation by its topic, and a topic can be renamed — calls it when the token changes. Without it, every item armed for the old token fires into a conversation that no longer exists and is dropped as gone.
The fires that run in from right now move too, so a schedule that a running scheduled turn arms after the move still gets its parent's depth. A move is not an arm: MaxPerConv is not checked, so nothing armed is lost when two conversations become one.
from == to, or an empty token, is a no-op.