agent

Documentation

Index

• Variables
• func DefaultMerge(outputs map[RoleType]string) string
• func ResolveProvider(role RoleType, registry *provider.Registry, roles map[RoleType]string) provider.Provider
• func SaveCheckpoint(jobID string, checkpoint *JobCheckpoint) error
• type JobCheckpoint
  • func LoadCheckpoint(jobID string) (*JobCheckpoint, error)
• type JobResult
• type MergeFunc
• type RoleType
• type Stage
• type StageCheckpoint
• type StageResult
• type TaskGraph
  • func (g *TaskGraph) Resume(ctx context.Context, jobID string, onStageComplete func(StageResult)) (*JobResult, error)
  • func (g *TaskGraph) Run(ctx context.Context, input string, onStageComplete func(StageResult)) (*JobResult, error)
• type Worker
  • func (w *Worker) Run(ctx context.Context, input string) (string, tokens.Usage, error)

Variables

var RolePrompts = map[RoleType]string{
	RolePlanner: "Break this request into concrete steps. Identify what information is needed. Produce a numbered plan.",

	RoleResearcher: "You are gathering context for a task. Read the plan and identify relevant code, documentation, and patterns. Summarize your findings.",

	RoleImplementer: "Implement the plan using the research provided. Write clean, focused code changes.",

	RoleTester: "Write tests that verify the implementation. Focus on edge cases and regressions.",

	RoleReviewer: "Review the plan, research, and any implementation. Identify gaps, risks, and improvements. Produce a final assessment.",
}

RolePrompts maps each role to its tailored system prompt.

Functions

func DefaultMerge

func DefaultMerge(outputs map[RoleType]string) string

DefaultMerge concatenates worker outputs with role headers.

func ResolveProvider

func ResolveProvider(role RoleType, registry *provider.Registry, roles map[RoleType]string) provider.Provider

ResolveProvider looks up the provider for a given role. It checks the roles map (role -> provider name), finds the matching provider in the registry by ID, and falls back to the registry's primary provider if no match is found.

func SaveCheckpoint

func SaveCheckpoint(jobID string, checkpoint *JobCheckpoint) error

SaveCheckpoint writes a checkpoint to disk as JSON atomically using a temp file + rename to prevent corruption from crashes during write.

Types

type JobCheckpoint

type JobCheckpoint struct {
	JobID     string            `json:"job_id"`
	Request   string            `json:"request"`
	Stages    []StageCheckpoint `json:"stages"`
	CreatedAt time.Time         `json:"created_at"`
	UpdatedAt time.Time         `json:"updated_at"`
}

JobCheckpoint is the serializable state of a job that can be saved to disk and loaded to resume execution.

func LoadCheckpoint

func LoadCheckpoint(jobID string) (*JobCheckpoint, error)

LoadCheckpoint reads a checkpoint from disk.

type JobResult

type JobResult struct {
	JobID      string
	Request    string
	Stages     []StageResult
	TotalUsage tokens.Usage
	Complete   bool
	Error      string
}

JobResult captures the full result of a task graph execution.

type MergeFunc

type MergeFunc func(outputs map[RoleType]string) string

MergeFunc combines the outputs of parallel workers within a stage into a single string that becomes the input for the next stage.

type RoleType

type RoleType string

RoleType identifies a worker's role within an agent team.

const (
	RolePlanner     RoleType = "planner"
	RoleResearcher  RoleType = "researcher"
	RoleImplementer RoleType = "implementer"
	RoleTester      RoleType = "tester"
	RoleReviewer    RoleType = "reviewer"
)

type Stage

type Stage struct {
	Name    string
	Workers []*Worker
	Merge   MergeFunc // nil = default merge
}

Stage represents a group of workers that execute in parallel. Stages execute sequentially within a TaskGraph.

type StageCheckpoint

type StageCheckpoint struct {
	Name     string            `json:"name"`
	Complete bool              `json:"complete"`
	Outputs  map[string]string `json:"outputs"` // role -> output
}

StageCheckpoint records the state of a completed stage.

type StageResult

type StageResult struct {
	StageName     string
	WorkerOutputs map[RoleType]string
	Usage         tokens.Usage
}

StageResult captures the output of a completed stage.

type TaskGraph

type TaskGraph struct {
	JobID  string
	Stages []Stage
	Budget int // max total tokens (input+output), 0 = unlimited
}

TaskGraph is an ordered list of stages that execute sequentially. Within each stage, workers run in parallel.

func (*TaskGraph) Resume

func (g *TaskGraph) Resume(ctx context.Context, jobID string, onStageComplete func(StageResult)) (*JobResult, error)

Resume loads a checkpoint and continues execution from the next incomplete stage.

func (*TaskGraph) Run

func (g *TaskGraph) Run(ctx context.Context, input string, onStageComplete func(StageResult)) (*JobResult, error)

Run executes the task graph: stages run sequentially, workers within each stage run in parallel. The merged output of each stage becomes the input for the next stage. The onStageComplete callback is called after each stage finishes.

type Worker

type Worker struct {
	Role         RoleType
	ProviderName string // which provider this worker uses
	Provider     provider.Provider
	SystemPrompt string
	MaxTokens    int
}

Worker wraps a provider with a role-specific system prompt. It constructs messages and queries the provider, returning the full response text and token usage.

func (*Worker) Run

func (w *Worker) Run(ctx context.Context, input string) (string, tokens.Usage, error)

Run executes the worker: constructs messages [system, user input], queries the provider, drains the stream, and returns output + usage.