domain

type BackgroundJob interface {
	// Meta returns the job's identity/display snapshot.
	Meta() JobMeta
	// Run blocks until the job reaches a terminal state or ctx is cancelled,
	// emitting intermediate JobSignals via emit, and returns the terminal result.
	// It MUST return promptly once ctx is cancelled.
	Run(ctx context.Context, emit func(JobSignal)) agentdomain.ToolExecutionResult
	// Wind delivers a graceful wind-down (WindWrapUp) or hard stop (WindStop) to a
	// RUNNING job. It must be safe to call from another goroutine while Run is in
	// flight, be idempotent, and a no-op once the job has finished.
	Wind(ctx context.Context, sig WindSignal) error
	// Close tears down the resources the job owns (its per-kind tracker record, an
	// interactive subagent's tmux pane and temp files, ...). The supervisor calls
	// it exactly once when it reaps a finished job after the retention window. It
	// must be idempotent and must not touch the running process (use Wind for that).
	Close()
}

type BackgroundShell struct {
	ShellID      string
	Command      string
	Cmd          *exec.Cmd
	StartedAt    time.Time
	CompletedAt  *time.Time
	State        ShellState
	ExitCode     *int
	OutputBuffer OutputRingBuffer
	CancelFunc   context.CancelFunc
	ReadOffset   int64

	ReadersDone <-chan struct{}
}

type BackgroundShellService interface {
	// DetachToBackground moves a running command to background. readersDone, when
	// non-nil, is closed once the caller's pipe readers reach EOF; the supervisor
	// waits on it before reaping so trailing output is not truncated.
	DetachToBackground(ctx context.Context, cmd *exec.Cmd, command string, outputBuffer OutputRingBuffer, readersDone <-chan struct{}) (string, error)

	// GetShellOutput retrieves output from a shell
	GetShellOutput(shellID string, fromOffset int64) (string, int64, ShellState, error)

	// GetShellOutputWithFilter retrieves filtered output from a shell
	GetShellOutputWithFilter(shellID string, fromOffset int64, filterPattern string) (string, int64, ShellState, error)

	// GetShell returns a specific shell by ID
	GetShell(shellID string) *BackgroundShell

	// GetAllShells returns all tracked shells
	GetAllShells() []*BackgroundShell

	// CancelShell cancels a running background shell
	CancelShell(shellID string) error

	// RemoveShell removes a shell from tracking
	RemoveShell(shellID string) error
}

type BackgroundTaskRegistry interface {
	ShellTracker
	SubagentTracker

	// HasPending reports whether *any* background work is still in flight,
	// regardless of type. True when there is at least one session-holding job
	// running (an A2A task, a background shell, or a HEADLESS subagent).
	// It deliberately excludes interactive subagents so a one-shot `infer headless`
	// does not hang at exit waiting on a user-driven tmux pane.
	HasPending() bool

	// Submit hands a background job to the supervisor, which spawns its monitor
	// goroutine and folds its result back onto the conversation when it finishes.
	// This is the single entry point every kind (A2A task, shell, subagent) uses
	// instead of running its own poller.
	Submit(job BackgroundJob)

	// Snapshot returns the supervisor's view of all live and recently-finished
	// jobs for the task view and status line.
	Snapshot() []TrackedJob

	// CountRunningJobs returns how many supervised jobs are running, optionally
	// filtered to one kind (pass "" for all kinds).
	CountRunningJobs(kind JobKind) int

	// IsJobRunning reports whether the supervised job with the given id is still
	// running. It is the per-id liveness query a tool uses (via the narrow
	// JobLivenessReporter projection) to defer to the supervisor - the single
	// source of truth - instead of racing it with a manual read.
	IsJobRunning(id string) bool

	// WindJob sends a graceful wind-down or hard stop to one supervised job.
	WindJob(id string, sig WindSignal) error
}

type JobFinisher interface {
	Finished(result agentdomain.ToolExecutionResult)
}

type JobIdleReporter interface {
	BackgroundJob
	Idle() bool
	IdleSince() time.Time
}

type JobKind string

type JobLivenessReporter interface {
	IsJobRunning(id string) bool
}

type JobMeta struct {
	ID           string
	SessionID    string
	Kind         JobKind
	Origin       string
	Label        string
	Description  string
	Detail       string
	StartedAt    time.Time
	Silent       bool
	HoldsSession bool
}

type JobNotifier interface {
	Notification(result agentdomain.ToolExecutionResult) string
}

type JobOutputProvider interface {
	Output() string
}

type JobPatch struct {
	Name           *string
	Description    *string
	CronExpression *string
	Prompt         *string
	Model          *string
	RunOnce        *bool
}

type JobSignal struct {
	// Note is a human-facing line surfaced to the UI and, when Enqueue is set,
	// landed on the message queue so the agent reads it on its next turn.
	Note string
	// Enqueue lands Note on the message queue and wakes the agent loop; otherwise
	// Note is a UI-only status update.
	Enqueue bool
	// State is an optional kind-specific status token (e.g. an A2A task state).
	State string
}

type JobStatsProvider interface {
	Stats() *SubagentRunStats
}

type JobStatus string

type JobStopper interface {
	WindJob(id string, sig WindSignal) error
}

type JobSubmitter interface {
	Submit(job BackgroundJob)
}

type OutputRingBuffer interface {
	Write(p []byte) (n int, err error)
	ReadFrom(offset int64) (string, int64)
	Recent(maxBytes int) string
	TotalWritten() int64
	Size() int
	String() string
	Clear()
}

type PaneObservation struct {
	// Harvested is the subagent chat's real last assistant message (from its
	// result file); "" until its turn completes. The ONLY content ever delivered -
	// the pane is never scraped for content (its TUI chrome is noise).
	Harvested string
	// Screen is a snapshot of the pane's current tail, used by the poller to detect
	// idleness by stability: while the subagent works the chat's elapsed-time
	// spinner changes this every poll; at idle it is frozen. The input-box
	// placeholder ("Type your message") is NOT a usable idle signal - it is drawn
	// even mid-turn - so the stability of the whole tail is used instead.
	Screen string
	// Gone means the pane no longer exists (closed).
	Gone bool
	// Dead means the pane's process exited (the pane is kept open by remain-on-exit).
	Dead bool
	// AwaitingApproval means the subagent is blocked on a tool-approval prompt.
	AwaitingApproval bool
	// ApprovalSummary describes the pending tool call (name + args) when awaiting.
	ApprovalSummary string
	// Done is the result file's done flag: the subagent explicitly marked this
	// write as its task's terminal turn.
	Done bool
	// HarvestFailed means the harvested turn was a failed terminal turn
	// (the result file recorded Success=false).
	HarvestFailed bool
	// HarvestError is the error the subagent recorded for the harvested turn.
	HarvestError string
	// HarvestStats is the run's tool and token tally, nil when none was recorded.
	HarvestStats *SubagentRunStats
}

type RunEvent struct {
	Line []byte
	Err  error
	Done bool
}

type RunRecord struct {
	SessionID  string     `yaml:"session_id" json:"session_id"`
	JobID      string     `yaml:"job_id" json:"job_id"`
	Status     RunStatus  `yaml:"status" json:"status"`
	Error      string     `yaml:"error,omitempty" json:"error,omitempty"`
	StartedAt  time.Time  `yaml:"started_at" json:"started_at"`
	FinishedAt *time.Time `yaml:"finished_at,omitempty" json:"finished_at,omitempty"`
}

type RunStatus string

type ScheduledJob struct {
	ID             string     `yaml:"id" json:"id"`
	Name           string     `yaml:"name,omitempty" json:"name,omitempty"`
	Description    string     `yaml:"description,omitempty" json:"description,omitempty"`
	CronExpression string     `yaml:"cron_expression" json:"cron_expression"`
	Prompt         string     `yaml:"prompt" json:"prompt"`
	Channel        string     `yaml:"channel,omitempty" json:"channel,omitempty"`
	RecipientID    string     `yaml:"recipient_id,omitempty" json:"recipient_id,omitempty"`
	Model          string     `yaml:"model,omitempty" json:"model,omitempty"`
	RunOnce        bool       `yaml:"run_once,omitempty" json:"run_once,omitempty"`
	CreatedAt      time.Time  `yaml:"created_at" json:"created_at"`
	UpdatedAt      time.Time  `yaml:"updated_at" json:"updated_at"`
	LastRun        *time.Time `yaml:"last_run,omitempty" json:"last_run,omitempty"`
	LastError      string     `yaml:"last_error,omitempty" json:"last_error,omitempty"`
}

type ShellInfo struct {
	ShellID     string
	Command     string
	State       ShellState
	StartedAt   time.Time
	CompletedAt *time.Time
	ExitCode    *int
	OutputSize  int64
	Elapsed     time.Duration
}

type ShellState string

type ShellTracker interface {
	// Add adds a new shell to the tracker.
	// Returns an error if max concurrent limit is reached.
	Add(shell *BackgroundShell) error

	// Get retrieves a shell by ID.
	// Returns nil if not found.
	Get(shellID string) *BackgroundShell

	// GetAll returns all tracked shells.
	GetAll() []*BackgroundShell

	// Remove removes a shell from the tracker.
	Remove(shellID string) error

	// CountRunning returns the number of shells in running state.
	CountRunning() int
}

type SubagentApprovalFile struct {
	Awaiting bool   `json:"awaiting"`
	Summary  string `json:"summary,omitempty"`
}

type SubagentMode string

type SubagentResultFile struct {
	FinalAssistant string            `json:"final_assistant"`
	Success        bool              `json:"success"`
	Error          string            `json:"error,omitempty"`
	SessionID      string            `json:"session_id,omitempty"`
	Done           bool              `json:"done,omitempty"`
	Stats          *SubagentRunStats `json:"stats,omitempty"`
}

type SubagentRunStats struct {
	ToolsSucceeded int `json:"tools_succeeded"`
	ToolsFailed    int `json:"tools_failed"`
	InputTokens    int `json:"input_tokens"`
	OutputTokens   int `json:"output_tokens"`
	CachedTokens   int `json:"cached_tokens,omitempty"`
}

type SubagentState struct {
	ID          string
	Label       string
	Description string
	Model       string
	Mode        SubagentMode
	SessionID   string
	PaneID      string
	Status      SubagentStatus
	StartedAt   time.Time
	CancelFunc  context.CancelFunc
	Silent      bool
	Input       func(text string) error
}

type SubagentStatus string

type SubagentTracker interface {
	// AddSubagent registers a running subagent. Returns an error if the ID
	// is already tracked.
	AddSubagent(state *SubagentState) error

	// GetSubagent returns a subagent by ID, or nil if not tracked.
	GetSubagent(id string) *SubagentState

	// GetAllSubagents returns all tracked subagents.
	GetAllSubagents() []*SubagentState

	// RemoveSubagent removes a subagent from tracking.
	RemoveSubagent(id string) error

	// CountRunningSubagents returns the number of subagents in the running state.
	CountRunningSubagents() int

	// SetSubagentStatus atomically updates a subagent's status under the
	// tracker's lock. Returns an error if the ID is not tracked.
	SetSubagentStatus(id string, status SubagentStatus) error
}

type SubagentTurnLine struct {
	Type string `json:"type"`
	SubagentResultFile
}

type TitleGenerator interface {
	ProcessPendingTitles(ctx context.Context) error
}

type TrackedJob struct {
	Meta        JobMeta
	Status      JobStatus
	CompletedAt *time.Time
	Output      string
	Stats       *SubagentRunStats
}

type WindSignal int