swarm

package
v1.3.68 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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_text", "teammate_tool_call", "teammate_idle", "teammate_shutdown", "team_created", "team_deleted"
	TeamID       string
	TeammateID   string
	TeammateName string
	Result       string
	Error        error
	CurrentTool  string // tool name (for teammate_tool_call)
	ToolID       string // tool call ID (for teammate_tool_call/result)
	ToolArgs     string // tool args (for teammate_tool_call)
	IsError      bool   // tool result error (for teammate_tool_result)
	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
}

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) CancelAll added in v1.2.3 

func (m *Manager) CancelAll()

CancelAll cancels all live teammates across all teams. Used when the main agent is interrupted (ctrl+c/esc) to avoid orphaned work or queued work starting after the UI has already marked the team as cancelled.

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) FlushStreamBatch added in v1.3.62 

func (m *Manager) FlushStreamBatch()

FlushStreamBatch exports flushStreamBatch for use in tests.

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) ListTeamStatuses added in v1.3.11 

func (m *Manager) ListTeamStatuses() []TeamStatusInfo

ListTeamStatuses returns lightweight status info for all teams. Unlike ListTeams(), this does NOT copy teammate events and is safe to call at high frequency (e.g. on every streaming token event) without contending the Teammate.mu lock that the runner uses for appendEvent.

func (*Manager) ListTeams 

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

ListTeams returns full snapshots of all teams (including events). Prefer ListTeamStatuses() for strip/status display to avoid copying events.

func (*Manager) NotifyIdleRunners added in v1.1.97 

func (m *Manager) NotifyIdleRunners(teamID string)

NotifyIdleRunners sends a task-available hint to all idle teammates, triggering them to poll the task board immediately instead of waiting for the next poller tick.

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) SetUsageHandler added in v1.3.41 

func (m *Manager) SetUsageHandler(fn func(provider.TokenUsage))

func (*Manager) SetWorkingDir added in v1.2.3 

func (m *Manager) SetWorkingDir(dir string)

SetWorkingDir sets the working directory injected into teammate system prompts.

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.

func (*Manager) StartStreamBatcher added in v1.3.62 

func (m *Manager) StartStreamBatcher()

StartStreamBatcher starts the background goroutine that periodically flushes accumulated teammate text/reasoning events. Must be called after SetOnUpdate.

func (*Manager) TeammateEventsSince added in v1.3.11 

func (m *Manager) TeammateEventsSince(tmID string, fromIdx int) ([]TeammateEvent, int, bool)

TeammateEventsSince returns incremental events for a teammate starting from fromIdx, along with the total event count. Unlike TeammateSnapshot, this avoids copying the full event history and is safe to call at high frequency.

func (*Manager) TeammateSnapshot added in v1.2.3 

func (m *Manager) TeammateSnapshot(tmID string) (TeammateSnapshot, bool)

TeammateSnapshot returns a snapshot of a teammate by ID across all teams.

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 TeamStatusInfo added in v1.3.11 

type TeamStatusInfo struct {
	ID        string
	Name      string
	LeaderID  string
	Teammates []TeammateStatusInfo
	TaskCount int
}

TeamStatusInfo is a lightweight snapshot of a team with only teammate status info (no events). Use this instead of ListTeams() when only the strip display needs updating.

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.

func (*Teammate) EventsSince added in v1.3.11 

func (t *Teammate) EventsSince(fromIdx int) ([]TeammateEvent, int)

EventsSince returns only events with index >= fromIdx, along with the total event count. This avoids copying the full event history when only incremental events are needed (e.g. GUI agent panel updates).

type TeammateEvent added in v1.2.3 

type TeammateEvent struct {
	Type     TeammateEventType
	Text     string // TeammateEventText / TeammateEventReasoning / TeammateEventError
	ToolName string // TeammateEventToolCall / TeammateEventToolResult
	ToolID   string // TeammateEventToolCall / TeammateEventToolResult — unique ID for precise matching
	ToolArgs string // TeammateEventToolCall
	Result   string // TeammateEventToolResult
	IsError  bool   // TeammateEventToolResult / TeammateEventError
}

TeammateEvent is a single recorded event from a teammate's execution.

type TeammateEventType added in v1.2.3 

type TeammateEventType int

TeammateEventType identifies the kind of teammate event. 

const (
	TeammateEventText       TeammateEventType = iota // LLM text output
	TeammateEventReasoning                           // LLM thinking/reasoning output
	TeammateEventToolCall                            // tool invocation started
	TeammateEventToolResult                          // tool execution result
	TeammateEventError                               // error encountered
)

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
	Events        []TeammateEvent
	EventsDropped int
}

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 TeammateStatusInfo added in v1.3.11 

type TeammateStatusInfo struct {
	ID     string
	Name   string
	Status TeammateStatus
}

TeammateStatusInfo is a lightweight read-only copy of a Teammate's identity and status. Unlike TeammateSnapshot, it does NOT copy events, making it safe to call at high frequency (e.g. every streaming token) without incurring O(maxTeammateEvents) copy overhead or contending the Teammate.mu lock that the runner uses for appendEvent.

type ToolBuilder 

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

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.