orchestrator

Documentation

Overview

Package orchestrator coordinates AI agents working on tasks. Implements the plan-implement-review loop for task execution.

Index

• Constants
• func CurrentBranch(ctx context.Context, workDir string) (string, error)
• func ExtractPRURL(text string) string
• func ParseMetadataBlock(body string) map[string]string
• type Config
  • func DefaultConfig() Config
• type Event
• type EventHandler
• type EventType
• type ImplementOutput
• type LogEntry
• type Option
  • func WithAgent(a agents.Agent) Option
  • func WithBudget(b *budget.Tracker) Option
  • func WithConfig(c Config) Option
  • func WithEventHandler(h EventHandler) Option
  • func WithLogger(l *logging.Logger) Option
  • func WithQueue(q *tasks.Queue) Option
• type Orchestrator
  • func New(opts ...Option) *Orchestrator
  • func (o *Orchestrator) PlanPrompt(task *tasks.Task) string
  • func (o *Orchestrator) Run(ctx context.Context) error
  • func (o *Orchestrator) RunTask(ctx context.Context, task *tasks.Task, workDir string) (*TaskResult, error)
  • func (o *Orchestrator) SetRunMetadata(m *RunMetadata)
• type PlanOutput
• type ReviewOutput
• type RunMetadata
• type TaskResult
• type TaskStatus

Constants

const (
	DefaultMaxIterations = 3
	DefaultAgentTimeout  = 30 * time.Minute
)

Constants for orchestration.

Functions

func CurrentBranch

func CurrentBranch(ctx context.Context, workDir string) (string, error)

CurrentBranch resolves the current git branch in the given directory. Returns an error if the directory is not inside a git repository.

func ExtractPRURL

func ExtractPRURL(text string) string

ExtractPRURL scans text for GitHub PR URLs and returns the last match. Returns empty string if no PR URL is found.

func ParseMetadataBlock

func ParseMetadataBlock(body string) map[string]string

ParseMetadataBlock extracts key-value pairs from a nightshift metadata comment embedded in a PR body. Returns nil if the block is not found or is malformed.

Types

type Config

type Config struct {
	MaxIterations int           // Max review iterations (default: 3)
	AgentTimeout  time.Duration // Per-agent timeout (default: 30min)
	WorkDir       string        // Working directory for agents
}

Config holds orchestrator configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns default orchestrator config.

type Event

type Event struct {
	Type      EventType
	Time      time.Time
	Phase     TaskStatus // which phase: StatusPlanning, StatusExecuting, StatusReviewing
	Iteration int        // current iteration (1-based)
	MaxIter   int        // max iterations configured
	TaskID    string
	TaskTitle string
	Message   string         // human-readable message
	Level     string         // "info", "warn", "error"
	Fields    map[string]any // structured fields
	Status    TaskStatus     // for EventTaskEnd: final status
	Duration  time.Duration  // for EventPhaseEnd/EventTaskEnd: elapsed time
	Error     string         // error message if applicable
}

Event carries data about an orchestrator lifecycle event.

type EventHandler

type EventHandler func(Event)

EventHandler is a callback that receives orchestrator events.

type EventType

type EventType int

EventType classifies orchestrator lifecycle events.

const (
	EventTaskStart      EventType = iota // task execution begins
	EventPhaseStart                      // entering a phase (plan/implement/review)
	EventPhaseEnd                        // phase completed
	EventIterationStart                  // new iteration of the implement-review loop
	EventLog                             // internal log message
	EventTaskEnd                         // task execution finished
)

type ImplementOutput

type ImplementOutput struct {
	FilesModified []string `json:"files_modified"`
	Summary       string   `json:"summary"`
	Raw           string   `json:"raw,omitempty"`
}

ImplementOutput represents structured output from implement agent.

type LogEntry

type LogEntry struct {
	Time    time.Time      `json:"time"`
	Level   string         `json:"level"`
	Message string         `json:"message"`
	Fields  map[string]any `json:"fields,omitempty"`
}

LogEntry captures a timestamped log message.

type Option

type Option func(*Orchestrator)

Option configures an Orchestrator.

func WithAgent

func WithAgent(a agents.Agent) Option

WithAgent sets the agent for task execution.

func WithBudget

func WithBudget(b *budget.Tracker) Option

WithBudget sets the budget tracker.

func WithConfig

func WithConfig(c Config) Option

WithConfig sets orchestrator configuration.

func WithEventHandler

func WithEventHandler(h EventHandler) Option

WithEventHandler sets an optional callback for real-time orchestrator events.

func WithLogger

func WithLogger(l *logging.Logger) Option

WithLogger sets the logger.

func WithQueue

func WithQueue(q *tasks.Queue) Option

WithQueue sets the task queue.

type Orchestrator

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

Orchestrator manages agent execution using plan-implement-review loop.

func New

func New(opts ...Option) *Orchestrator

New creates an orchestrator with the given options.

func (*Orchestrator) PlanPrompt

func (o *Orchestrator) PlanPrompt(task *tasks.Task) string

PlanPrompt returns the planning prompt for a task.

func (*Orchestrator) Run

func (o *Orchestrator) Run(ctx context.Context) error

Run processes all tasks in queue until empty or budget exhausted.

func (*Orchestrator) RunTask

func (o *Orchestrator) RunTask(ctx context.Context, task *tasks.Task, workDir string) (*TaskResult, error)

RunTask executes a single task through the plan-implement-review loop.

func (*Orchestrator) SetRunMetadata

func (o *Orchestrator) SetRunMetadata(m *RunMetadata)

SetRunMetadata sets the metadata to inject into PRs for the next task.

type PlanOutput

type PlanOutput struct {
	Steps       []string `json:"steps"`
	Files       []string `json:"files"`
	Description string   `json:"description"`
	Raw         string   `json:"raw,omitempty"`
}

PlanOutput represents structured plan from the plan agent.

type ReviewOutput

type ReviewOutput struct {
	Passed   bool     `json:"passed"`
	Feedback string   `json:"feedback"`
	Issues   []string `json:"issues,omitempty"`
	Raw      string   `json:"raw,omitempty"`
}

ReviewOutput represents structured output from review agent.

type RunMetadata

type RunMetadata struct {
	Provider  string
	TaskType  string
	TaskScore float64
	CostTier  string
	RunStart  time.Time
	Branch    string // base branch for feature branches
}

RunMetadata holds provenance information about a nightshift run, injected into PRs for traceability.

type TaskResult

type TaskResult struct {
	TaskID     string        `json:"task_id"`
	Status     TaskStatus    `json:"status"`
	Iterations int           `json:"iterations"`
	Plan       *PlanOutput   `json:"plan,omitempty"`
	Output     string        `json:"output,omitempty"`
	OutputType string        `json:"output_type,omitempty"` // e.g. "PR"
	OutputRef  string        `json:"output_ref,omitempty"`  // e.g. PR URL
	Error      string        `json:"error,omitempty"`
	Duration   time.Duration `json:"duration"`
	Logs       []LogEntry    `json:"logs"`
}

TaskResult holds the outcome of orchestrating a task.

type TaskStatus

type TaskStatus string

TaskStatus represents the outcome of task execution.

const (
	StatusPending   TaskStatus = "pending"
	StatusPlanning  TaskStatus = "planning"
	StatusExecuting TaskStatus = "executing"
	StatusReviewing TaskStatus = "reviewing"
	StatusCompleted TaskStatus = "completed"
	StatusFailed    TaskStatus = "failed"
	StatusAbandoned TaskStatus = "abandoned"
)