worker

Documentation

Overview

Package worker provides worker command resolution helpers.

Package worker provides worker completion detection helpers.

Package worker provides asynchronous worker dispatch helpers.

Package worker provides worker process execution with timeout and logging.

Package worker provides worker result ingestion for updating task state.

Package worker provides pidfile helpers for agent process observability.

Package worker provides worker command resolution helpers.

Index

• func IsCodexCommand(cfg config.Config, role index.Role) (bool, error)
• func ReadAgentPID(workerStateDir string) (int, bool, error)
• func ResolveCommand(cfg config.Config, role index.Role, taskPath string, repoRoot string, ...) ([]string, error)
• type AuditLogger
• type DispatchInput
• type DispatchResult
  • func DispatchWorker(input DispatchInput) (DispatchResult, error)
  • func DispatchWorkerFromConfig(cfg config.Config, task index.Task, stageResult StageResult, workDir string, ...) (DispatchResult, error)
• type ExecInput
• type ExecResult
  • func ExecuteWorker(input ExecInput) (ExecResult, error)
  • func ExecuteWorkerFromConfig(cfg config.Config, task index.Task, stageResult StageResult, workDir string, ...) (ExecResult, error)
  • func ExecuteWorkerFromConfigWithAudit(cfg config.Config, task index.Task, stageResult StageResult, workDir string, ...) (ExecResult, error)
• type ExitStatus
  • func ReadExitStatus(workerStateDir string, taskID string, stage roles.Stage) (ExitStatus, bool, error)
• type IngestInput
• type IngestResult
  • func CompletionResultToIngest(taskID string, stage roles.Stage, completion StageCompletion) (IngestResult, error)
  • func IngestWorkerResult(input IngestInput) (IngestResult, error)
• type StageCompletion
  • func CheckStageCompletion(worktreePath string, workerStateDir string, stage roles.Stage) (StageCompletion, error)
• type StageInput
• type StageResult
  • func StageEnvAndPrompts(input StageInput) (StageResult, error)

Functions

func IsCodexCommand

func IsCodexCommand(cfg config.Config, role index.Role) (bool, error)

IsCodexCommand reports whether the configured template runs the Codex CLI.

func ReadAgentPID

func ReadAgentPID(workerStateDir string) (int, bool, error)

ReadAgentPID returns the first valid pid found in the worker state directory.

func ResolveCommand

func ResolveCommand(cfg config.Config, role index.Role, taskPath string, repoRoot string, promptPath string) ([]string, error)

ResolveCommand resolves a worker command template for the given role and fills tokens.

Types

type AuditLogger

type AuditLogger interface {
	LogWorkerTimeout(taskID string, role string, timeoutSecs int, worktreePath string) error
}

AuditLogger defines the interface for audit logging.

type DispatchInput

type DispatchInput struct {
	Command        []string
	WorkDir        string
	TaskID         string
	Stage          roles.Stage
	EnvVars        map[string]string
	Warn           func(string)
	WorkerStateDir string
	SelectedCLI    string // The CLI name from config ("claude", "codex", "gemini", or "")
}

DispatchInput defines the inputs required for asynchronous worker dispatch.

type DispatchResult

type DispatchResult struct {
	PID            int
	StartedAt      time.Time
	StdoutPath     string
	StderrPath     string
	ExitPath       string
	WorkerStateDir string
}

DispatchResult captures the worker dispatch metadata.

func DispatchWorker

func DispatchWorker(input DispatchInput) (DispatchResult, error)

DispatchWorker launches a worker process in the background using nohup.

func DispatchWorkerFromConfig

func DispatchWorkerFromConfig(cfg config.Config, task index.Task, stageResult StageResult, workDir string, stage roles.Stage, warn func(string)) (DispatchResult, error)

DispatchWorkerFromConfig resolves the worker command and dispatches asynchronously.

type ExecInput

type ExecInput struct {
	Command        []string
	WorkDir        string
	TaskID         string
	TimeoutSecs    int
	EnvVars        map[string]string
	Warn           func(string)
	AuditLogger    AuditLogger
	Role           string
	WorktreePath   string
	WorkerStateDir string
}

ExecInput defines the inputs required for worker process execution.

type ExecResult

type ExecResult struct {
	ExitCode   int
	TimedOut   bool
	StdoutPath string
	StderrPath string
	Duration   time.Duration
	Error      error
}

ExecResult captures the worker process execution results.

func ExecuteWorker

func ExecuteWorker(input ExecInput) (ExecResult, error)

ExecuteWorker runs a worker process with timeout and log capture.

func ExecuteWorkerFromConfig

func ExecuteWorkerFromConfig(cfg config.Config, task index.Task, stageResult StageResult, workDir string, warn func(string)) (ExecResult, error)

ExecuteWorkerFromConfig executes a worker using configuration and staging results.

func ExecuteWorkerFromConfigWithAudit

func ExecuteWorkerFromConfigWithAudit(cfg config.Config, task index.Task, stageResult StageResult, workDir string, warn func(string), auditLogger AuditLogger, worktreePath string) (ExecResult, error)

ExecuteWorkerFromConfigWithAudit executes a worker using configuration and staging results with audit logging.

type ExitStatus

type ExitStatus struct {
	ExitCode       int       `json:"exit_code"`
	FinishedAt     time.Time `json:"finished_at"`
	PID            int       `json:"pid,omitempty"`
	DurationMs     int64     `json:"duration_ms,omitempty"`     // Wall time in milliseconds
	TokensPrompt   int       `json:"tokens_prompt,omitempty"`   // Input tokens consumed
	TokensResponse int       `json:"tokens_response,omitempty"` // Output tokens generated
	TokensTotal    int       `json:"tokens_total,omitempty"`    // Total tokens (prompt + response)
}

ExitStatus records the terminal status of a worker process.

func ReadExitStatus

func ReadExitStatus(workerStateDir string, taskID string, stage roles.Stage) (ExitStatus, bool, error)

ReadExitStatus reads the exit status file if present.

type IngestInput

type IngestInput struct {
	TaskID       string
	WorktreePath string
	Stage        roles.Stage
	ExecResult   ExecResult
	ExitStatus   *ExitStatus // Optional: exit status from exit.json for metrics tracking
	Warn         func(string)
}

IngestInput defines the inputs required for worker result ingestion.

type IngestResult

type IngestResult struct {
	Success      bool
	NewState     index.TaskState
	BlockReason  string
	TimedOut     bool // TimedOut reports whether the worker execution timed out.
	HasCommit    bool
	HasMarker    bool
	MarkerPath   string
	MarkerExists bool
	Metrics      index.ExecutionMetrics // Metrics captured from this execution stage
}

IngestResult captures the worker result ingestion outcome.

func CompletionResultToIngest

func CompletionResultToIngest(taskID string, stage roles.Stage, completion StageCompletion) (IngestResult, error)

CompletionResultToIngest builds an ingest result from completion data.

func IngestWorkerResult

func IngestWorkerResult(input IngestInput) (IngestResult, error)

IngestWorkerResult processes worker execution results and determines task state changes.

type StageCompletion

type StageCompletion struct {
	Completed   bool
	HasCommit   bool
	HasMarker   bool
	MarkerPath  string
	MarkerFound bool
}

StageCompletion captures marker and commit checks for a stage.

func CheckStageCompletion

func CheckStageCompletion(worktreePath string, workerStateDir string, stage roles.Stage) (StageCompletion, error)

CheckStageCompletion inspects the worktree to determine whether a stage completed.

type StageInput

type StageInput struct {
	RepoRoot        string
	WorktreeRoot    string
	Task            index.Task
	TaskPromptPath  string
	ExtraPromptPath []string
	ExtraEnv        map[string]string
	Stage           roles.Stage
	Role            index.Role
	ReasoningEffort string
	AgentUsesCodex  bool
	Warn            func(string)
	WorkerStateDir  string
}

StageInput defines the inputs required to stage worker prompts and environment.

type StageResult

type StageResult struct {
	PromptPath      string
	PromptFiles     []string
	PromptListPath  string
	EnvPath         string
	Env             map[string]string
	WorkerStateDir  string
	ReasoningEffort string
}

StageResult captures staged prompt and environment artifacts.

func StageEnvAndPrompts

func StageEnvAndPrompts(input StageInput) (StageResult, error)

StageEnvAndPrompts prepares worker prompt and environment staging artifacts.