Documentation
¶
Overview ¶
Package swarm provides types and management for multi-agent swarms.
Index ¶
- Variables
- type GitAuditResult
- type LandingConfig
- type LandingResult
- type Manager
- func (m *Manager) AbortMerge() error
- func (m *Manager) CleanupBranches(swarmID string) error
- func (m *Manager) CreateIntegrationBranch(swarmID string) error
- func (m *Manager) ExecuteLanding(swarmID string, config LandingConfig) (*LandingResult, error)
- func (m *Manager) GetIntegrationBranch(swarmID string) (string, error)
- func (m *Manager) GetReadyTasks(swarmID string) ([]SwarmTask, error)
- func (m *Manager) GetSwarm(id string) (*Swarm, error)
- func (m *Manager) GetWorkerBranch(swarmID, worker, taskID string) string
- func (m *Manager) IsComplete(swarmID string) (bool, error)
- func (m *Manager) LandToMain(swarmID string) error
- func (m *Manager) LoadSwarm(epicID string) (*Swarm, error)
- func (m *Manager) MergeToIntegration(swarmID, workerBranch string) error
- type Swarm
- type SwarmState
- type SwarmSummary
- type SwarmTask
- type TaskState
Constants ¶
This section is empty.
Variables ¶
var ( ErrBranchExists = errors.New("branch already exists") ErrBranchNotFound = errors.New("branch not found") ErrMergeConflict = errors.New("merge conflict") ErrNotOnIntegration = errors.New("not on integration branch") )
Integration branch errors
var ( ErrSwarmNotFound = errors.New("swarm not found") ErrSwarmExists = errors.New("swarm already exists") ErrInvalidState = errors.New("invalid state transition") ErrNoReadyTasks = errors.New("no ready tasks") ErrBeadsNotFound = errors.New("beads not available") )
Common errors
Functions ¶
This section is empty.
Types ¶
type GitAuditResult ¶
type GitAuditResult struct {
Worker string
ClonePath string
HasUncommitted bool
HasUnpushed bool
HasStashes bool
BeadsOnly bool // True if changes are only in .beads/
CodeAtRisk bool
Details string
}
GitAuditResult contains the result of a git safety audit.
type LandingConfig ¶
type LandingConfig struct {
// TownRoot is the workspace root for mail routing.
TownRoot string
// ForceKill kills sessions without graceful shutdown.
ForceKill bool
// SkipGitAudit skips the git safety audit.
SkipGitAudit bool
}
LandingConfig configures the landing protocol.
type LandingResult ¶
type LandingResult struct {
SwarmID string
Success bool
Error string
SessionsStopped int
BranchesCleaned int
PolecatsAtRisk []string
}
LandingResult contains the result of a landing operation.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager handles swarm lifecycle operations. Manager is stateless - all swarm state is discovered from beads.
func NewManager ¶
NewManager creates a new swarm manager for a rig.
func (*Manager) AbortMerge ¶
AbortMerge aborts an in-progress merge.
func (*Manager) CleanupBranches ¶
CleanupBranches removes all branches associated with a swarm.
func (*Manager) CreateIntegrationBranch ¶
CreateIntegrationBranch creates the integration branch for a swarm. The branch is created from the swarm's BaseCommit and pushed to origin.
func (*Manager) ExecuteLanding ¶
func (m *Manager) ExecuteLanding(swarmID string, config LandingConfig) (*LandingResult, error)
ExecuteLanding performs the witness landing protocol for a swarm.
func (*Manager) GetIntegrationBranch ¶
GetIntegrationBranch returns the integration branch name for a swarm.
func (*Manager) GetReadyTasks ¶
GetReadyTasks returns tasks ready to be assigned by querying beads.
func (*Manager) GetSwarm ¶
GetSwarm loads a swarm from beads. Alias for LoadSwarm for compatibility.
func (*Manager) GetWorkerBranch ¶
GetWorkerBranch generates the branch name for a worker on a task.
func (*Manager) IsComplete ¶
IsComplete checks if all tasks are closed by querying beads.
func (*Manager) LandToMain ¶
LandToMain merges the integration branch to the target branch (usually main).
func (*Manager) LoadSwarm ¶
LoadSwarm loads swarm state from beads by querying the epic. This is the canonical way to get swarm state - no in-memory caching.
func (*Manager) MergeToIntegration ¶
MergeToIntegration merges a worker branch into the integration branch. Returns ErrMergeConflict if the merge has conflicts.
type Swarm ¶
type Swarm struct {
// ID is the unique swarm identifier (matches beads epic ID).
ID string `json:"id"`
// RigName is the rig this swarm operates in.
RigName string `json:"rig_name"`
// EpicID is the beads epic tracking this swarm's work.
EpicID string `json:"epic_id"`
// BaseCommit is the git SHA all workers branch from.
BaseCommit string `json:"base_commit"`
// Integration is the integration branch name for merging work.
Integration string `json:"integration"`
// TargetBranch is the branch to merge into when complete (e.g., "main").
TargetBranch string `json:"target_branch"`
// State is the current lifecycle state.
State SwarmState `json:"state"`
// CreatedAt is when the swarm was created.
CreatedAt time.Time `json:"created_at"`
// UpdatedAt is when the swarm was last updated.
UpdatedAt time.Time `json:"updated_at"`
// Workers is the list of polecat names assigned to this swarm.
Workers []string `json:"workers"`
// Tasks is the list of tasks in this swarm.
Tasks []SwarmTask `json:"tasks"`
// Error contains error details if State is SwarmFailed.
Error string `json:"error,omitempty"`
}
Swarm represents a coordinated multi-agent work unit. The swarm references a beads epic that tracks all swarm work.
func (*Swarm) Summary ¶
func (s *Swarm) Summary() SwarmSummary
Summary returns a SwarmSummary for this swarm.
type SwarmState ¶
type SwarmState string
SwarmState represents the lifecycle state of a swarm.
const ( // SwarmCreated is the initial state after swarm creation. SwarmCreated SwarmState = "created" // SwarmActive means workers are actively working on tasks. SwarmActive SwarmState = "active" // SwarmMerging means all work is done and merging is in progress. SwarmMerging SwarmState = "merging" // SwarmLanded means all work has been merged to the target branch. SwarmLanded SwarmState = "landed" // SwarmFailed means the swarm failed and cannot be recovered. SwarmFailed SwarmState = "failed" // SwarmCanceled means the swarm was explicitly canceled. SwarmCanceled SwarmState = "canceled" )
func (SwarmState) IsActive ¶
func (s SwarmState) IsActive() bool
IsActive returns true if the swarm is actively running.
func (SwarmState) IsTerminal ¶
func (s SwarmState) IsTerminal() bool
IsTerminal returns true if the swarm is in a terminal state.
type SwarmSummary ¶
type SwarmSummary struct {
ID string `json:"id"`
State SwarmState `json:"state"`
TotalTasks int `json:"total_tasks"`
PendingTasks int `json:"pending_tasks"`
ActiveTasks int `json:"active_tasks"`
MergedTasks int `json:"merged_tasks"`
FailedTasks int `json:"failed_tasks"`
WorkerCount int `json:"worker_count"`
}
SwarmSummary provides a high-level overview of swarm progress.
type SwarmTask ¶
type SwarmTask struct {
// IssueID is the beads issue ID for this task.
IssueID string `json:"issue_id"`
// Title is the task title (copied from beads issue).
Title string `json:"title"`
// Assignee is the polecat name working on this task.
Assignee string `json:"assignee,omitempty"`
// Branch is the worker's branch name for this task.
Branch string `json:"branch,omitempty"`
// State mirrors the beads issue status.
State TaskState `json:"state"`
// MergedAt is when the task branch was merged (if merged).
MergedAt *time.Time `json:"merged_at,omitempty"`
}
SwarmTask represents a single task in the swarm. Each task maps to a beads issue and is assigned to a worker.
type TaskState ¶
type TaskState string
TaskState represents the state of a swarm task.
const ( // TaskPending means the task is not yet started. TaskPending TaskState = "pending" // TaskAssigned means the task is assigned but not started. TaskAssigned TaskState = "assigned" // TaskInProgress means the task is actively being worked on. TaskInProgress TaskState = "in_progress" // TaskReview means the task is ready for review/merge. TaskReview TaskState = "review" // TaskMerged means the task has been merged. TaskMerged TaskState = "merged" // TaskFailed means the task failed. TaskFailed TaskState = "failed" )
func (TaskState) IsComplete ¶
IsComplete returns true if the task is in a terminal state.