agent

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jun 25, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package agent is the namespace for sub-agent orchestration types. See ../REFACTOR_PLAN.md.

Index

Constants

View Source 
const (
	DefaultExploreTurns = 15
	DefaultGeneralTurns = 20
	// DefaultPlanTurns is the turn budget for plan-mode sub-agents. Planning
	// benefits from broad read-only exploration before synthesis, so it sits
	// above explore but below a full general agent.
	DefaultPlanTurns = 18
	MaxAgentDepth    = 2
)

Sub-agent budget defaults per mode.

View Source 
const (
	ThoroughnessQuickTurns        = 8
	ThoroughnessMediumTurns       = 15
	ThoroughnessVeryThoroughTurns = 30
)

Per-thoroughness explore turn budgets. These are distinct so that callers can tune exploration depth without touching the default explore budget.

Variables

View Source 
var ExploreTools = []string{
	"Glob", "Grep", "Read", "Bash", "LS",
}

ExploreTools are the read-only tools available to explore-mode sub-agents.

View Source 
var ModeToolAllowlist = map[SubAgentMode][]string{
	SubAgentExplore: {
		"Read",
		"Grep",
		"Glob",
		"LS",
		"Bash",
	},
	SubAgentGeneral: {
		"Read",
		"Grep",
		"Glob",
		"LS",
		"Bash",
		"Write",
		"Edit",
		"Agent",
		"MultiAgent",
	},
}

ModeToolAllowlist maps each sub-agent mode to the tool names it can use. Explore mode is restricted to read-only tools; general mode has full access.

View Source 
var PlanTools = []string{
	"Glob", "Grep", "Read", "Bash", "LS",
}

PlanTools are the read-only tools available to plan-mode sub-agents. Planning is non-destructive, so it shares explore's read-only surface.

Functions

func DefaultTurnsForMode 

func DefaultTurnsForMode(mode SubAgentMode) int

DefaultTurnsForMode returns the default turn budget for a sub-agent mode. It is the single source of truth for mode->budget resolution and is used to wire new modes (such as plan) into the dispatch path.

func FilterToolsForMode 

func FilterToolsForMode(mode SubAgentMode, available []string) []string

FilterToolsForMode returns only the tool names from available that are permitted for the given mode. Tools not in the allowlist are excluded.

func FormatResults 

func FormatResults(results []BackgroundResult) string

FormatResults formats background results for injection into the agent context.

func IsReadOnlyMode 

func IsReadOnlyMode(mode SubAgentMode) bool

IsReadOnlyMode reports whether a mode is restricted to read-only tools. Both explore and plan are non-destructive.

func ThoroughnessTurns 

func ThoroughnessTurns(t ExploreThoroughness) int

ThoroughnessTurns maps a thoroughness level to its explore turn budget. Unknown or empty levels return DefaultExploreTurns.

Types

type BackgroundAgentPool 

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

BackgroundAgentPool manages async sub-agents that run in the background. When background agents finish, their results are collected for re-injection into the main agent loop.

func NewBackgroundAgentPool 

func NewBackgroundAgentPool() *BackgroundAgentPool

NewBackgroundAgentPool creates a pool with configurable wait limits.

func (*BackgroundAgentPool) AllResults 

func (p *BackgroundAgentPool) AllResults() []BackgroundResult

AllResults returns all results collected so far (completed background tasks).

func (*BackgroundAgentPool) ClearResults 

func (p *BackgroundAgentPool) ClearResults()

ClearResults clears all collected results to free memory.

func (*BackgroundAgentPool) Collect 

func (p *BackgroundAgentPool) Collect() []BackgroundResult

Collect gathers all completed background results without blocking. Returns immediately with whatever results are available.

func (*BackgroundAgentPool) HasPending 

func (p *BackgroundAgentPool) HasPending() bool

HasPending returns true if background agents are still running.

func (*BackgroundAgentPool) PendingCount 

func (p *BackgroundAgentPool) PendingCount() int

PendingCount returns the number of in-flight background agents.

func (*BackgroundAgentPool) Submit 

func (p *BackgroundAgentPool) Submit(id, prompt string, spawn func(ctx context.Context, prompt string) (string, error))

Submit launches a background sub-agent. The spawn function runs asynchronously.

func (*BackgroundAgentPool) WaitAll 

func (p *BackgroundAgentPool) WaitAll() []BackgroundResult

WaitAll blocks until all pending tasks complete or timeout.

type BackgroundResult 

type BackgroundResult struct {
	ID      string
	Prompt  string
	Output  string
	Error   error
	Elapsed time.Duration
}

BackgroundResult holds the output of a completed background agent.

type ExploreConfig 

type ExploreConfig struct {
	Thoroughness ExploreThoroughness
}

ExploreConfig configures an explore-mode sub-agent. The zero value resolves to medium thoroughness via DefaultExploreConfig / Turns().

func DefaultExploreConfig 

func DefaultExploreConfig() ExploreConfig

DefaultExploreConfig returns the default explore configuration (medium).

func (ExploreConfig) Turns 

func (c ExploreConfig) Turns() int

Turns returns the turn budget for the configured thoroughness. Unknown or empty thoroughness values fall back to the default explore budget.

type ExploreThoroughness 

type ExploreThoroughness string

ExploreThoroughness controls how much turn budget an explore-mode sub-agent receives. Higher thoroughness trades latency/cost for more complete coverage. It mirrors Claude Code's explore thoroughness levels. 

const (
	ThoroughnessQuick        ExploreThoroughness = "quick"
	ThoroughnessMedium       ExploreThoroughness = "medium"
	ThoroughnessVeryThorough ExploreThoroughness = "very-thorough"
)

type SubAgentBudget 

type SubAgentBudget struct {
	Mode      SubAgentMode
	TurnsUsed int
	MaxTurns  int
}

SubAgentBudget tracks turn usage against a mode-derived limit.

func NewSubAgentBudget 

func NewSubAgentBudget(mode SubAgentMode, cfg SubAgentConfig) *SubAgentBudget

NewSubAgentBudget creates a budget tracker for the given mode and config.

func (*SubAgentBudget) Remaining 

func (b *SubAgentBudget) Remaining() int

Remaining returns how many turns are left before synthesis is triggered.

func (*SubAgentBudget) ShouldSynthesize 

func (b *SubAgentBudget) ShouldSynthesize() bool

ShouldSynthesize returns true when the sub-agent has exceeded its turn budget and should produce a final synthesis response instead of continuing tool use.

func (*SubAgentBudget) Tick 

func (b *SubAgentBudget) Tick()

Tick increments the turn counter by one.

type SubAgentConfig 

type SubAgentConfig struct {
	ExploreMaxTurns int // turn budget for explore-mode sub-agents
	GeneralMaxTurns int // turn budget for general-mode sub-agents
	MaxDepth        int // maximum nesting depth (1 = sub-agents cannot spawn children)
}

SubAgentConfig holds configuration for sub-agent budget and depth limits. Zero-value int fields receive defaults via DefaultSubAgentConfig().

func DefaultSubAgentConfig 

func DefaultSubAgentConfig() SubAgentConfig

DefaultSubAgentConfig returns a SubAgentConfig with sane production defaults.

type SubAgentMode 

type SubAgentMode string

SubAgentMode determines the capabilities and cost profile of a sub-agent. 

const (
	SubAgentExplore SubAgentMode = "explore"
	SubAgentGeneral SubAgentMode = "general"
	// SubAgentPlan is a read-only planning mode: it decomposes a task into
	// ordered, actionable steps without making changes. It mirrors Claude
	// Code's "plan" subagent. Like explore it is restricted to read-only
	// tools, but it gets a larger turn budget so it can reason over more
	// context before producing a plan.
	SubAgentPlan SubAgentMode = "plan"
)

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.