agent

Documentation

Overview

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

Index

• Constants
• Variables
• func FilterToolsForMode(mode SubAgentMode, available []string) []string
• func FormatResults(results []BackgroundResult) string
• type BackgroundAgentPool
  • func NewBackgroundAgentPool() *BackgroundAgentPool
  • func (p *BackgroundAgentPool) AllResults() []BackgroundResult
  • func (p *BackgroundAgentPool) ClearResults()
  • func (p *BackgroundAgentPool) Collect() []BackgroundResult
  • func (p *BackgroundAgentPool) HasPending() bool
  • func (p *BackgroundAgentPool) PendingCount() int
  • func (p *BackgroundAgentPool) Submit(id, prompt string, ...)
  • func (p *BackgroundAgentPool) WaitAll() []BackgroundResult
• type BackgroundResult
• type SubAgentBudget
  • func NewSubAgentBudget(mode SubAgentMode, cfg SubAgentConfig) *SubAgentBudget
  • func (b *SubAgentBudget) Remaining() int
  • func (b *SubAgentBudget) ShouldSynthesize() bool
  • func (b *SubAgentBudget) Tick()
• type SubAgentConfig
  • func DefaultSubAgentConfig() SubAgentConfig
• type SubAgentMode

Constants

const (
	DefaultExploreTurns = 15
	DefaultGeneralTurns = 20
	MaxAgentDepth       = 2
)

Sub-agent budget defaults per mode.

Variables

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

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

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.

Functions

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.

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 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"
)