Documentation
¶
Index ¶
- Constants
- type AgentConfig
- func FindAgent(result *AgentDiscoveryResult, name string) (AgentConfig, bool)
- func LoadAgentsFromDir(dir string) ([]AgentConfig, error)
- func LoadBundledAgents() ([]AgentConfig, error)
- func ParseAgentFile(path string) (AgentConfig, error)
- func ParseAgentFileFromFS(fsys fs.FS, path string) (AgentConfig, error)
- type AgentDiscoveryResult
- type AgentInput
- type AgentOutput
- type AgentScope
- type AgentStatus
- type Event
- type Orchestrator
- func (o *Orchestrator) Cancel(agentID string) error
- func (o *Orchestrator) List() []AgentStatus
- func (o *Orchestrator) Shutdown()
- func (o *Orchestrator) Spawn(ctx context.Context, input SpawnInput) (<-chan Event, string, error)
- func (o *Orchestrator) SpawnWithInput(ctx context.Context, input AgentInput) (<-chan Event, string, error)
- func (o *Orchestrator) Worktree() *WorktreeManager
- type Pool
- type Process
- type SpawnInput
- type SpawnOpts
- type Spawner
- type WorktreeManager
- func (m *WorktreeManager) Active() int
- func (m *WorktreeManager) Cleanup(agentID string) error
- func (m *WorktreeManager) CleanupAll() error
- func (m *WorktreeManager) Create(agentID string) (string, error)
- func (m *WorktreeManager) MergeBack(agentID string) (string, error)
- func (m *WorktreeManager) PathFor(agentID string) string
Constants ¶
const DefaultPoolSize = 5
DefaultPoolSize is the default maximum number of concurrent subagents.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentConfig ¶ added in v0.0.4
type AgentConfig struct {
Name string // Agent identifier (e.g., "explore", "plan")
Description string // One-line description from frontmatter
Role string // Config role name for model resolution (e.g., "smol", "plan", "slow")
Worktree bool // Whether this agent runs in an isolated git worktree
Instruction string // System prompt (markdown body)
Tools []string // Allowed tool names (empty = all tools)
Source string // "bundled", "user", or "project"
}
AgentConfig represents a parsed agent definition from markdown.
func FindAgent ¶ added in v0.0.4
func FindAgent(result *AgentDiscoveryResult, name string) (AgentConfig, bool)
FindAgent looks up an agent by name from a discovery result.
func LoadAgentsFromDir ¶ added in v0.0.4
func LoadAgentsFromDir(dir string) ([]AgentConfig, error)
LoadAgentsFromDir loads all agent markdown files from a directory. Returns empty slice if directory doesn't exist (not an error).
func LoadBundledAgents ¶ added in v0.0.5
func LoadBundledAgents() ([]AgentConfig, error)
LoadBundledAgents loads all embedded agent definitions. Returns agents with Source set to "bundled".
func ParseAgentFile ¶ added in v0.0.4
func ParseAgentFile(path string) (AgentConfig, error)
ParseAgentFile parses a single agent markdown file. Expected format: --- name: agent-name description: One-line description role: smol worktree: false tools: read, write, edit --- Markdown instruction body...
func ParseAgentFileFromFS ¶ added in v0.0.5
func ParseAgentFileFromFS(fsys fs.FS, path string) (AgentConfig, error)
ParseAgentFileFromFS parses an agent file from an embedded filesystem.
type AgentDiscoveryResult ¶ added in v0.0.4
type AgentDiscoveryResult struct {
Bundled []AgentConfig
User []AgentConfig
Project []AgentConfig
All []AgentConfig // Merged with priority: project > user > bundled
}
AgentDiscoveryResult contains all discovered agents.
func DiscoverAgents ¶ added in v0.0.4
func DiscoverAgents(cwd string, scope AgentScope) (*AgentDiscoveryResult, error)
DiscoverAgents loads agents from bundled, user, and project directories. Priority: project > user > bundled (later sources override earlier ones by name).
type AgentInput ¶
type AgentInput struct {
Type string `json:"type"` // Agent type name
Prompt string `json:"prompt"` // Task prompt for the agent
Worktree *bool `json:"worktree,omitempty"` // Override worktree setting
WorkDir string `json:"work_dir,omitempty"` // Override working directory (e.g. existing worktree path)
Background bool `json:"background,omitempty"` // Run in background
SkipCleanup bool `json:"skip_cleanup,omitempty"` // Don't auto-cleanup worktree on completion
}
AgentInput is the legacy input to spawn a subagent (deprecated, use SpawnInput). It is kept for backward compatibility with existing callers. Convert to SpawnInput using ToSpawnInput() which looks up the bundled agent.
func (AgentInput) ToSpawnInput ¶ added in v0.0.5
func (a AgentInput) ToSpawnInput() (SpawnInput, error)
ToSpawnInput converts a legacy AgentInput to the new SpawnInput format. It looks up the agent config from bundled agents.
type AgentOutput ¶
type AgentOutput struct {
AgentID string `json:"agent_id"`
Type string `json:"type"`
Result string `json:"result"`
Error string `json:"error,omitempty"`
Duration string `json:"duration"`
}
AgentOutput is the result of a completed subagent.
type AgentScope ¶ added in v0.0.4
type AgentScope string
AgentScope defines the scope for agent discovery.
const ( ScopeBoth AgentScope = "both" // Bundled + user/project ScopeBundled AgentScope = "bundled" // Only embedded agents ScopeProject AgentScope = "project" // Only user/project agents )
type AgentStatus ¶
type AgentStatus struct {
AgentID string `json:"agent_id"`
Type string `json:"type"`
Status string `json:"status"` // "running", "completed", "failed", "cancelled"
Prompt string `json:"prompt"`
StartedAt time.Time `json:"started_at"`
Duration string `json:"duration,omitempty"`
}
AgentStatus represents the current state of a subagent.
type Event ¶
type Event struct {
Type string `json:"type"` // "text_delta", "tool_call", "tool_result", "message_end", "error"
Content string `json:"content,omitempty"` // Text content for text_delta
Error string `json:"error,omitempty"` // Error message for error events
}
Event is a streaming event from a subagent process.
type Orchestrator ¶
type Orchestrator struct {
// contains filtered or unexported fields
}
Orchestrator composes Pool, Spawner, and WorktreeManager to manage subagent lifecycle.
func NewOrchestrator ¶
func NewOrchestrator(cfg *config.Config, repoRoot string) *Orchestrator
NewOrchestrator creates an Orchestrator from config. repoRoot is the git repository root (empty string disables worktree support).
func (*Orchestrator) Cancel ¶
func (o *Orchestrator) Cancel(agentID string) error
Cancel cancels a running agent by ID.
func (*Orchestrator) List ¶
func (o *Orchestrator) List() []AgentStatus
List returns the status of all tracked agents.
func (*Orchestrator) Shutdown ¶
func (o *Orchestrator) Shutdown()
Shutdown cancels all running agents and cleans up worktrees.
func (*Orchestrator) Spawn ¶
func (o *Orchestrator) Spawn(ctx context.Context, input SpawnInput) (<-chan Event, string, error)
Spawn starts a new subagent and returns an event channel. It acquires a pool slot, optionally creates a worktree, and spawns the pi process.
func (*Orchestrator) SpawnWithInput ¶ added in v0.0.5
func (o *Orchestrator) SpawnWithInput(ctx context.Context, input AgentInput) (<-chan Event, string, error)
SpawnWithInput is the legacy method that accepts AgentInput for backward compatibility. It converts the input to SpawnInput and calls Spawn. Deprecated: Use Spawn with SpawnInput directly.
func (*Orchestrator) Worktree ¶
func (o *Orchestrator) Worktree() *WorktreeManager
Worktree returns the WorktreeManager (may be nil if worktrees are disabled).
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool manages concurrency for subagent processes using a buffered channel semaphore.
type Process ¶
type Process struct {
// contains filtered or unexported fields
}
Process represents a running subagent pi process.
type SpawnInput ¶ added in v0.0.5
type SpawnInput struct {
Agent AgentConfig `json:"agent"` // Agent configuration
Prompt string `json:"prompt"` // Task prompt for the agent
Worktree *bool `json:"worktree,omitempty"` // Override worktree setting
WorkDir string `json:"work_dir,omitempty"` // Override working directory (e.g. existing worktree path)
Background bool `json:"background,omitempty"` // Run in background
SkipCleanup bool `json:"skip_cleanup,omitempty"` // Don't auto-cleanup worktree on completion
}
SpawnInput is the input to spawn a subagent with an AgentConfig.
type SpawnOpts ¶
type SpawnOpts struct {
AgentID string // Unique ID for this agent
Model string // Model name to use
WorkDir string // Working directory for the process
Prompt string // Task prompt to send
Instruction string // System instruction for the subagent
}
SpawnOpts holds options for spawning a subagent process.
type Spawner ¶
type Spawner struct {
// PiBinary is the path to the pi binary. Defaults to "pi" (from PATH).
PiBinary string
}
Spawner creates and manages subagent pi processes.
func NewSpawner ¶
NewSpawner creates a new Spawner. If piBinary is empty, uses "pi" from PATH.
type WorktreeManager ¶
type WorktreeManager struct {
// contains filtered or unexported fields
}
WorktreeManager manages git worktrees for isolated subagent execution.
func NewWorktreeManager ¶
func NewWorktreeManager(repoRoot string) *WorktreeManager
NewWorktreeManager creates a new WorktreeManager rooted at the given git repo.
func (*WorktreeManager) Active ¶
func (m *WorktreeManager) Active() int
Active returns the number of active worktrees.
func (*WorktreeManager) Cleanup ¶
func (m *WorktreeManager) Cleanup(agentID string) error
Cleanup removes the worktree and branch for the given agent ID. After CleanupAll has started (closed=true), late Cleanup calls are no-ops — CleanupAll owns all remaining entries at that point.
func (*WorktreeManager) CleanupAll ¶
func (m *WorktreeManager) CleanupAll() error
CleanupAll removes all active worktrees. Used during shutdown. It sets the closed flag to reject late Cleanup calls from completion goroutines, waits for in-flight cleanups, then retries remaining entries up to maxPasses.
func (*WorktreeManager) Create ¶
func (m *WorktreeManager) Create(agentID string) (string, error)
Create creates a new git worktree for the given agent ID. Returns the filesystem path to the worktree.
func (*WorktreeManager) MergeBack ¶
func (m *WorktreeManager) MergeBack(agentID string) (string, error)
MergeBack merges the worktree branch back into the current branch of the main worktree. Returns the merge output.
func (*WorktreeManager) PathFor ¶
func (m *WorktreeManager) PathFor(agentID string) string
PathFor returns the worktree path for the given agent ID, or empty string if none.