background

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package background manages detached local jobs started by Codog.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsActiveStatus 

func IsActiveStatus(status string) bool

IsActiveStatus reports whether a task is still expected to make progress or transition into a terminal state.

func IsTerminalStatus 

func IsTerminalStatus(status string) bool

IsTerminalStatus reports whether a task status is terminal.

Types

type EventProvenance 

type EventProvenance struct {
	SourceKind  string `json:"source_kind"`
	Environment string `json:"environment"`
	Channel     string `json:"channel"`
	Emitter     string `json:"emitter"`
	Confidence  string `json:"confidence"`
}

EventProvenance labels the source and trust level of a lane event.

func NormalizeEventProvenance 

func NormalizeEventProvenance(provenance EventProvenance) EventProvenance

NormalizeEventProvenance fills missing event provenance fields with stable defaults and canonicalizes known values.

type LaneBoard 

type LaneBoard struct {
	GeneratedAt time.Time        `json:"generated_at"`
	Active      []LaneBoardEntry `json:"active"`
	Blocked     []LaneBoardEntry `json:"blocked"`
	Finished    []LaneBoardEntry `json:"finished"`
}

type LaneBoardEntry 

type LaneBoardEntry struct {
	TaskID          string              `json:"task_id"`
	Prompt          string              `json:"prompt,omitempty"`
	Command         string              `json:"command,omitempty"`
	Kind            string              `json:"kind,omitempty"`
	SessionID       string              `json:"session_id,omitempty"`
	Status          string              `json:"status"`
	Heartbeat       *LaneHeartbeat      `json:"heartbeat,omitempty"`
	Freshness       LaneFreshness       `json:"freshness"`
	Provenance      EventProvenance     `json:"provenance"`
	ScopeBinding    ScopeBinding        `json:"scope_binding"`
	Lifecycle       LifecycleResolution `json:"lifecycle"`
	TerminalOutcome *TerminalOutcome    `json:"terminal_outcome,omitempty"`
}

type LaneFreshness 

type LaneFreshness string
const (
	LaneFreshnessHealthy       LaneFreshness = "healthy"
	LaneFreshnessStalled       LaneFreshness = "stalled"
	LaneFreshnessTransportDead LaneFreshness = "transport_dead"
	LaneFreshnessUnknown       LaneFreshness = "unknown"
)

type LaneHeartbeat 

type LaneHeartbeat struct {
	ObservedAt     time.Time       `json:"observed_at"`
	TransportAlive bool            `json:"transport_alive"`
	Status         string          `json:"status,omitempty"`
	Provenance     EventProvenance `json:"provenance"`
}

type LifecycleResolution 

type LifecycleResolution struct {
	Status               string `json:"status"`
	Terminal             bool   `json:"terminal"`
	TerminalStateUnknown bool   `json:"terminal_state_unknown,omitempty"`
	Reason               string `json:"reason,omitempty"`
}

LifecycleResolution describes the canonical lifecycle state inferred from task status and transport freshness.

func ResolveLifecycle 

func ResolveLifecycle(status string, freshness LaneFreshness) LifecycleResolution

ResolveLifecycle returns the canonical lifecycle outcome for a task.

type PruneOptions 

type PruneOptions struct {
	OlderThan time.Duration
	Keep      int
}

func DefaultPruneOptions 

func DefaultPruneOptions() PruneOptions

type PruneResult 

type PruneResult struct {
	Removed      []string `json:"removed"`
	RemovedCount int      `json:"removed_count"`
	Kept         int      `json:"kept"`
}

type RestartPolicy 

type RestartPolicy struct {
	Enabled      bool   `json:"enabled"`
	Mode         string `json:"mode,omitempty"`
	MaxAttempts  int    `json:"max_attempts,omitempty"`
	DelaySeconds int    `json:"delay_seconds,omitempty"`
}

type RunOptions 

type RunOptions struct {
	Kind          string
	AgentType     string
	SessionID     string
	RestartedFrom string
	RestartPolicy *RestartPolicy
	RestartCount  int
	Env           []string
	Prompt        string
	Description   string
	TaskPacket    json.RawMessage
	ScopeBinding  ScopeBinding
}

type ScopeBinding 

type ScopeBinding struct {
	Owner         string `json:"owner,omitempty"`
	WorkflowScope string `json:"workflow_scope"`
	WatcherAction string `json:"watcher_action"`
	Actionable    bool   `json:"actionable"`
}

ScopeBinding declares ownership and watcher responsibility for a lane.

func NormalizeScopeBinding 

func NormalizeScopeBinding(binding ScopeBinding) ScopeBinding

NormalizeScopeBinding fills missing lane ownership fields with stable defaults and derives whether the current watcher should act.

type Store 

type Store struct {
	Dir string
}

func NewStore 

func NewStore(configHome string) Store

func (Store) Get 

func (s Store) Get(id string) (Task, error)

func (Store) LaneBoard 

func (s Store) LaneBoard(stalledAfter time.Duration) (LaneBoard, error)

func (Store) LaneBoardAt 

func (s Store) LaneBoardAt(now time.Time, stalledAfter time.Duration) (LaneBoard, error)

func (Store) List 

func (s Store) List() ([]Task, error)

func (Store) LogFrom 

func (s Store) LogFrom(id string, offset int64) (int64, string, error)

func (Store) LogRange 

func (s Store) LogRange(id string, offset int64, limitBytes int64) (int64, string, error)

func (Store) Logs 

func (s Store) Logs(id string, limitBytes int64) (string, error)

func (Store) Prune 

func (s Store) Prune(options PruneOptions) (PruneResult, error)

func (Store) RecordTerminalEvent 

func (s Store) RecordTerminalEvent(id string, event TerminalEvent) (Task, error)

RecordTerminalEvent appends a terminal notification while preserving only one actionable outcome for downstream automation.

func (Store) Restart 

func (s Store) Restart(id string, cwd string) (Task, error)

func (Store) Run 

func (s Store) Run(command string, cwd string) (Task, error)

func (Store) RunWithOptions 

func (s Store) RunWithOptions(command string, cwd string, options RunOptions) (Task, error)

func (Store) Status 

func (s Store) Status(id string) (Task, error)

func (Store) Stop 

func (s Store) Stop(id string) (Task, error)

func (Store) SuperviseOnce 

func (s Store) SuperviseOnce(now time.Time) (SuperviseResult, error)

func (Store) Update 

func (s Store) Update(id string, message string) (Task, error)

func (Store) UpdateHeartbeat 

func (s Store) UpdateHeartbeat(id string, heartbeat LaneHeartbeat) (Task, error)

func (Store) Watch 

func (s Store) Watch(ctx context.Context, id string, options WatchOptions, emit func(WatchEvent) error) error

type SuperviseResult 

type SuperviseResult struct {
	Restarted []Task          `json:"restarted"`
	Skipped   []SuperviseSkip `json:"skipped,omitempty"`
}

type SuperviseSkip 

type SuperviseSkip struct {
	ID     string `json:"id"`
	Reason string `json:"reason"`
}

type Task 

type Task struct {
	ID              string           `json:"id"`
	Kind            string           `json:"kind,omitempty"`
	AgentType       string           `json:"agent_type,omitempty"`
	Command         string           `json:"command"`
	Prompt          string           `json:"prompt,omitempty"`
	Description     string           `json:"description,omitempty"`
	TaskPacket      json.RawMessage  `json:"task_packet,omitempty"`
	Workspace       string           `json:"workspace,omitempty"`
	SessionID       string           `json:"session_id,omitempty"`
	RestartPolicy   *RestartPolicy   `json:"restart_policy,omitempty"`
	RestartCount    int              `json:"restart_count,omitempty"`
	PID             int              `json:"pid"`
	Status          string           `json:"status"`
	StartedAt       time.Time        `json:"started_at"`
	CompletedAt     *time.Time       `json:"completed_at,omitempty"`
	ExitCode        *int             `json:"exit_code,omitempty"`
	LogPath         string           `json:"log_path"`
	Error           string           `json:"error,omitempty"`
	RestartedFrom   string           `json:"restarted_from,omitempty"`
	RestartedBy     string           `json:"restarted_by,omitempty"`
	Messages        []TaskMessage    `json:"messages,omitempty"`
	Heartbeat       *LaneHeartbeat   `json:"heartbeat,omitempty"`
	ScopeBinding    ScopeBinding     `json:"scope_binding"`
	TerminalEvents  []TerminalEvent  `json:"terminal_events,omitempty"`
	TerminalOutcome *TerminalOutcome `json:"terminal_outcome,omitempty"`
}

func FilterByKind 

func FilterByKind(tasks []Task, kind string) []Task

func FilterBySession 

func FilterBySession(tasks []Task, sessionID string) []Task

type TaskMessage 

type TaskMessage struct {
	Message   string    `json:"message"`
	CreatedAt time.Time `json:"created_at"`
}

type TerminalEvent 

type TerminalEvent struct {
	Sequence            int             `json:"sequence"`
	ObservedAt          time.Time       `json:"observed_at"`
	Status              string          `json:"status"`
	ExitCode            *int            `json:"exit_code,omitempty"`
	Error               string          `json:"error,omitempty"`
	Fingerprint         string          `json:"fingerprint"`
	Duplicate           bool            `json:"duplicate,omitempty"`
	DuplicateOf         string          `json:"duplicate_of,omitempty"`
	MateriallyDifferent bool            `json:"materially_different,omitempty"`
	Actionable          bool            `json:"actionable"`
	Provenance          EventProvenance `json:"provenance"`
}

TerminalEvent records one raw terminal notification for audit and dedupe.

type TerminalOutcome 

type TerminalOutcome struct {
	Fingerprint         string    `json:"fingerprint"`
	Status              string    `json:"status"`
	ExitCode            *int      `json:"exit_code,omitempty"`
	Error               string    `json:"error,omitempty"`
	ObservedAt          time.Time `json:"observed_at"`
	EventCount          int       `json:"event_count"`
	DuplicateCount      int       `json:"duplicate_count,omitempty"`
	ConflictCount       int       `json:"conflict_count,omitempty"`
	MateriallyDifferent bool      `json:"materially_different,omitempty"`
	Actionable          bool      `json:"actionable"`
}

TerminalOutcome is the single actionable terminal outcome for a lane.

type WatchEvent 

type WatchEvent struct {
	Type         string          `json:"type"`
	ID           string          `json:"id"`
	Offset       int64           `json:"offset,omitempty"`
	Data         string          `json:"data,omitempty"`
	Status       string          `json:"status,omitempty"`
	Error        string          `json:"error,omitempty"`
	Task         *Task           `json:"task,omitempty"`
	Provenance   EventProvenance `json:"provenance"`
	ScopeBinding ScopeBinding    `json:"scope_binding"`
}

type WatchOptions 

type WatchOptions struct {
	Offset    int64
	Interval  time.Duration
	MaxEvents int
}

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.