monitor

package
v0.0.0-...-9b65b54 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Poll loop pattern (interval, stopCh, RunOnce) is reused by the global daemon for its watchdog and scheduling cycle (Phase 2B).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FingerprintError 

func FingerprintError(errMsg string) uint64

FingerprintError computes an FNV-1a hash for an error message.

func FingerprintToolCall 

func FingerprintToolCall(name, input string) uint64

FingerprintToolCall computes an FNV-1a hash fingerprint for a tool call.

func SustainedStallCheck 

func SustainedStallCheck(history []StallRecord, monitorThreshold, resetThreshold float64, now time.Time) (monitor bool, reset bool)

SustainedStallCheck determines whether the composite stall score has exceeded a threshold for a sustained duration. Returns true for monitor level (2min sustained) or reset level (5min sustained).

monitorThreshold and resetThreshold come from PhaseThresholds. history should be ordered oldest-first.

Types

type AgentActivity 

type AgentActivity struct {
	RecentToolCalls []ToolCall   // last 10 tool calls
	FileActivity    FileActivity // file modification data
	Errors          []ErrorEntry // recent error entries
	ReadWrite       ReadWriteStats
	HasEdits        bool       // agent has made file edits
	RunningTests    bool       // agent is executing test commands
	CompactedAt     *time.Time // last compaction event time
}

AgentActivity aggregates all signals needed for stall scoring.

type CycleStats 

type CycleStats struct {
	Checked        int
	Completed      int
	Failed         int
	Retried        int
	StuckWarned    int
	StuckKilled    int
	WaitersResumed int
	TimedOut       int
	Validated      int
	AutoSpawned    int
	Duration       time.Duration
	Errors         []error // phase errors accumulated during the cycle
}

CycleStats captures metrics from one monitor cycle.

func (*CycleStats) HasErrors 

func (s *CycleStats) HasErrors() bool

HasErrors returns true if any errors occurred during the cycle.

type ErrorEntry 

type ErrorEntry struct {
	Hash uint64
}

ErrorEntry represents a parsed error with its hash.

type FileActivity 

type FileActivity struct {
	RecentModifications int // file modifications in last 5min
	PriorModifications  int // file modifications in 5-10min ago window
	UniqueFilesTouched  int // distinct files modified so far
	ExpectedFiles       int // files from task spec
}

FileActivity records file modification counts across time windows.

type FileWatcher 

type FileWatcher struct {
	DB  *db.DB
	Log func(string)
	// contains filtered or unexported fields
}

FileWatcher monitors agent worktrees for file ownership violations in real-time.

func NewFileWatcher 

func NewFileWatcher(database *db.DB, logFn func(string)) *FileWatcher

NewFileWatcher creates a new FileWatcher. Call Start to begin watching.

func (*FileWatcher) AddWorktree 

func (fw *FileWatcher) AddWorktree(ctx context.Context, taskID, worktreePath string)

AddWorktree registers a task's worktree for file ownership monitoring.

func (*FileWatcher) RemoveWorktree 

func (fw *FileWatcher) RemoveWorktree(taskID string)

RemoveWorktree stops monitoring a task's worktree.

func (*FileWatcher) Start 

func (fw *FileWatcher) Start(ctx context.Context) error

Start begins the file watching goroutine.

func (*FileWatcher) Stop 

func (fw *FileWatcher) Stop()

Stop terminates the file watching goroutine.

func (*FileWatcher) WatchedTaskCount 

func (fw *FileWatcher) WatchedTaskCount() int

WatchedTaskCount returns the number of tasks currently being watched.

type GoroutineMetrics 

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

GoroutineMetrics tracks goroutine counts over time to detect leaks. Thread-safe for concurrent use.

func NewGoroutineMetrics 

func NewGoroutineMetrics() *GoroutineMetrics

NewGoroutineMetrics creates a new tracker, recording the current goroutine count as the baseline.

func (*GoroutineMetrics) Baseline 

func (gm *GoroutineMetrics) Baseline() int

Baseline returns the initial goroutine count.

func (*GoroutineMetrics) Current 

func (gm *GoroutineMetrics) Current() int

Current returns the current goroutine count.

func (*GoroutineMetrics) DeltaFromBaseline 

func (gm *GoroutineMetrics) DeltaFromBaseline() int

DeltaFromBaseline returns the difference between current and baseline.

func (*GoroutineMetrics) DetectLeaks 

func (gm *GoroutineMetrics) DetectLeaks(threshold int) []string

DetectLeaks returns warnings if the goroutine count exceeds baseline by more than threshold. Call after all work should be complete.

func (*GoroutineMetrics) Peak 

func (gm *GoroutineMetrics) Peak() int

Peak returns the highest goroutine count observed.

func (*GoroutineMetrics) Report 

func (gm *GoroutineMetrics) Report() string

Report generates a human-readable goroutine metrics summary.

func (*GoroutineMetrics) Reset 

func (gm *GoroutineMetrics) Reset()

Reset clears all snapshots and re-establishes the baseline.

func (*GoroutineMetrics) Snapshot 

func (gm *GoroutineMetrics) Snapshot() GoroutineSnapshot

Snapshot records the current goroutine count.

func (*GoroutineMetrics) SnapshotCount 

func (gm *GoroutineMetrics) SnapshotCount() int

SnapshotCount returns the number of snapshots recorded.

type GoroutineSnapshot 

type GoroutineSnapshot struct {
	Timestamp time.Time
	Count     int
	Delta     int // change since last snapshot
}

GoroutineSnapshot records the goroutine count at a point in time.

type HealFunc 

type HealFunc func(ctx context.Context, sessionID, taskID, errorType string) (bool, error)

HealFunc attempts to auto-fix a build failure for a task. Parameters: ctx, sessionID, taskID, errorType. Returns true if the fix was applied successfully, false otherwise.

type MergeFunc 

type MergeFunc func(ctx context.Context, testCmd string, review bool) error

MergeFunc is a callback for Go-native merge (avoids circular import with orchestrator). Parameters: ctx, testCmd, review. Returns error.

type MergeFuncWithSkip 

type MergeFuncWithSkip func(ctx context.Context, testCmd string, review bool, skipBranches []string) error

MergeFuncWithSkip is like MergeFunc but accepts branches to skip test gate (B-145 recovery).

type Monitor 

type Monitor struct {
	DB                *db.DB
	Spawner           *agent.Spawner
	MergeFunc         MergeFunc         // optional: when set, uses Go merge in phase3 instead of bash
	MergeFuncWithSkip MergeFuncWithSkip // optional: merge with skip-branches for crash recovery (B-145)
	StagingMergeFunc  StagingMergeFunc  // optional: staging-to-dev merge for crash recovery (B-145)
	PRCreateFunc      PRCreateFunc      // optional: creates GitHub PR from staging branch (B-273)
	ReDecomposeFunc   ReDecomposeFunc   // optional: when set, splits context-exhausted tasks into subtasks
	HealFunc          HealFunc          // optional: when set, attempts auto-fix on build failures before retry
	QualityCheckFunc  QualityCheckFunc  // optional: when set, runs quality gates before merge (Phase 5)
	TaskGateFunc      TaskGateFunc      // optional: when set, runs build+test gate before marking task done
	RepoRoot          string
	LogsDir           string
	PidsDir           string
	Interval          time.Duration
	Log               func(string) // logging callback
	// contains filtered or unexported fields
}

Monitor manages the agent lifecycle with a background polling loop.

func (*Monitor) RunOnce 

func (m *Monitor) RunOnce(ctx context.Context) (*CycleStats, error)

RunOnce executes a single monitor cycle (useful for testing and debug).

func (*Monitor) Running 

func (m *Monitor) Running() bool

Running returns whether the monitor loop is active.

func (*Monitor) Start 

func (m *Monitor) Start(ctx context.Context) error

Start begins the background monitor loop in a goroutine.

func (*Monitor) Stop 

func (m *Monitor) Stop() error

Stop gracefully stops the monitor loop.

type PRCreateFunc 

type PRCreateFunc func(ctx context.Context) (*PRCreateResult, error)

PRCreateFunc creates a GitHub PR from the staging branch (B-273).

type PRCreateResult 

type PRCreateResult struct {
	PRURL    string
	PRNumber int
	Branch   string
	Base     string
}

PRCreateResult is the monitor-side result of creating a staging PR.

type Phase 

type Phase string

Phase represents the detected activity phase of an agent. 

const (
	PhaseExploration    Phase = "exploration"
	PhaseImplementation Phase = "implementation"
	PhaseTesting        Phase = "testing"
)

func DetectPhase 

func DetectPhase(activity AgentActivity) Phase

DetectPhase returns the current activity phase based on agent behavior.

type QualityCheckFunc 

type QualityCheckFunc func(ctx context.Context, projectPath, branch, sessionID string) error

QualityCheckFunc runs quality gates before merge. Returns nil for PROMOTE, non-nil error for HOLD or ROLLBACK. Wire to quality.CheckBeforeMerge.

type RabbitHoleResult 

type RabbitHoleResult struct {
	Detected  bool
	Ratio     float64
	CallCount int
}

RabbitHoleResult holds the outcome of a rabbit-hole detection check.

func DetectRabbitHole 

func DetectRabbitHole(calls []ToolCall) RabbitHoleResult

DetectRabbitHole checks whether tool call activity indicates rabbit-hole behavior. Returns detected=true when there are 20+ tool calls and the ratio of unique Write/Edit file targets to total calls is below 0.1.

type ReDecomposeFunc 

type ReDecomposeFunc func(ctx context.Context, taskID string, checkpoint string) ([]string, error)

ReDecomposeFunc is called when a context-exhausted task should be split into subtasks. Parameters: ctx, taskID, checkpoint JSON. Returns new task IDs or error.

type ReadWriteStats 

type ReadWriteStats struct {
	Reads     int
	Writes    int
	HasEdited bool // whether the agent has made any edit at all
}

ReadWriteStats tracks read vs write tool call counts.

type StagingMergeFunc 

type StagingMergeFunc func(ctx context.Context) error

StagingMergeFunc merges the staging branch into dev (B-145 recovery).

type StallRecord 

type StallRecord struct {
	Score     float64
	Timestamp time.Time
}

StallRecord is a timestamped stall score used for sustained stall checking.

type StallScore 

type StallScore struct {
	ToolRepetition  float64 // 30% weight — tool call fingerprint repetition
	ProgressDelta   float64 // 25% weight — file modification rate delta
	FileCoverage    float64 // 20% weight — unique files touched / expected files
	ErrorRepetition float64 // 15% weight — repeated error hash count
	ReadWriteDrift  float64 // 10% weight — read-heavy with no writes after first edit
	Composite       float64 // weighted combination of the 5 signals
	Timestamp       time.Time
}

StallScore holds the individual signal scores and the composite score.

func ComputeStallScore 

func ComputeStallScore(activity AgentActivity, now time.Time) StallScore

ComputeStallScore calculates the composite stall score from agent activity signals. Each signal produces a 0.0-1.0 score; the composite is the weighted sum. If a compaction event occurred within the last 2 minutes, all signals are suppressed (score=0).

type TaskGateFunc 

type TaskGateFunc func(ctx context.Context, worktreePath string, testCmd string) (bool, string, string)

TaskGateFunc runs build+test validation on an agent's worktree before merge. Returns (passed, triageOutcome, errorOutput). triageOutcome is one of "heal", "refine", or "redo". Wire to task_gate.RunGate (built by another agent).

type ThresholdPair 

type ThresholdPair struct {
	Monitor float64
	Reset   float64
}

ThresholdPair holds the monitor and reset thresholds for a phase.

func PhaseThresholds 

func PhaseThresholds(phase Phase, tierAdj float64) ThresholdPair

PhaseThresholds returns the monitor/reset threshold pair for the given phase. tierAdj applies a ±0.05 adjustment: negative for tighter (Tier 1), positive for looser (Tier 3). tierAdj should be one of -0.05, 0.0, or 0.05.

type ToolCall 

type ToolCall struct {
	Name  string
	Input string // truncated input
}

ToolCall represents a single tool invocation for fingerprint analysis.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.