Documentation
¶
Overview ¶
Package todos is the agent's operational work tracker — a lightweight checklist the agent maintains itself so it doesn't lose its place when a request has several moving parts. It is NOT the deliberate, research-heavy `/plan` mode (that decides WHAT to do and asks the human to confirm); todos are just for NOT LOSING TRACK during execution.
The authoritative list lives in the Session's memory (the agent's scratchpad for this run). Each change is also snapshotted into the event log as a `todos_updated` event — purely for provenance/replay, never as the source of truth. Todos deliberately stay OUT of the human-authored objectives table: agent-inferred work must not masquerade as the user's durable goals. A todo only becomes durable project intent if the user explicitly promotes it to an objective.
Index ¶
- Constants
- func ActiveIndex(l List) int
- func Marker(status string) string
- type Item
- type List
- func Advance(l List) List
- func Append(l List, extra List) List
- func Current(ctx context.Context, st store.Store) (List, error)
- func FromTitles(titles []string) List
- func MarkBlockedAt(l List, idx int) List
- func MarkDoneAt(l List, idx int) List
- func MarkSkippedAt(l List, idx int) List
- func Normalize(l List) List
- func StartAt(l List, idx int) List
Constants ¶
const ( StatusPending = "pending" StatusActive = "active" StatusDone = "done" StatusBlocked = "blocked" StatusSkipped = "skipped" // intentionally not doing this item )
Status values for a todo item. They map onto the checklist legend: ✓ done · ▸ active · ○ pending · ! blocked.
const EventKind = "todos_updated"
EventKind is the canonical event kind for a todo-list snapshot. (Mirrored as events.KindTodosUpdated; kept here too so this package needn't import events.)
Variables ¶
This section is empty.
Functions ¶
func ActiveIndex ¶
ActiveIndex returns the index of the active item, or -1 if none.
Types ¶
type Item ¶
type Item struct {
Title string `json:"title"`
Detail string `json:"detail,omitempty"`
Status string `json:"status"`
Owner string `json:"owner,omitempty"`
}
Item is one unit of work the agent is tracking. Detail is per-item context (what the step actually entails) so the agent can pick the work back up later. Owner is who runs it — "main" today; "reader"/"background" once parallel fan-out (a later slice) can dispatch items to sub-agents.
type List ¶
type List []Item
List is an ordered set of todo items. Slice 1 executes them serially: at most one item is StatusActive at a time. (Parallel fan-out is a later slice, built on the explore/jobs substrate — not here.)
func Advance ¶
Advance marks the current active item done and promotes the next pending item to active. Used when the agent finishes the step it was on.
func Append ¶
Append pushes newly-discovered work onto the end of an existing list (the "push" path) without rewriting it — important for long-running sessions that accumulate many items. It keeps existing items untouched and promotes an active item if none remains.
func Current ¶
Current reads the most recent todo-list snapshot from the event log. An empty list (no error) means no todos have been recorded yet.
func FromTitles ¶
FromTitles builds a fresh list from plain titles (the `create` action), with the first item active and the rest pending.
func MarkBlockedAt ¶
MarkBlockedAt marks the item at idx (1-based) blocked; idx<=0 targets active.
func MarkDoneAt ¶
MarkDoneAt marks the item at idx (1-based) done; idx<=0 targets the active item. It then ensures something is active if work remains.
func MarkSkippedAt ¶
MarkSkippedAt marks the item at idx (1-based) skipped; idx<=0 targets active. Skipping is "intentionally not doing this", distinct from done.
func Normalize ¶
Normalize cleans a model-supplied list: it drops empty titles, defaults blank or unknown statuses to pending, collapses multiple actives down to the first, and — if nothing is active yet but work remains — promotes the first pending item to active so there is always a clear "current" step.
func StartAt ¶
StartAt makes the item at idx (1-based) the active one, demoting any current active item back to pending (a deliberate focus switch). idx<=0 starts the next pending item. Serial execution keeps exactly one item active.
func (List) AllSettled ¶
AllSettled reports whether every item has reached a terminal state (done or deliberately skipped) — i.e. there's no work left pending/active/blocked.
func (List) Payload ¶
Payload returns the event payload for persisting l (used by the runtime's session-tagged emitter so todo changes are attributed like any other event).
func (List) Render ¶
Render returns the multi-line checklist, each line prefixed with indent, e.g.
✓ 1. inspect current loader ▸ 2. add upsert path ○ 3. update tests
func (List) RenderWindow ¶
RenderWindow renders at most max item lines, centered on the active item, so a long list (a session can accumulate dozens) stays compact in the live TUI. Hidden items above/below are summarized as "…N above/below". The full list is always available via `todo show` / `memcode todos`.
Source Files