Help us shape the future of Go! Take the 2026 Go Developer Survey

orchestrator

package
v2.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package orchestrator coordinates multiple agent runners and model routing.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentRunner

type AgentRunner interface {
	RunGoal(ctx context.Context, goal string) (string, error)
}

AgentRunner is the interface the orchestrator uses to execute a goal. The real implementation wraps agent.Runner; tests supply fakes.

type Approval

type Approval int

Approval is how the lanes answer a tool call the permission policy resolves to Ask. Spec §4 F2: the orchestrator inherits its caller's Gate.

const (
	// ApprovalDeny is the headless default: no caller prompt, so Asks are
	// denied. Run says so in an event and records it in Result.Approval.
	ApprovalDeny Approval = iota
	// ApprovalPrompt asks the caller's prompt (the TUI's permission modal).
	ApprovalPrompt
)

func (Approval) String

func (a Approval) String() string

type DebateManager

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

DebateManager tracks debate turns and produces a verdict.

func NewDebateManager

func NewDebateManager(opts DebateOptions) *DebateManager

NewDebateManager creates a DebateManager with the given options.

func (*DebateManager) AddTurn

func (d *DebateManager) AddTurn(turn DebateTurn)

AddTurn appends a turn to the debate.

func (*DebateManager) RoundsCompleted

func (d *DebateManager) RoundsCompleted() int

RoundsCompleted returns the number of full rounds (reviewer + primary) completed.

func (*DebateManager) Verdict

func (d *DebateManager) Verdict(issues []Issue) DebateResult

Verdict produces a DebateResult from the given open issues.

type DebateOptions

type DebateOptions struct {
	MaxRounds int // default 3
}

DebateOptions configures a DebateManager.

type DebateResult

type DebateResult struct {
	Kind   VerdictKind
	Issues []Issue
	Score  float64 // 0.0–1.0; higher = cleaner code
}

DebateResult is the final outcome of all debate rounds.

type DebateRole

type DebateRole int

DebateRole identifies which side is speaking in a review debate.

const (
	RoleReviewer DebateRole = iota
	RolePrimary
)

type DebateTurn

type DebateTurn struct {
	Round  int
	Role   DebateRole
	Input  string
	Output string
}

DebateTurn is one side's contribution to a debate round.

type EventKind

type EventKind int

EventKind identifies the type of an OrchestratorEvent.

const (
	EventClassified  EventKind = iota // goal classified into a task lane
	EventAction                       // agent took a discrete action
	EventToolCall                     // agent called a tool
	EventFileDiff                     // agent wrote or modified a file
	EventReviewDraft                  // reviewer produced a critique
	EventDefense                      // primary agent responded to critique
	EventVerdict                      // reviewer issued a final verdict
	EventComplete                     // orchestrator run finished
	EventError                        // orchestrator run failed
	EventDebateStart                  // debate round beginning (carries round number and reviewer model)
)

type Issue

type Issue struct {
	File        string
	Line        int
	Severity    string // "low", "medium", "high"
	Description string
}

Issue is a code issue raised by the reviewer.

type ModelAssignment

type ModelAssignment struct {
	Primary         string
	PrimaryBaseURL  string
	PrimaryAPIKey   string
	Reviewer        string
	ReviewerBaseURL string
	ReviewerAPIKey  string
	// Notes say which retired models were replaced.
	Notes []string
}

ModelAssignment describes which models to use for a given run. Per-role BaseURL and APIKey allow cross-provider orchestration.

func (ModelAssignment) HasReviewer

func (m ModelAssignment) HasReviewer() bool

HasReviewer returns true when a non-blank reviewer model is assigned.

type Option

type Option func(*Orchestrator)

Option configures an Orchestrator.

func WithPrompt

func WithPrompt(fn tools.PromptFunc) Option

WithPrompt makes the lanes ask fn (the TUI's permission modal) for tools the policy resolves to Ask. A nil fn keeps the headless default.

func WithRunnerFactory

func WithRunnerFactory(f RunnerFactory) Option

WithRunnerFactory overrides the AgentRunner factory (useful in tests).

type Orchestrator

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

Orchestrator manages multi-model agent execution.

func New

func New(cfg *config.Config, opts ...Option) *Orchestrator

New creates an Orchestrator backed by the given config.

func (*Orchestrator) OnEvent

func (o *Orchestrator) OnEvent(fn func(OrchestratorEvent))

OnEvent registers a callback for all orchestrator events. Safe to call at any time. Events are delivered one at a time, under a lock: fn must not call back into the Orchestrator.

func (*Orchestrator) Run

func (orch *Orchestrator) Run(ctx context.Context, goal string) (*Result, error)

Run classifies the goal, routes to models, executes the primary agent, and optionally runs a reviewer debate. Every real lane of the run nests under one environment (loop.Parent). That environment is local to this call, so concurrent Runs never close each other's lanes, and it is closed before the terminal event (EventComplete or EventError), so nothing from it reaches a caller that stops reading there.

type OrchestratorEvent

type OrchestratorEvent struct {
	Kind         EventKind
	Lane         TaskLane
	Text         string        // human-readable description
	Model        string        // model name — non-empty where role matters (primary/reviewer)
	Duration     time.Duration // per-turn API call elapsed time (EventTurnStats)
	InputTokens  int           // prompt tokens for this turn
	OutputTokens int           // completion tokens for this turn
	Response     string        // full assistant response text for this turn (live code output)
	FilePath     string        // non-empty for EventFileDiff
	Diff         string        // unified diff content for EventFileDiff
	Turn         int
	MaxTurns     int
	Score        float64 // 0.0–1.0 for EventVerdict
	VerdictErr   string  // non-empty if verdict is Contested or NeedsWork
}

OrchestratorEvent is emitted by the orchestrator state machine.

type Result

type Result struct {
	Lane     TaskLane
	Primary  string        // final response from primary agent
	Verdict  *DebateResult // nil when no debate was run
	Approval Approval      // how the lanes answered tools that need approval
}

Result is the final output of an orchestrator run.

type Router

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

Router maps TaskLanes to ModelAssignments using the user's config.

func NewRouter

func NewRouter(cfg *config.Config) *Router

NewRouter creates a Router backed by the given config.

func (*Router) Resolve

func (r *Router) Resolve(ctx context.Context, lane TaskLane) (ModelAssignment, error)

Resolve returns the ModelAssignment for the given lane. Falls back to cfg.Model as primary with no reviewer when the lane is unconfigured. Each model is resolved against its own endpoint's catalog (the lane's base URL and key, else the config's), unless the config pins models; this may block on a catalog fetch, bounded by its timeout and by ctx (the run's: cancelling the run interrupts it).

type RunnerFactory

type RunnerFactory func(model string) AgentRunner

RunnerFactory creates an AgentRunner for the given model name.

type TaskLane

type TaskLane string

TaskLane identifies the type of task being performed.

const (
	LaneCode     TaskLane = "code"
	LaneContent  TaskLane = "content"
	LaneMedia    TaskLane = "media"
	LaneReview   TaskLane = "review"
	LaneResearch TaskLane = "research"
	LaneUnknown  TaskLane = "unknown"
)

func Classify

func Classify(ctx context.Context, goal, mode string, logf func(string)) (lane TaskLane, confidence float64, note string)

Classify picks the goal's lane (2.0 W3, jev_route). "on": a Jev choice question decides, falling back to the keyword heuristic on any error; "shadow": the heuristic decides and note says what Jev would pick; off: the heuristic alone. note is "" when there is nothing to add.

func ClassifyHeuristic

func ClassifyHeuristic(goal string) (TaskLane, float64)

ClassifyHeuristic returns the best-guess TaskLane and a confidence score (0.0–1.0) based purely on keyword matching. Confidence < 0.5 means the goal is ambiguous.

type VerdictKind

type VerdictKind int

VerdictKind is the outcome of a review debate.

const (
	VerdictApproved VerdictKind = iota
	VerdictNeedsWork
	VerdictContested
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL