watch

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Jul 5, 2026 License: MIT Imports: 11 Imported by: 0

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

View Source
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

type Counts struct {
	Iterations   int
	ToolCalls    int
	Responses    int
	Errors       int
	LargeResults int
}

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

func Discover(sessionsRoot string) ([]*Tailer, error)

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

func NewTailer(dir string) *Tailer

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) Dir

func (t *Tailer) Dir() string

Dir returns the watched directory.

func (*Tailer) Refresh

func (t *Tailer) Refresh() (State, error)

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

func (t *Tailer) SessionID() string

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

func (t *Tailer) SetEventCap(n int)

SetEventCap overrides the retention limit. 0 disables capping (use with caution on long-running sessions).

func (*Tailer) State

func (t *Tailer) State() State

State returns the current snapshot. Callers should not mutate the returned struct; treat it as a value.

Jump to

Keyboard shortcuts

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