queue

Documentation

Index

• type AttentionReason
  • func (r AttentionReason) String() string
• type DiffSummary
• type Priority
  • func DeterminePriority(reason AttentionReason, detectedStatus detection.DetectedStatus, ...) Priority
  • func ReasonToPriority(reason AttentionReason) Priority
  • func (p Priority) Emoji() string
  • func (p Priority) IsHigherThan(other Priority) bool
  • func (p Priority) IsLowerThan(other Priority) bool
  • func (p Priority) IsValid() bool
  • func (p Priority) String() string
• type RetryAttempt
• type RetryHistory
• type ReviewItem
• type ReviewQueue
  • func NewReviewQueue() *ReviewQueue
  • func (rq *ReviewQueue) Add(item *ReviewItem) bool
  • func (rq *ReviewQueue) Clear()
  • func (rq *ReviewQueue) Count() int
  • func (rq *ReviewQueue) CountByPriority() map[Priority]int
  • func (rq *ReviewQueue) CountByReason() map[AttentionReason]int
  • func (rq *ReviewQueue) Get(sessionID string) (*ReviewItem, bool)
  • func (rq *ReviewQueue) GetStatistics() ReviewQueueStatistics
  • func (rq *ReviewQueue) Has(sessionID string) bool
  • func (rq *ReviewQueue) List() []*ReviewItem
  • func (rq *ReviewQueue) Next(currentSessionID string) (string, bool)
  • func (rq *ReviewQueue) Previous(currentSessionID string) (string, bool)
  • func (rq *ReviewQueue) Remove(sessionID string) bool
  • func (rq *ReviewQueue) Subscribe(observer ReviewQueueObserver)
  • func (rq *ReviewQueue) Unsubscribe(observer ReviewQueueObserver)
• type ReviewQueueObserver
• type ReviewQueueStatistics
• type Score
• type TestResults

Types

type AttentionReason

type AttentionReason string

AttentionReason describes why a session needs user attention.

const (
	ReasonApprovalPending    AttentionReason = "approval_pending"    // Waiting for approval dialog response
	ReasonInputRequired      AttentionReason = "input_required"      // Waiting for user input
	ReasonErrorState         AttentionReason = "error_state"         // Error occurred
	ReasonTestsFailing       AttentionReason = "tests_failing"       // Tests are failing
	ReasonIdleTimeout        AttentionReason = "idle_timeout"        // DEPRECATED: No activity for extended period (use ReasonIdle or ReasonStale)
	ReasonTaskComplete       AttentionReason = "task_complete"       // Task completed, waiting for next instruction
	ReasonUncommittedChanges AttentionReason = "uncommitted_changes" // Uncommitted git changes ready to commit
	ReasonIdle               AttentionReason = "idle"                // Session idle, ready for next task (short idle, expected)
	ReasonStale              AttentionReason = "stale"               // No output for extended period (may be stuck)
	ReasonWaitingForUser     AttentionReason = "waiting_for_user"    // Explicitly waiting for user input (detected prompt)
)

func (AttentionReason) String

func (r AttentionReason) String() string

String returns a human-readable description of the attention reason.

type DiffSummary

type DiffSummary struct {
	FilesChanged int32
	ChangedFiles []string
	LinesAdded   int32
	LinesDeleted int32
	Excerpt      string // Capped at 1000 chars
}

DiffSummary summarises the git diff at the time of the sweep.

type Priority

type Priority int

Priority defines the urgency level of a review item.

const (
	PriorityUrgent Priority = 1 // Blocking errors
	PriorityHigh   Priority = 2 // Approval dialogs
	PriorityMedium Priority = 3 // Input requests
	PriorityLow    Priority = 4 // Idle/complete
)

func DeterminePriority

func DeterminePriority(reason AttentionReason, detectedStatus detection.DetectedStatus, age time.Duration) Priority

DeterminePriority calculates the priority for a review item based on multiple factors.

func ReasonToPriority

func ReasonToPriority(reason AttentionReason) Priority

ReasonToPriority maps attention reasons to base priority levels.

func (Priority) Emoji

func (p Priority) Emoji() string

Emoji returns an emoji representation of the priority level.

func (Priority) IsHigherThan

func (p Priority) IsHigherThan(other Priority) bool

IsHigherThan returns true if p is higher priority than other. Note: LOWER numeric value = HIGHER priority (Urgent=1, Low=4).

func (Priority) IsLowerThan

func (p Priority) IsLowerThan(other Priority) bool

IsLowerThan returns true if p is lower priority than other. Note: HIGHER numeric value = LOWER priority (Urgent=1, Low=4).

func (Priority) IsValid

func (p Priority) IsValid() bool

IsValid returns true if p is a defined priority level.

func (Priority) String

func (p Priority) String() string

String returns a human-readable description of the priority level.

type RetryAttempt

type RetryAttempt struct {
	Number        int32
	FailureReason string // Capped at 500 chars
	TimestampMs   int64
}

RetryAttempt captures one correction iteration.

type RetryHistory

type RetryHistory struct {
	AttemptCount int32
	MaxRetries   int32
	Attempts     []RetryAttempt
}

RetryHistory tracks each correction loop attempt.

type ReviewItem

type ReviewItem struct {
	SessionID   string            `json:"session_id"`
	SessionName string            `json:"session_name"`
	Reason      AttentionReason   `json:"reason"`
	Priority    Priority          `json:"priority"`
	DetectedAt  time.Time         `json:"detected_at"`
	Context     string            `json:"context"`            // Snippet of relevant output
	PatternName string            `json:"pattern_name"`       // Pattern that matched
	Metadata    map[string]string `json:"metadata,omitempty"` // Additional metadata

	// Session details for rich display (matching Instance fields)
	Program      string         `json:"program"`       // Program running (claude, aider, etc.)
	Branch       string         `json:"branch"`        // Git branch name
	Path         string         `json:"path"`          // Repository path
	WorkingDir   string         `json:"working_dir"`   // Working directory
	Status       string         `json:"status"`        // Current session status (string form of session.Status)
	Tags         []string       `json:"tags"`          // Session tags
	Category     string         `json:"category"`      // Session category
	DiffStats    *git.DiffStats `json:"diff_stats"`    // Git diff statistics (nullable)
	LastActivity time.Time      `json:"last_activity"` // Last meaningful output time (used for sorting and display)

	// IdleState is the active-work state at the time this item was last evaluated.
	// Used as a fallback for WorkingState when ClaudeStatus is Unknown.
	IdleState detection.IdleState `json:"idle_state,omitempty"`

	// ClaudeStatus is the raw DetectedStatus from the detection pipeline at the time
	// this item was last evaluated. It distinguishes Active from Processing, enabling
	// the WORKING_STATE_PROCESSING proto value that IdleState alone cannot produce.
	//
	// WARNING: DetectedStatus is serialized as an integer (iota). New values MUST be
	// appended to the end of the iota block in detection/status.go — inserting values
	// mid-iota will silently corrupt persisted queue entries read by older server versions.
	ClaudeStatus detection.DetectedStatus `json:"claude_status,omitempty"`

	// Score is set by the Fixer after a successful Sweep quality gate.
	// Nil if the Sweep has not yet completed or was not triggered.
	Score *Score `json:"score,omitempty"`
}

ReviewItem represents a session that needs user attention.

type ReviewQueue

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

ReviewQueue manages sessions that need user attention.

func NewReviewQueue

func NewReviewQueue() *ReviewQueue

NewReviewQueue creates a new review queue.

func (*ReviewQueue) Add

func (rq *ReviewQueue) Add(item *ReviewItem) bool

Add adds a session to the review queue or updates it if already present. Returns true if this is a new item, false if it was updated.

func (*ReviewQueue) Clear

func (rq *ReviewQueue) Clear()

Clear removes all items from the queue.

func (*ReviewQueue) Count

func (rq *ReviewQueue) Count() int

Count returns the number of items in the queue.

func (*ReviewQueue) CountByPriority

func (rq *ReviewQueue) CountByPriority() map[Priority]int

CountByPriority returns the count of items for each priority level.

func (*ReviewQueue) CountByReason

func (rq *ReviewQueue) CountByReason() map[AttentionReason]int

CountByReason returns the count of items for each attention reason.

func (*ReviewQueue) Get

func (rq *ReviewQueue) Get(sessionID string) (*ReviewItem, bool)

Get retrieves a review item by session ID.

func (*ReviewQueue) GetStatistics

func (rq *ReviewQueue) GetStatistics() ReviewQueueStatistics

GetStatistics returns summary statistics about the review queue.

func (*ReviewQueue) Has

func (rq *ReviewQueue) Has(sessionID string) bool

Has checks if a session is in the review queue.

func (*ReviewQueue) List

func (rq *ReviewQueue) List() []*ReviewItem

List returns all items sorted by priority (most urgent first).

func (*ReviewQueue) Next

func (rq *ReviewQueue) Next(currentSessionID string) (string, bool)

Next returns the session ID of the next review item after the given session ID. If currentSessionID is empty or not found, returns the highest priority item. Returns empty string and false if the queue is empty.

func (*ReviewQueue) Previous

func (rq *ReviewQueue) Previous(currentSessionID string) (string, bool)

Previous returns the session ID of the previous review item before the given session ID. If currentSessionID is empty or not found, returns the highest priority item. Returns empty string and false if the queue is empty.

func (*ReviewQueue) Remove

func (rq *ReviewQueue) Remove(sessionID string) bool

Remove removes a session from the review queue. Returns true if the item was present and removed.

func (*ReviewQueue) Subscribe

func (rq *ReviewQueue) Subscribe(observer ReviewQueueObserver)

Subscribe adds an observer to receive queue update notifications.

func (*ReviewQueue) Unsubscribe

func (rq *ReviewQueue) Unsubscribe(observer ReviewQueueObserver)

Unsubscribe removes an observer from receiving notifications.

type ReviewQueueObserver

type ReviewQueueObserver interface {
	OnItemAdded(item *ReviewItem)
	OnItemRemoved(sessionID string)
	OnQueueUpdated(items []*ReviewItem)
}

ReviewQueueObserver is notified when the review queue changes.

type ReviewQueueStatistics

type ReviewQueueStatistics struct {
	TotalItems int
	ByPriority map[Priority]int
	ByReason   map[AttentionReason]int
	AverageAge time.Duration
	OldestAge  time.Duration
	OldestItem string
}

ReviewQueueStatistics provides summary information about the queue.

type Score

type Score struct {
	TestResults  *TestResults
	DiffSummary  *DiffSummary
	RetryHistory *RetryHistory
}

Score contains the assembled quality gate results for a passing Sweep. Populated by the Fixer after a successful Lookout run.

type TestResults

type TestResults struct {
	Passed           bool
	OutputExcerpt    string // Capped at 2000 chars
	DurationMs       int64
	TestsRun         int32
	TestsFailed      int32
	FailingTestNames []string
}

TestResults holds a Sweep's test run outcome.