swarm

Documentation

Index

• type AgentFactory
• type AgentRunner
• type Event
• type MailMessage
• type Manager
  • func NewManager(cfg config.SwarmConfig, prov provider.Provider, factory AgentFactory, ...) *Manager
  • func (m *Manager) BroadcastToTeam(teamID string, msg MailMessage) []string
  • func (m *Manager) CreateTeam(name, leaderID string) TeamSnapshot
  • func (m *Manager) DeleteTeam(teamID string) error
  • func (m *Manager) EnsureTaskManager(teamID string) (*task.Manager, error)
  • func (m *Manager) GetTaskManager(teamID string) *task.Manager
  • func (m *Manager) GetTeam(id string) (TeamSnapshot, bool)
  • func (m *Manager) GetTeamResults(teamID string) map[string]string
  • func (m *Manager) GetTeammateResult(teamID, tmID string) (string, bool)
  • func (m *Manager) ListTeams() []TeamSnapshot
  • func (m *Manager) RootContext() context.Context
  • func (m *Manager) SendToTeammate(teamID, tmID string, msg MailMessage) error
  • func (m *Manager) SetOnUpdate(fn func(Event))
  • func (m *Manager) Shutdown()
  • func (m *Manager) ShutdownTeammate(teamID, tmID string) error
  • func (m *Manager) SpawnTeammate(teamID, name, color string, allowedTools []string) (TeammateSnapshot, error)
• type TaskResult
• type Team
• type TeamSnapshot
• type Teammate
• type TeammateSnapshot
• type TeammateStatus
• type ToolBuilder

Types

type AgentFactory

type AgentFactory func(prov provider.Provider, tools interface{}, systemPrompt string, maxTurns int) AgentRunner

AgentFactory creates an agent with the given provider, tool set, system prompt, and max turns.

type AgentRunner

type AgentRunner interface {
	RunStream(ctx context.Context, prompt string, onEvent func(provider.StreamEvent)) error
}

AgentRunner is the minimal interface a teammate agent must satisfy.

type Event

type Event struct {
	Type         string // "teammate_spawned", "teammate_working", "teammate_idle", "teammate_shutdown", "team_created", "team_deleted"
	TeamID       string
	TeammateID   string
	TeammateName string
	Result       string
	Error        error
	Timestamp    time.Time
}

Event represents a state change in the swarm system, sent to TUI via callback.

type MailMessage

type MailMessage struct {
	From    string // sender ID (leader or another teammate)
	Content string // task or message content
	Summary string // optional short summary
	Type    string // "task", "message", "shutdown"

	// ReplyTo is an optional channel for sending the task result back to the caller.
	// If non-nil, the idle runner will send the execution result here after the task completes.
	// The caller (e.g., send_message tool) blocks on this channel to await the result.
	ReplyTo chan<- TaskResult
}

MailMessage is a message delivered to a teammate's inbox.

type Manager

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

Manager manages swarm teams: creation, teammate spawning, lifecycle.

func NewManager

func NewManager(cfg config.SwarmConfig, prov provider.Provider, factory AgentFactory, builder ToolBuilder) *Manager

NewManager creates a swarm Manager.

func (*Manager) BroadcastToTeam

func (m *Manager) BroadcastToTeam(teamID string, msg MailMessage) []string

BroadcastToTeam sends a message to all idle teammates in the team.

func (*Manager) CreateTeam

func (m *Manager) CreateTeam(name, leaderID string) TeamSnapshot

CreateTeam creates a new team with the given name and returns its snapshot.

func (*Manager) DeleteTeam

func (m *Manager) DeleteTeam(teamID string) error

DeleteTeam shuts down all teammates and removes the team.

func (*Manager) EnsureTaskManager

func (m *Manager) EnsureTaskManager(teamID string) (*task.Manager, error)

EnsureTaskManager returns the team's task manager, creating it if needed.

func (*Manager) GetTaskManager

func (m *Manager) GetTaskManager(teamID string) *task.Manager

GetTaskManager returns the team's task manager without creating one. Returns nil if the team has no task board yet.

func (*Manager) GetTeam

func (m *Manager) GetTeam(id string) (TeamSnapshot, bool)

GetTeam returns a snapshot of the team if it exists.

func (*Manager) GetTeamResults

func (m *Manager) GetTeamResults(teamID string) map[string]string

GetTeamResults returns a map of teammateID → last result for all teammates in the team that have a result.

func (*Manager) GetTeammateResult

func (m *Manager) GetTeammateResult(teamID, tmID string) (string, bool)

GetTeammateResult returns the most recent task output for a teammate. Returns (result, true) if a result exists, ("", false) otherwise.

func (*Manager) ListTeams

func (m *Manager) ListTeams() []TeamSnapshot

ListTeams returns snapshots of all teams.

func (*Manager) RootContext

func (m *Manager) RootContext() context.Context

RootContext returns the manager's lifecycle context.

func (*Manager) SendToTeammate

func (m *Manager) SendToTeammate(teamID, tmID string, msg MailMessage) error

SendToTeammate sends a message to a specific teammate's inbox.

func (*Manager) SetOnUpdate

func (m *Manager) SetOnUpdate(fn func(Event))

SetOnUpdate sets the callback for swarm state changes (used by TUI).

func (*Manager) Shutdown

func (m *Manager) Shutdown()

Shutdown cancels all running teammates and stops the manager.

func (*Manager) ShutdownTeammate

func (m *Manager) ShutdownTeammate(teamID, tmID string) error

ShutdownTeammate stops a specific teammate.

func (*Manager) SpawnTeammate

func (m *Manager) SpawnTeammate(teamID, name, color string, allowedTools []string) (TeammateSnapshot, error)

SpawnTeammate creates a new teammate in the given team and starts its idle loop.

type TaskResult

type TaskResult struct {
	Output string
	Error  error
}

TaskResult holds the outcome of a teammate executing a task.

type Team

type Team struct {
	ID        string
	Name      string
	LeaderID  string
	Teammates map[string]*Teammate
	Tasks     *task.Manager // shared task board
	CreatedAt time.Time
	// contains filtered or unexported fields
}

Team represents a collaboration group with a leader and multiple teammates.

type TeamSnapshot

type TeamSnapshot struct {
	ID        string
	Name      string
	LeaderID  string
	Teammates []TeammateSnapshot
	TaskCount int
	CreatedAt time.Time
}

TeamSnapshot is a read-only copy of a Team for external consumption.

type Teammate

type Teammate struct {
	ID          string
	Name        string // e.g., "researcher", "coder"
	Color       string // TUI display color (ANSI code or empty)
	Status      TeammateStatus
	CurrentTask string
	LastResult  string // most recent task output (truncated)
	Inbox       chan MailMessage
	CreatedAt   time.Time
	StartedAt   time.Time
	EndedAt     time.Time
	// contains filtered or unexported fields
}

Teammate represents a worker agent within a team.

type TeammateSnapshot

type TeammateSnapshot struct {
	ID          string
	Name        string
	Color       string
	Status      TeammateStatus
	CurrentTask string
	LastResult  string // most recent task output (truncated)
	CreatedAt   time.Time
	StartedAt   time.Time
	EndedAt     time.Time
}

TeammateSnapshot is a read-only copy of a Teammate for external consumption.

type TeammateStatus

type TeammateStatus string

TeammateStatus represents the lifecycle state of a teammate within a team.

const (
	TeammateIdle         TeammateStatus = "idle"
	TeammateWorking      TeammateStatus = "working"
	TeammateShuttingDown TeammateStatus = "shutting_down"
)

type ToolBuilder

type ToolBuilder func(allowedTools []string) interface{}

ToolBuilder constructs a tool set for a teammate based on allowed tool names.