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 ¶
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.
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 ¶
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 (*Router) Resolve ¶
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.
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 ¶
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 )