scheduler

type AgentCapConfig struct {
	// MaxConcurrent is the maximum number of concurrent instances.
	MaxConcurrent int `json:"max_concurrent"`

	// RampUpEnabled enables gradual capacity increase over time.
	RampUpEnabled bool `json:"ramp_up_enabled"`

	// RampUpInitial is the starting cap when ramp-up is enabled.
	RampUpInitial int `json:"ramp_up_initial"`

	// RampUpStep is how much to increase the cap each interval.
	RampUpStep int `json:"ramp_up_step"`

	// RampUpInterval is how often to increase the cap.
	RampUpInterval time.Duration `json:"ramp_up_interval"`

	// CooldownOnFailure reduces the cap on failure.
	CooldownOnFailure bool `json:"cooldown_on_failure"`

	// CooldownReduction is how much to reduce on failure.
	CooldownReduction int `json:"cooldown_reduction"`

	// CooldownRecovery is how long before restoring cap after cooldown.
	CooldownRecovery time.Duration `json:"cooldown_recovery"`
}

type AgentCapStats struct {
	Running    int  `json:"running"`     // Currently running instances
	CurrentCap int  `json:"current_cap"` // Current effective cap
	MaxCap     int  `json:"max_cap"`     // Configured max cap
	Waiting    int  `json:"waiting"`     // Waiting for capacity
	InRampUp   bool `json:"in_ramp_up"`  // Currently ramping up
	InCooldown bool `json:"in_cooldown"` // Currently in cooldown
}

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

type AgentCapsConfig struct {
	// Default is the default cap config for unknown agent types.
	Default AgentCapConfig `json:"default"`

	// PerAgent contains per-agent-type overrides.
	PerAgent map[string]AgentCapConfig `json:"per_agent,omitempty"`

	// GlobalMax is the absolute maximum across all agents (0 = no limit).
	GlobalMax int `json:"global_max"`
}

type AgentLimiterConfig struct {
	// Default is the default limiter config for unknown agent types.
	Default LimiterConfig `json:"default"`

	// PerAgent contains per-agent-type overrides.
	PerAgent map[string]LimiterConfig `json:"per_agent,omitempty"`
}

type BackoffConfig struct {
	// InitialDelay is the starting delay for backoff.
	InitialDelay time.Duration `json:"initial_delay"`

	// MaxDelay is the maximum backoff delay.
	MaxDelay time.Duration `json:"max_delay"`

	// Multiplier is the factor by which delay increases.
	Multiplier float64 `json:"multiplier"`

	// JitterFactor is the random jitter as a fraction of delay (0.0-1.0).
	JitterFactor float64 `json:"jitter_factor"`

	// MaxRetries is the maximum number of retry attempts.
	MaxRetries int `json:"max_retries"`

	// PauseQueueOnBackoff pauses the scheduler queue during backoff.
	PauseQueueOnBackoff bool `json:"pause_queue_on_backoff"`

	// ConsecutiveFailuresThreshold triggers global backoff after N failures.
	ConsecutiveFailuresThreshold int `json:"consecutive_failures_threshold"`
}

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

type BackoffStats struct {
	TotalBackoffs     int64             `json:"total_backoffs"`
	TotalRetries      int64             `json:"total_retries"`
	TotalExhausted    int64             `json:"total_exhausted"`
	MaxConsecutive    int               `json:"max_consecutive"`
	TotalBackoffTime  time.Duration     `json:"total_backoff_time"`
	LastBackoffReason ResourceErrorType `json:"last_backoff_reason,omitempty"`
	LastBackoffAt     time.Time         `json:"last_backoff_at,omitempty"`
}

type CapsStats struct {
	// PerAgent contains per-agent statistics.
	PerAgent map[string]AgentCapStats `json:"per_agent"`

	// TotalRunning is the total running across all agents.
	TotalRunning int `json:"total_running"`

	// TotalWaiting is the total waiting across all agents.
	TotalWaiting int `json:"total_waiting"`
}

type Config struct {
	// MaxConcurrent is the maximum number of concurrent spawn operations.
	MaxConcurrent int `json:"max_concurrent"`

	// GlobalRateLimit is the global rate limiter configuration.
	GlobalRateLimit LimiterConfig `json:"global_rate_limit"`

	// AgentRateLimits is the per-agent rate limiter configuration.
	AgentRateLimits AgentLimiterConfig `json:"agent_rate_limits"`

	// AgentCaps is the per-agent concurrency caps configuration.
	AgentCaps AgentCapsConfig `json:"agent_caps"`

	// FairScheduler is the fair scheduler configuration.
	FairScheduler FairSchedulerConfig `json:"fair_scheduler"`

	// Backoff is the backoff configuration for resource errors.
	Backoff BackoffConfig `json:"backoff"`

	// MaxCompleted is the number of completed jobs to retain for status.
	MaxCompleted int `json:"max_completed"`

	// DefaultRetries is the default number of retries for failed jobs.
	DefaultRetries int `json:"default_retries"`

	// DefaultRetryDelay is the default delay between retries.
	DefaultRetryDelay time.Duration `json:"default_retry_delay"`

	// BackpressureThreshold is the queue size that triggers backpressure alerts.
	BackpressureThreshold int `json:"backpressure_threshold"`

	// Headroom is the pre-spawn resource headroom configuration.
	Headroom HeadroomConfig `json:"headroom"`
}

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

type FairSchedulerConfig struct {
	MaxPerSession int `json:"max_per_session"`
	MaxPerBatch   int `json:"max_per_batch"`
}

type HeadroomConfig struct {
	// Enabled toggles headroom checking.
	Enabled bool `json:"enabled"`

	// Threshold is the usage percentage (0.0-1.0) above which spawns are blocked.
	// Default: 0.75 (75%)
	Threshold float64 `json:"threshold"`

	// WarnThreshold is the usage percentage (0.0-1.0) at which warnings are logged.
	// Default: 0.70 (70%)
	WarnThreshold float64 `json:"warn_threshold"`

	// RecheckInterval is how often to recheck resource headroom when blocked.
	// Default: 5s
	RecheckInterval time.Duration `json:"recheck_interval"`

	// MinHeadroom is the minimum number of free process slots required.
	// Default: 50
	MinHeadroom int `json:"min_headroom"`

	// CacheTimeout is how long to cache headroom measurements.
	// Default: 2s
	CacheTimeout time.Duration `json:"cache_timeout"`
}

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

type HeadroomStatus struct {
	// Available is the number of free process slots.
	Available int `json:"available"`

	// UsagePercent is the current usage as a percentage (0.0-1.0).
	UsagePercent float64 `json:"usage_percent"`

	// Blocked indicates if spawns are blocked.
	Blocked bool `json:"blocked"`

	// BlockReason is the reason for blocking (empty if not blocked).
	BlockReason string `json:"block_reason,omitempty"`

	// Limits contains the detected resource limits.
	Limits *ResourceLimits `json:"limits"`

	// Usage contains the current resource usage.
	Usage *ResourceUsage `json:"usage"`

	// LastCheck is when headroom was last checked.
	LastCheck time.Time `json:"last_check"`
}

type Hooks struct {
	// OnJobEnqueued is called when a job is added to the queue.
	OnJobEnqueued func(job *SpawnJob)

	// OnJobStarted is called when a job starts executing.
	OnJobStarted func(job *SpawnJob)

	// OnJobCompleted is called when a job completes successfully.
	OnJobCompleted func(job *SpawnJob)

	// OnJobFailed is called when a job fails.
	OnJobFailed func(job *SpawnJob, err error)

	// OnJobRetrying is called when a job is about to retry.
	OnJobRetrying func(job *SpawnJob, attempt int)

	// OnBackpressure is called when the queue is experiencing backpressure.
	OnBackpressure func(queueSize int, waitTime time.Duration)

	// OnGuardrailTriggered is called when a guardrail blocks a spawn.
	OnGuardrailTriggered func(job *SpawnJob, reason string)
}

type JobPriority int

type JobProgress struct {
	// ID is the job ID.
	ID string `json:"id"`

	// Type is the job type.
	Type JobType `json:"type"`

	// Status is the current status.
	Status JobStatus `json:"status"`

	// SessionName is the target session.
	SessionName string `json:"session_name"`

	// AgentType is the agent type if applicable.
	AgentType string `json:"agent_type,omitempty"`

	// PaneIndex is the pane index if applicable.
	PaneIndex int `json:"pane_index,omitempty"`

	// Priority is the job priority.
	Priority JobPriority `json:"priority"`

	// QueuedFor is how long the job has been queued.
	QueuedFor time.Duration `json:"queued_for,omitempty"`

	// RunningFor is how long the job has been running.
	RunningFor time.Duration `json:"running_for,omitempty"`

	// Error is any error message.
	Error string `json:"error,omitempty"`

	// RetryCount is the current retry count.
	RetryCount int `json:"retry_count,omitempty"`

	// EstimatedETASeconds is estimated time until this job starts.
	EstimatedETASeconds float64 `json:"estimated_eta_seconds,omitempty"`
}

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

type JobStatus string

type JobType string

type LimiterConfig struct {
	// Rate is the number of tokens added per second.
	Rate float64 `json:"rate"`

	// Capacity is the maximum number of tokens (burst size).
	Capacity float64 `json:"capacity"`

	// BurstAllowed enables burst mode.
	BurstAllowed bool `json:"burst_allowed"`

	// MinInterval is the minimum time between operations.
	MinInterval time.Duration `json:"min_interval"`
}

type LimiterStats struct {
	// TotalRequests is the total number of Wait calls.
	TotalRequests int64 `json:"total_requests"`

	// AllowedRequests is requests that were allowed immediately.
	AllowedRequests int64 `json:"allowed_requests"`

	// WaitedRequests is requests that had to wait.
	WaitedRequests int64 `json:"waited_requests"`

	// DeniedRequests is requests denied due to timeout/cancellation.
	DeniedRequests int64 `json:"denied_requests"`

	// TotalWaitTime is the cumulative wait time.
	TotalWaitTime time.Duration `json:"total_wait_time"`

	// MaxWaitTime is the longest wait time recorded.
	MaxWaitTime time.Duration `json:"max_wait_time"`

	// AvgWaitTime is the average wait time.
	AvgWaitTime time.Duration `json:"avg_wait_time"`

	// CurrentTokens is the current token count.
	CurrentTokens float64 `json:"current_tokens"`

	// Waiting is the number of requests currently waiting.
	Waiting int `json:"waiting"`
}

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

type Progress struct {
	// Timestamp is when this progress snapshot was taken.
	Timestamp time.Time `json:"timestamp"`

	// Status is the overall scheduler status.
	Status string `json:"status"` // running, paused, stopped

	// QueuedCount is the number of jobs waiting in queue.
	QueuedCount int `json:"queued_count"`

	// RunningCount is the number of jobs currently executing.
	RunningCount int `json:"running_count"`

	// CompletedCount is the number of completed jobs (session lifetime).
	CompletedCount int `json:"completed_count"`

	// FailedCount is the number of failed jobs.
	FailedCount int `json:"failed_count"`

	// EstimatedETASeconds is the estimated time until queue is empty.
	EstimatedETASeconds float64 `json:"estimated_eta_seconds,omitempty"`

	// RateLimitInfo contains current rate limiter state.
	RateLimitInfo RateLimitInfo `json:"rate_limit_info"`

	// Queued contains details of queued jobs.
	Queued []JobProgress `json:"queued,omitempty"`

	// Running contains details of running jobs.
	Running []JobProgress `json:"running,omitempty"`

	// RecentCompleted contains recently completed jobs.
	RecentCompleted []JobProgress `json:"recent_completed,omitempty"`

	// BySession contains progress grouped by session.
	BySession map[string]*SessionProgress `json:"by_session,omitempty"`
}

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

type ProgressEvent struct {
	// Type is the event type.
	Type string `json:"type"` // job_enqueued, job_started, job_completed, job_failed, progress_update

	// JobID is the job ID if applicable.
	JobID string `json:"job_id,omitempty"`

	// SessionName is the session name if applicable.
	SessionName string `json:"session_name,omitempty"`

	// Progress is the current progress snapshot.
	Progress *Progress `json:"progress,omitempty"`

	// Message is a human-readable message.
	Message string `json:"message,omitempty"`

	// Timestamp is when this event occurred.
	Timestamp time.Time `json:"timestamp"`
}

type ProgressSubscriber func(event ProgressEvent)

type QueueStats struct {
	// TotalEnqueued is the total number of jobs ever enqueued.
	TotalEnqueued int64 `json:"total_enqueued"`

	// TotalDequeued is the total number of jobs ever dequeued.
	TotalDequeued int64 `json:"total_dequeued"`

	// CurrentSize is the current queue size.
	CurrentSize int `json:"current_size"`

	// MaxSize is the maximum queue size ever observed.
	MaxSize int `json:"max_size"`

	// ByPriority is the count per priority level.
	ByPriority map[JobPriority]int `json:"by_priority"`

	// ByType is the count per job type.
	ByType map[JobType]int `json:"by_type"`

	// AvgWaitTime is the average time jobs spend in the queue.
	AvgWaitTime time.Duration `json:"avg_wait_time"`

	// MaxWaitTime is the maximum time a job spent in the queue.
	MaxWaitTime time.Duration `json:"max_wait_time"`
	// contains filtered or unexported fields
}

type RateLimitInfo struct {
	// AvailableTokens is the current token count.
	AvailableTokens float64 `json:"available_tokens"`

	// Rate is tokens per second.
	Rate float64 `json:"rate"`

	// Capacity is the maximum tokens.
	Capacity float64 `json:"capacity"`

	// WaitingCount is requests waiting for tokens.
	WaitingCount int `json:"waiting_count"`

	// NextTokenInMs is milliseconds until next token.
	NextTokenInMs int64 `json:"next_token_in_ms"`
}

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

type ResourceError struct {
	Original   error
	Type       ResourceErrorType
	ExitCode   int
	StderrHint string
	Retryable  bool
	Timestamp  time.Time
}

type ResourceErrorType string

type ResourceLimits struct {
	// UlimitNproc is the user's process limit from ulimit -u.
	UlimitNproc int `json:"ulimit_nproc"`

	// CgroupPidsMax is the cgroup v2 pids.max limit (0 if not available).
	CgroupPidsMax int `json:"cgroup_pids_max"`

	// SystemdTasksMax is the systemd TasksMax limit (0 if not available).
	SystemdTasksMax int `json:"systemd_tasks_max"`

	// KernelPidMax is the kernel's pid_max from /proc/sys/kernel/pid_max.
	KernelPidMax int `json:"kernel_pid_max"`

	// EffectiveLimit is min(all non-zero limits).
	EffectiveLimit int `json:"effective_limit"`

	// Source indicates which limit is the effective one.
	Source string `json:"source"`
}

type ResourceUsage struct {
	// CgroupPidsCurrent is the cgroup v2 pids.current (0 if not available).
	CgroupPidsCurrent int `json:"cgroup_pids_current"`

	// ProcessCount is the number of processes owned by the current user.
	ProcessCount int `json:"process_count"`

	// EffectiveUsage is the best estimate of current usage.
	EffectiveUsage int `json:"effective_usage"`

	// Source indicates which usage metric is being used.
	Source string `json:"source"`
}

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

type SessionProgress struct {
	// SessionName is the session name.
	SessionName string `json:"session_name"`

	// QueuedCount is queued jobs for this session.
	QueuedCount int `json:"queued_count"`

	// RunningCount is running jobs for this session.
	RunningCount int `json:"running_count"`

	// CompletedCount is completed jobs for this session.
	CompletedCount int `json:"completed_count"`

	// FailedCount is failed jobs for this session.
	FailedCount int `json:"failed_count"`

	// TotalPanes is the total panes being spawned.
	TotalPanes int `json:"total_panes"`

	// PanesReady is panes that are ready.
	PanesReady int `json:"panes_ready"`

	// ProgressPercent is the completion percentage.
	ProgressPercent float64 `json:"progress_percent"`
}

type SpawnExecutor func(ctx context.Context, job *SpawnJob) error

type SpawnJob struct {
	// ID is a unique identifier for this job.
	ID string `json:"id"`

	// Type is the kind of spawn operation.
	Type JobType `json:"type"`

	// Priority determines processing order.
	Priority JobPriority `json:"priority"`

	// SessionName is the target session.
	SessionName string `json:"session_name"`

	// AgentType is the type of agent (cc, cod, gmi) if applicable.
	AgentType string `json:"agent_type,omitempty"`

	// PaneIndex is the target pane index if applicable.
	PaneIndex int `json:"pane_index,omitempty"`

	// Directory is the working directory for the spawn.
	Directory string `json:"directory,omitempty"`

	// Status is the current job status.
	Status JobStatus `json:"status"`

	// CreatedAt is when the job was created.
	CreatedAt time.Time `json:"created_at"`

	// ScheduledAt is when the job was approved by rate limiter.
	ScheduledAt time.Time `json:"scheduled_at,omitempty"`

	// StartedAt is when execution began.
	StartedAt time.Time `json:"started_at,omitempty"`

	// CompletedAt is when the job finished (success or failure).
	CompletedAt time.Time `json:"completed_at,omitempty"`

	// Error contains any error message if failed.
	Error string `json:"error,omitempty"`

	// RetryCount is the number of retry attempts.
	RetryCount int `json:"retry_count"`

	// MaxRetries is the maximum number of retries allowed.
	MaxRetries int `json:"max_retries"`

	// RetryDelay is the delay before next retry.
	RetryDelay time.Duration `json:"retry_delay,omitempty"`

	// Metadata contains additional context for the job.
	Metadata map[string]interface{} `json:"metadata,omitempty"`

	// Result contains the result of the spawn operation.
	Result *SpawnResult `json:"result,omitempty"`

	// BatchID groups related jobs for fairness tracking.
	BatchID string `json:"batch_id,omitempty"`

	// ParentJobID is the ID of the parent job if this is a sub-job.
	ParentJobID string `json:"parent_job_id,omitempty"`

	// Callback is called when the job completes (success or failure).
	Callback func(*SpawnJob) `json:"-"`
	// contains filtered or unexported fields
}

type SpawnResult struct {
	// SessionName is the created/target session.
	SessionName string `json:"session_name"`

	// PaneID is the created pane ID.
	PaneID string `json:"pane_id,omitempty"`

	// PaneIndex is the index of the pane.
	PaneIndex int `json:"pane_index,omitempty"`

	// AgentType is the launched agent type.
	AgentType string `json:"agent_type,omitempty"`

	// Title is the pane title.
	Title string `json:"title,omitempty"`

	// Duration is how long the spawn took.
	Duration time.Duration `json:"duration"`
}

type Stats struct {
	// TotalSubmitted is jobs submitted to scheduler.
	TotalSubmitted int64 `json:"total_submitted"`

	// TotalCompleted is jobs that completed successfully.
	TotalCompleted int64 `json:"total_completed"`

	// TotalFailed is jobs that failed after all retries.
	TotalFailed int64 `json:"total_failed"`

	// TotalRetried is the total number of retry attempts.
	TotalRetried int64 `json:"total_retried"`

	// CurrentQueueSize is the current queue size.
	CurrentQueueSize int `json:"current_queue_size"`

	// CurrentRunning is the number of currently running jobs.
	CurrentRunning int `json:"current_running"`

	// AvgQueueTime is the average time jobs spend in queue.
	AvgQueueTime time.Duration `json:"avg_queue_time"`

	// AvgExecutionTime is the average job execution time.
	AvgExecutionTime time.Duration `json:"avg_execution_time"`

	// IsPaused indicates if the scheduler is paused.
	IsPaused bool `json:"is_paused"`

	// StartedAt is when the scheduler started.
	StartedAt time.Time `json:"started_at"`

	// Uptime is how long the scheduler has been running.
	Uptime time.Duration `json:"uptime"`

	// LimiterStats contains rate limiter statistics.
	LimiterStats LimiterStats `json:"limiter_stats"`

	// QueueStats contains queue statistics.
	QueueStats QueueStats `json:"queue_stats"`

	// BackoffStats contains backoff statistics.
	BackoffStats BackoffStats `json:"backoff_stats"`

	// CapsStats contains per-agent concurrency cap statistics.
	CapsStats CapsStats `json:"caps_stats"`

	// InGlobalBackoff indicates if global backoff is active.
	InGlobalBackoff bool `json:"in_global_backoff"`

	// RemainingBackoff is the remaining backoff duration if in global backoff.
	RemainingBackoff time.Duration `json:"remaining_backoff,omitempty"`

	// HeadroomStatus contains resource headroom status.
	HeadroomStatus HeadroomStatus `json:"headroom_status"`
}