hive

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Background-task helpers. `bee bg` spawns detached child engines and drops their stdout/stderr under <beeHome>/sessions/bg/<session-id>.log. Pure helpers — no exec, no syscall — so the package stays portable.

Result fan-in helpers. Plain functions over []Result so callers can compose them without bringing in the Pool dependency.

Queen-and-workers orchestration.

The Queen runs three or four phases:

  1. decompose: ask Planner Runner to split the task into ≤8 sub-tasks (JSON objects pairing role + task).
  2. dispatch: round-robin sub-tasks to Workers, fan out via goroutines.
  3. review: (optional) hand worker outputs to Critic for a short critique.
  4. synthesize: hand all worker outputs (plus critique if any) back to Planner for a final summary.

Pool from spawn.go (slice 4A) is preferred when available; this file uses direct goroutine fan-out so the queen still builds even if 4A is missing.

Fan-out orchestrator. Spawns up to MaxConcurrency workers in parallel, each driving its own Engine via the Runner contract. Results stream out on a channel as workers finish; cancellation propagates through ctx.

Package hive implements multi-bee orchestration: fan-out (Pool), queen-and- workers (Queen), and the result fan-in primitives both share.

A Worker wraps a single loop.Engine running in its own goroutine. The TUI visual concept lives in internal/tui/hive.go and is intentionally separate.

Index

Constants

View Source 
const MaxSubTasks = 8

MaxSubTasks caps how many sub-tasks the queen will accept from the planner. matches the prompt budget; defends against runaway plans.

Variables

This section is empty.

Functions

func EnsureLogDir 

func EnsureLogDir(sessionID string) (string, error)

EnsureLogDir creates the parent directory for LogPath and returns the fully-qualified log path. Idempotent.

func LogDir 

func LogDir() (string, error)

LogDir returns the directory holding background log files.

func LogPath 

func LogPath(sessionID string) (string, error)

LogPath returns the absolute path where a background session's combined stdout/stderr should be written. It does not create anything on disk.

func MergeText 

func MergeText(results []Result) string

MergeText concatenates the final text from each successful worker into a single transcript with `## <name>` headers. Failed workers are omitted.

func ReadPid 

func ReadPid(sessionID string) (int, error)

ReadPid reads a pidfile if it exists.

func Summary 

func Summary(results []Result) string

Summary renders a human-readable summary block: counts, wall-clock, and one line per worker. Wall-clock is min(Started)..max(Ended), so it reflects actual parallel duration, not sum-of-bee-times.

func WritePid 

func WritePid(sessionID string, pid int) error

WritePid writes the process id to a pidfile beside the log.

Types

type Pool 

type Pool struct {
	MaxConcurrency int

	Workers []*Worker
	// contains filtered or unexported fields
}

Pool manages a bounded set of concurrent Workers.

func NewPool 

func NewPool(max int) *Pool

NewPool builds a Pool with the given concurrency cap. A non-positive cap is treated as 1 — refusing to run any work would surprise callers.

func (*Pool) Run 

func (p *Pool) Run(ctx context.Context) <-chan Result

Run dispatches submitted workers up to MaxConcurrency at a time. Each worker's Engine.Run is invoked with a context derived from ctx. Results land on the returned channel as workers finish; the channel closes once all workers are done (including those skipped by cancellation).

func (*Pool) Submit 

func (p *Pool) Submit(w *Worker)

Submit registers a Worker with the pool. State starts at pending. Safe to call before Run; calling after Run is a no-op for that worker because the dispatcher has already iterated the snapshot.

func (*Pool) WorkersSnapshot 

func (p *Pool) WorkersSnapshot() []*Worker

WorkersSnapshot returns a shallow copy of the Worker pointer slice for observers (TUI, tests). The pointed-to Worker structs are still shared, so reading State/Started/Ended is a live view.

type Queen 

type Queen struct {
	Planner     Runner
	Workers     []Runner
	Critic      Runner
	MaxParallel int // 0 => len(Workers)
}

Queen orchestrates a planner Runner and N worker Runners. Critic is optional; when set, its output is appended to the synthesize prompt.

func NewQueen 

func NewQueen(planner Runner, workers []Runner) *Queen

NewQueen returns a Queen ready to Run. MaxParallel defaults to len(workers).

func (*Queen) Run 

func (q *Queen) Run(ctx context.Context, task string) (QueenResult, error)

Run executes the full decompose → dispatch → (review) → synthesize pipeline.

type QueenResult 

type QueenResult struct {
	Plan          []SubTask
	WorkerResults []Result
	Critique      string
	Final         string
}

QueenResult is the aggregate of one Queen.Run.

type Result 

type Result struct {
	WorkerID string
	Name     string
	Task     string
	Final    string
	Err      error
	Started  time.Time
	Ended    time.Time
}

Result is what a Worker emits on completion. Final is the final assistant text; Err is non-nil if the run failed.

func Collect 

func Collect(ch <-chan Result) []Result

Collect drains ch into a slice. Returns when the channel is closed. Order matches arrival order, not submission order.

type Role 

type Role string

Role names a hive specialist. Each role pairs a tuned system prompt with a tool allowlist. The queen.go / pool.go wiring decides defaults when a role's AllowedTools is empty. 

const (
	RoleQueen        Role = "queen"
	RoleSubqueen     Role = "subqueen"
	RoleBuilder      Role = "builder"
	RoleScoutPlanner Role = "scout_planner"
	RoleForeman      Role = "foreman"
	RoleSage         Role = "sage"
	RoleArchivist    Role = "archivist"
	RoleForager      Role = "forager"
	RoleDiviner      Role = "diviner"
	RoleCritic       Role = "critic"
	RoleEye          Role = "eye"
)

func AllRoles 

func AllRoles() []Role

AllRoles returns every defined role in stable order.

func ParseRole 

func ParseRole(s string) (Role, bool)

ParseRole accepts the canonical name (case-insensitive) and returns the Role + ok. Whitespace is trimmed.

func (Role) AllowedTools 

func (r Role) AllowedTools() []string

AllowedTools returns the tool names this role may invoke. Empty slice means "all tools" — caller decides default. Returned slice is a copy.

func (Role) SystemPrompt 

func (r Role) SystemPrompt() string

SystemPrompt returns the role-tuned system prompt text. Empty for unknown roles.

func (Role) Temperature 

func (r Role) Temperature() float64

Temperature returns the recommended sampling temperature for the role.

type Runner 

type Runner interface {
	Run(ctx context.Context, userMsg string) (loop.RunResult, error)
}

Runner is the contract Pool and Queen both rely on. It exists so callers can inject a stub Runner in tests instead of a real loop.Engine.

type State 

type State string

State of a Worker bee. 

const (
	StatePending  State = "pending"
	StateRunning  State = "running"
	StateDone     State = "done"
	StateFailed   State = "failed"
	StateCanceled State = "canceled"
)

type SubTask 

type SubTask struct {
	Role Role
	Task string
}

SubTask pairs a single planner-emitted sub-task with the role that should execute it. Queen produces these during decompose and uses them downstream in dispatch + synthesize.

type Worker 

type Worker struct {
	ID      string
	Name    string
	Task    string
	Engine  *loop.Engine
	State   State
	Started time.Time
	Ended   time.Time
}

Worker is one bee executing one task against its own Engine.

Engine is required; the rest is filled in by Pool/Queen and observed via the Result channel.

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.