subagent

Documentation

Index

• type Job
• type Manager
  • func New(opts Options) *Manager
  • func (m *Manager) Boundary() []agent.Input
  • func (m *Manager) Close()
  • func (m *Manager) Flush()
  • func (m *Manager) Interrupted()
  • func (m *Manager) List() []Job
  • func (m *Manager) Poll(ctx context.Context, id string) (Job, bool)
  • func (m *Manager) Reserve(calls []agent.ToolCall)
  • func (m *Manager) Start(task, instructions string) string
  • func (m *Manager) Stop(id string) error
  • func (m *Manager) StopAll() int
  • func (m *Manager) Tools() []agent.Tool
• type Options
• type Status
  • func (s Status) String() string
• type ToolSource

Types

type Job

type Job struct {
	ID      string
	Status  Status
	Task    string // shortened task label, single line
	Started time.Time
	Ended   time.Time
	Summary string
	Err     error
}

Job is a public snapshot of one investigation, for List and Poll callers.

type Manager

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

Manager owns every sub-agent job: spawning, concurrency bounding, polling, completion notification and shutdown.

func New

func New(opts Options) *Manager

New returns a Manager with defaults resolved.

func (*Manager) Boundary

func (m *Manager) Boundary() []agent.Input

Boundary returns one batched completion input for the step boundary, or nil. The host chains it into agent.Options.OnBoundary, so it runs on the loop goroutine at the exact moment the message lands: ids a poll claimed since completing are dropped and never named, because the poll response already carries their result.

func (*Manager) Close

func (m *Manager) Close()

Close cancels every job and waits briefly for them to stop, then clears the activity rows and status segment.

func (*Manager) Flush

func (m *Manager) Flush()

Flush retries delivering every completed-but-undelivered id into the parent context as one batched message. Called from a turn-start observer so pending completions reach the model on the next real turn without ever starting one.

func (*Manager) Interrupted

func (m *Manager) Interrupted()

Interrupted reports that the parent turn was interrupted: queued completion steers were dropped without their Delivered firing, so the in-flight marks must release or every later batch waits behind a delivery that never comes. The ids stay pending for the next Flush.

func (*Manager) List

func (m *Manager) List() []Job

List returns a snapshot of every job, oldest id first.

func (*Manager) Poll

func (m *Manager) Poll(ctx context.Context, id string) (Job, bool)

Poll blocks until id completes, PollTimeout elapses, or ctx is cancelled. It returns false when still running; an interrupted turn releases the poll at once.

func (*Manager) Reserve

func (m *Manager) Reserve(calls []agent.ToolCall)

Reserve hands out an id number for every agent_start in one tool batch, in the order the model asked for them. agent_start is ModeParallel, so without this the goroutines race for the counter and the task submitted last can become sub-1. A batch supersedes the previous one, dropping reservations whose call never ran (an interrupted turn); the ids they held are simply skipped.

func (*Manager) Start

func (m *Manager) Start(task, instructions string) string

Start launches one investigation and returns its id immediately. The job sits StatusQueued until it takes a concurrency slot.

func (*Manager) Stop

func (m *Manager) Stop(id string) error

Stop cancels one job by id (accepts sub-2 or bare 2). A queued or running job is aborted; a finished one returns an error.

func (*Manager) StopAll

func (m *Manager) StopAll() int

StopAll cancels every in-flight job and returns how many were cancelled.

func (*Manager) Tools

func (m *Manager) Tools() []agent.Tool

Tools returns the three agent_* tools a parent registers.

type Options

type Options struct {
	Provider            func(llm.Model) (llm.Provider, error)
	Model               func() llm.Model           // configured child model, else the session's
	Reasoning           func() llm.ReasoningConfig // inherited from the parent
	Parent              func() *tokens.Accounting  // parent ledger; Child() per job
	Tools               ToolSource                 // nil disables a child's tool set entirely
	Env                 agent.Environment
	ProjectInstructions []agent.ProjectInstruction

	// Activity publishes one keyed row; an empty text removes it. rank is the
	// job number, so rows hold a stable place regardless of publish order.
	Activity func(key, text string, rank int) // nil disables activity rows
	Notice   func(msg string)                 // keyed UI notice for completions
	Status   func(text, short string)
	Deliver  func(agent.Input) bool // steer into a running parent turn; false when idle

	MaxConcurrent int           // 0 -> defaultMaxConcurrent
	PollTimeout   time.Duration // 0 -> defaultPollTimeout
}

Options configures a sub-agent Manager. The func-typed fields are supplied by main.go so this package never imports pkg/tui or pkg/tools.

type Status

type Status uint8

Status is a job's lifecycle state.

const (
	StatusQueued Status = iota // waiting on the concurrency semaphore
	StatusRunning
	StatusDone
	StatusError
	StatusAborted
)

func (Status) String

func (s Status) String() string

String returns the canonical status name used in /agents and tool output.

type ToolSource

type ToolSource interface {
	All() []agent.Tool
	ReadOnly(name string) bool
}

ToolSource is the parent registry's view a child tool set is built from.