swarm

Documentation

Overview

Package swarm is the ephemeral per-call coordinator for CAP-03: it fans a set of goals out as LlmAgent workers, runs them in budget-bounded leak-safe waves, isolates per-child failures (a failed child becomes a report entry, siblings keep running — D-02), and collects an ordered []ChildReport. The engine is decoupled from the swarm_spawn tool (09-05 wires them) so it stays independently testable with agenttest.FakeClient.

Index

• Constants
• func Run(ctx context.Context, rc RunConfig, goals []string) (string, error)
• type ChildReport
• type RunConfig
• type RunnerAdapter
  • func NewRunnerAdapter(cfg config.Config) *RunnerAdapter
  • func (a *RunnerAdapter) Run(ctx context.Context, goals []string) (tools.ToolResult, error)

Constants

const (
	StatusOK             = "ok"
	StatusFailed         = "failed"
	StatusNeedsUserInput = "needs_user_input"
)

Status values a ChildReport can carry (D-15). They are model-readable: the parent LLM reads these off the collected report to decide aggregation / proxying.

Functions

func Run

func Run(ctx context.Context, rc RunConfig, goals []string) (string, error)

Run fans goals out as LlmAgent workers in budget-bounded leak-safe waves, isolates per-child failures (a failed/timed-out child becomes a {status:failed} report; its siblings are NEVER cancelled — D-02), and returns the ordered []ChildReport marshaled to JSON. A pre-flight failure (depth/goals-cap/budget) returns a model-readable "error: ..." string and NO worker is spawned. The returned error is reserved for a genuine marshal failure; domain rejections ride in the string so the model self-corrects (D-15).

Types

type ChildReport

type ChildReport struct {
	GoalIndex  int      `json:"goal_index"`
	ChildID    string   `json:"child_id"`
	Status     string   `json:"status"`
	Summary    string   `json:"summary,omitempty"`
	Error      string   `json:"error,omitempty"`
	Question   string   `json:"question,omitempty"`
	Options    []string `json:"options,omitempty"`
	ToolCallID string   `json:"tool_call_id,omitempty"`
}

ChildReport is one worker's slot in the swarm result, ordered by goal index (D-15). ChildID is the deterministic flat worker id ("w1".."wN", D-16) — it contains no path separator so it is safe as both the worker SessionID suffix and the transcript filename (Pitfall 4). The needs_user_input fields (Question/Options/ToolCallID) carry the worker's ask_user pause payload (D-04) so the parent can proxy it via D-05.

type RunConfig

type RunConfig struct {
	ParentBudget   *agent.Budget
	ParentRegistry *tools.Registry
	Client         llm.Client
	LLM            llm.Config
	Cfg            config.Config
	ConvID         string
	Depth          int
}

RunConfig carries the inputs the ephemeral runner needs for one swarm_spawn call. Depth is the invocation depth (a parent-initiated spawn is depth 1); the D-10 guard rejects depth >= AURA_SWARM_MAX_DEPTH. ConvID keys the per-child SessionID and the transcript directory.

type RunnerAdapter

type RunnerAdapter struct {
	Cfg   config.Config
	Depth int
}

RunnerAdapter is the concrete swarmRunner the swarm_spawn tool delegates to (cycle-free seam). It imports internal/agent + internal/config — fine, because swarm_spawn.go in the tools package imports NEITHER (the interface lives there). The composition root (cmd/aura) constructs one with the static Cfg and injects it as the tool's Runner; the per-invocation parent deps (budget/registry/client/ llmCfg/convID) travel on the ctx via agent.WithSwarmContext, set by the agent's runTool. Run reads them off the ctx, builds the swarm RunConfig, and calls the 09-02 engine, whose runChild derives each worker registry via Without(parentRegistry, "swarm_spawn") (D-08/D-10 flat — no nested swarm).

func NewRunnerAdapter

func NewRunnerAdapter(cfg config.Config) *RunnerAdapter

NewRunnerAdapter builds an adapter over the static config. Depth defaults to 1 (a parent-initiated spawn); a caller may raise it for forward-compat nesting.

func (*RunnerAdapter) Run

func (a *RunnerAdapter) Run(ctx context.Context, goals []string) (tools.ToolResult, error)

Run resolves the parent deps off the ctx (agent.WithSwarmContext, injected by the agent's runTool), builds the RunConfig, and invokes the engine. A missing swarm context is a model-readable inline error (the tool was dispatched outside the agent loop — a wiring bug, surfaced without panicking). The engine's marshal error is the only real Go error; domain rejections ride in the JSON string. The returned report JSON is wrapped via tools.NewResult so a large report spills to a sidecar (D-15 — the ONLY spillover path).