Documentation
¶
Overview ¶
Package agent provides the agent runtime pool and runner for processing tasks as goroutines with session lifecycle management and cost recording.
Index ¶
- Variables
- func BranchSlug(issueNumber int, title string) string
- func BuildSystemPrompt(task Task, fileContext map[string]string) string
- type FileEdit
- type ParseResponse
- type Pool
- func (p *Pool) AddWorkers(n int) error
- func (p *Pool) Done() <-chan struct{}
- func (p *Pool) RemoveWorkers(n int) int
- func (p *Pool) Resize(target int) error
- func (p *Pool) SetMaxWorkers(limit int)
- func (p *Pool) SetOnComplete(fn func(TaskResult))
- func (p *Pool) Shutdown()
- func (p *Pool) Snapshot() metrics.PoolSnapshot
- func (p *Pool) Submit(task Task) error
- func (p *Pool) Workers() int
- type Runner
- type Task
- type TaskResult
Constants ¶
This section is empty.
Variables ¶
var ErrMaxWorkers = errors.New("pool: would exceed maximum worker count")
ErrMaxWorkers is returned when AddWorkers or Resize would exceed the configured maximum worker count.
var ErrPoolShutdown = errors.New("pool is shut down")
ErrPoolShutdown is returned when Submit is called on a shut-down pool.
Functions ¶
func BranchSlug ¶ added in v0.1.5
BranchSlug generates a branch name from an issue number and title. Format: agent/issue-{N}-{slug}, truncated to 50 chars.
func BuildSystemPrompt ¶ added in v0.1.3
BuildSystemPrompt dispatches to per-agent-type prompt builders and appends file context when available. Agent types that are not AI-driven (human, orchestrator, dispatcher) return an empty string.
Types ¶
type FileEdit ¶ added in v0.1.5
FileEdit represents a single file edit extracted from an agent response.
type ParseResponse ¶ added in v0.1.5
ParseResponse holds the parsed result of an agent's response.
func ParseEditBlocks ¶ added in v0.1.5
func ParseEditBlocks(response string) *ParseResponse
ParseEditBlocks extracts EDIT/END file blocks and the PR_TITLE line from an agent response string. Returns nil edits if no EDIT blocks found.
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool manages a set of worker goroutines that process agent tasks. Workers may be added or removed at runtime via AddWorkers/RemoveWorkers/Resize.
func NewPool ¶
func NewPool(registry *provider.Registry, tracker forge.IssueTracker, st store.Store, costs *cost.Tracker, workers int) *Pool
NewPool creates a pool with the given number of worker goroutines and starts them immediately. If workers is <= 0, it defaults to 3. The default maximum is runtime.NumCPU(); call SetMaxWorkers to override before scaling.
func (*Pool) AddWorkers ¶ added in v0.1.11
AddWorkers starts n additional worker goroutines. Returns ErrPoolShutdown if the pool has already been shut down, or ErrMaxWorkers if the addition would exceed the configured maximum. No-op if n <= 0.
func (*Pool) Done ¶
func (p *Pool) Done() <-chan struct{}
Done returns a channel that is closed after Shutdown completes.
func (*Pool) RemoveWorkers ¶ added in v0.1.11
RemoveWorkers signals n workers to exit after completing their current task. To protect liveness, at least one worker is always kept running; the actual number removed may be less than n. Returns the number of quit signals sent.
func (*Pool) Resize ¶ added in v0.1.11
Resize sets the pool's worker count to target, adding or removing workers as needed. It enforces the same minimum (1) and maximum bounds as AddWorkers and RemoveWorkers. Returns ErrPoolShutdown if the pool has been shut down.
func (*Pool) SetMaxWorkers ¶ added in v0.1.11
SetMaxWorkers sets the maximum number of workers the pool may hold at any time. A value <= 0 removes the limit. Must be called before scaling; not safe to call concurrently with AddWorkers or Resize.
func (*Pool) SetOnComplete ¶ added in v0.1.10
func (p *Pool) SetOnComplete(fn func(TaskResult))
SetOnComplete registers a callback invoked after each task finishes.
func (*Pool) Shutdown ¶
func (p *Pool) Shutdown()
Shutdown signals all workers to stop and waits for in-flight tasks to complete. After Shutdown returns, Submit will return ErrPoolShutdown.
func (*Pool) Snapshot ¶ added in v0.1.11
func (p *Pool) Snapshot() metrics.PoolSnapshot
Snapshot returns a point-in-time view of pool state for the scaling policy.
func (*Pool) Submit ¶
Submit enqueues a task for processing. Returns ErrPoolShutdown if the pool has been shut down.
The lock is held across the channel send to prevent a TOCTOU race with Shutdown: without it, Shutdown can close the channel between the flag check and the send, causing a panic. The channel is buffered (workers×2) so the send is almost always non-blocking. In the rare case the buffer is full, workers will drain it without acquiring mu, so no deadlock.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner executes a single agent task: sends the issue to an AI provider, records cost, and posts the response as an issue comment or opens a PR.
func NewRunner ¶
func NewRunner(p provider.Provider, model string, tracker forge.IssueTracker, st store.Store, costs *cost.Tracker) *Runner
NewRunner creates a runner bound to a specific provider and model. The repoWriter and prManager are optional; when nil, code-gen/test agents fall back to posting comments instead of opening PRs.
func (*Runner) Run ¶
Run processes a single task through the AI provider pipeline.
Steps:
- Update session status to "active"
- Check budget -- if exceeded, mark "failed" and return
- Build system prompt and chat request
- Call provider.Chat
- Record cost via cost tracker
- Post response as issue comment
- Mark session "completed"
On any error, the session is marked "failed" and an error comment is posted.
func (*Runner) SetPRManager ¶ added in v0.1.5
func (r *Runner) SetPRManager(pm forge.PullRequestManager)
SetPRManager configures pull request operations.
func (*Runner) SetRepoWriter ¶ added in v0.1.5
func (r *Runner) SetRepoWriter(rw forge.RepoWriter)
SetRepoWriter configures write access for branch/file operations.
type Task ¶
type Task struct {
Issue *forge.Issue
AgentType models.AgentType
SessionID string
ProviderKey string // routing chain key; defaults to string(AgentType) when empty
HeartbeatFunc func() // called periodically while running; signals dispatcher that work is in progress; may be nil
}
Task represents a unit of work to be processed by the agent pool.
Source Files