Documentation
¶
Overview ¶
Package watch tails an active or completed squad session directory (.squad/sessions/<id>/) and folds the events.jsonl + meta.json contents into a single observable State. The TUI consumes State to render the sidebar, focused panel, and event tail; CLI tools can consume it for once-off rendering (squad watch --once <id>).
The tailer is stateful: it tracks the byte offset into events.jsonl and the last-known mtime of meta.json so repeated Refresh() calls cost O(new bytes), not O(file size). Event tails are capped (default 200) so memory stays bounded for long-running sessions.
Index ¶
Constants ¶
const DefaultEventCap = 200
DefaultEventCap is the upper bound on retained events in State.Events. Older entries are dropped from the front as new ones arrive.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Counts ¶
Counts tracks running totals derived from events.jsonl. Useful for the header tallies (iter, tools called, error count, etc.).
type EventLine ¶
type EventLine struct {
Ts time.Time
Type string // session.Event* constant
Summary string // one-line, width-truncatable
}
EventLine is one summarized row for the events tail panel. Summary is rendered as-is (no further parsing) by the renderer.
type State ¶
type State struct {
Meta session.Meta // last-known meta.json contents
Events []EventLine // capped recent events, oldest first
Counts Counts // running totals
LastTool string // name of the most recent tool_call
LastError string // most recent error message (from error or run_end events)
LastEventAt time.Time // ts of the most recent event
}
State is the consolidated view of a session at a point in time. The renderer is pure over a State value — no I/O during render.
type Tailer ¶
type Tailer struct {
// contains filtered or unexported fields
}
Tailer reads one session directory incrementally. Refresh() picks up any new bytes appended to events.jsonl and re-parses meta.json when its mtime changes. The tailer is safe to call from a single goroutine (typically the bubble-tea Update loop); it is not goroutine-safe.
func Discover ¶
Discover scans a sessions root (e.g. ".squad/sessions") and returns a Tailer for each direct child directory. Children without a meta.json or events.jsonl are still returned — the Tailer will yield zero state until those files appear.
Results are sorted by directory name descending, which (for the squad session ID format) puts the newest first.
func NewTailer ¶
NewTailer returns a Tailer for the given .squad/sessions/<id>/ dir. The directory does not need to exist yet — Refresh() returns the zero State until the session is created on disk.
func (*Tailer) Refresh ¶
Refresh reads any new content from disk and returns the latest State. Missing files are treated as "not yet written" — no error, zero state fields. Other I/O errors are returned.
func (*Tailer) Reset ¶
func (t *Tailer) Reset()
Reset clears all state and offsets. The next Refresh re-reads from the beginning of the session.
func (*Tailer) SessionID ¶
SessionID returns the session identifier. Prefers the value parsed from meta.json; falls back to the directory basename, which is the same value for squad's standard layout.
func (*Tailer) SetEventCap ¶
SetEventCap overrides the retention limit. 0 disables capping (use with caution on long-running sessions).