swarm

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Jan 22, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package swarm provides types and management for multi-agent swarms.

Index

Constants

This section is empty.

Variables

View Source
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

View Source
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

func NewManager(r *rig.Rig) *Manager

NewManager creates a new swarm manager for a rig.

func (*Manager) AbortMerge

func (m *Manager) AbortMerge() error

AbortMerge aborts an in-progress merge.

func (*Manager) CleanupBranches

func (m *Manager) CleanupBranches(swarmID string) error

CleanupBranches removes all branches associated with a swarm.

func (*Manager) CreateIntegrationBranch

func (m *Manager) CreateIntegrationBranch(swarmID string) error

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

func (m *Manager) GetIntegrationBranch(swarmID string) (string, error)

GetIntegrationBranch returns the integration branch name for a swarm.

func (*Manager) GetReadyTasks

func (m *Manager) GetReadyTasks(swarmID string) ([]SwarmTask, error)

GetReadyTasks returns tasks ready to be assigned by querying beads.

func (*Manager) GetSwarm

func (m *Manager) GetSwarm(id string) (*Swarm, error)

GetSwarm loads a swarm from beads. Alias for LoadSwarm for compatibility.

func (*Manager) GetWorkerBranch

func (m *Manager) GetWorkerBranch(swarmID, worker, taskID string) string

GetWorkerBranch generates the branch name for a worker on a task.

func (*Manager) IsComplete

func (m *Manager) IsComplete(swarmID string) (bool, error)

IsComplete checks if all tasks are closed by querying beads.

func (*Manager) LandToMain

func (m *Manager) LandToMain(swarmID string) error

LandToMain merges the integration branch to the target branch (usually main).

func (*Manager) LoadSwarm

func (m *Manager) LoadSwarm(epicID string) (*Swarm, error)

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

func (m *Manager) MergeToIntegration(swarmID, workerBranch string) error

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

func (s *Swarm) Progress() int

Progress returns the completion percentage (0-100).

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

func (s TaskState) IsComplete() bool

IsComplete returns true if the task is in a terminal state.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL