agent

package
v0.411.0 Latest Latest
Warning

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

 Go to latest Published: Jun 1, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	GoalStatusRunning   = "running"
	GoalStatusCompleted = "completed"
	GoalStatusFailed    = "failed"
	GoalStatusCancelled = "cancelled"
	GoalStatusBlocked   = "blocked"
	GoalStatusTimeout   = "timeout"
	GoalStatusStalled   = "stalled"
)

Goal status constants

View Source 
const (
	AgentToolName = "agent"
)

Variables

View Source 
var (
	ErrRequestCancelled = errors.New("request cancelled by user")
	ErrSessionBusy      = errors.New("session is currently processing another request")
)

Common errors

View Source 
var (
	ErrGoalMaxIterationsReached = errors.New("goal reached max iterations")
	ErrGoalMaxDurationExceeded  = errors.New("goal exceeded max duration")
)
View Source 
var ErrNoModel = fmt.Errorf("no model configured, please select a model")

ErrNoModel is returned when the agent has no model configured.

Functions

func BuildGoalContinuationPrompt added in v0.324.0 

func BuildGoalContinuationPrompt(objective string, iteration int, maxIterations int, progress string, nextStep string) string

func BuildGoalInitialPrompt added in v0.324.0 

func BuildGoalInitialPrompt(objective string, additionalInstructions string) string

func CoderAgentTools 

func CoderAgentTools(
	permissions permission.Service,
	history history.Service,
	lspClients map[string]*lsp.Client,
) []tools.BaseTool

func CoderAgentToolsWithMesnada 

func CoderAgentToolsWithMesnada(
	mesnadaOrchestrator *orchestrator.Orchestrator,
	remembrances *rag.RemembrancesService,
	gateway *mcpgateway.Gateway,
	permissions permission.Service,
	history history.Service,
	lspClients map[string]*lsp.Client,
) []tools.BaseTool

func CreateAgentProvider added in v0.403.0 

func CreateAgentProvider(ctx context.Context, agentName config.AgentName) (provider.Provider, error)

CreateAgentProvider creates a provider for the given agent name. It is exported for use in app-layer code that needs a provider outside of the agent itself (e.g. the context-enricher LLM planner adapter).

func GetActivePersona added in v0.200.0 

func GetActivePersona() string

GetActivePersona returns the currently active persona name. An empty string means no persona is active (auto-select or none).

func GetMcpTools 

func GetMcpTools(ctx context.Context, permissions permission.Service) []tools.BaseTool

func GetMcpToolsWithGateway added in v0.8.0 

func GetMcpToolsWithGateway(ctx context.Context, permissions permission.Service, gw *mcpgateway.Gateway) []tools.BaseTool

GetMcpToolsWithGateway returns MCP-backed tools for the LLM agent. When gw is non-nil (gateway mode), it exposes two proxy tools plus any favorite tools as direct wrappers. When gw is nil it falls back to the standard per-server tool list.

func GetPersonaManager added in v0.200.0 

func GetPersonaManager() *persona.Manager

GetPersonaManager returns the global persona manager, or nil if not initialised.

func ListAvailablePersonas added in v0.200.0 

func ListAvailablePersonas() []string

ListAvailablePersonas returns the names of all loaded personas. Uses the global persona manager when available; falls back to the selector's manager.

func NewAgentTool 

func NewAgentTool(
	Sessions session.Service,
	Messages message.Service,
	LspClients map[string]*lsp.Client,
	skillManager *skills.SkillManager,
) tools.BaseTool

func NewMcpTool 

func NewMcpTool(name string, tool mcp.Tool, permissions permission.Service, mcpConfig config.MCPServer) tools.BaseTool

func ResetMcpToolsCache added in v0.310.3 

func ResetMcpToolsCache()

func SetActivePersona added in v0.200.0 

func SetActivePersona(name string) error

SetActivePersona sets the active persona by name. Pass an empty string to clear the active persona (revert to auto-select or none). Returns an error if the named persona does not exist (and name is non-empty).

func SetContextEnricher added in v0.236.1 

func SetContextEnricher(e ContextEnricher)

SetContextEnricher sets the context enricher used to prepend KB/code context to user messages. Pass nil to disable context enrichment.

func SetContextTrimmer added in v0.407.0 

func SetContextTrimmer(ct ContextTrimmer)

SetContextTrimmer sets the context trimmer used to filter the tool list for new sessions. Pass nil to disable context trimming (all tools will always be included).

func SetLuaManager added in v0.8.0 

func SetLuaManager(fm *luaengine.FilterManager)

SetLuaManager sets the global Lua filter manager used for MCP tool input/output filtering.

func SetNonInteractiveMode added in v0.291.0 

func SetNonInteractiveMode(enabled bool)

SetNonInteractiveMode configures all agents to run autonomously without waiting for user input. Call this before running a session when a prompt is provided via the -p flag or stdin pipe.

func SetPersonaManager added in v0.200.0 

func SetPersonaManager(mgr *persona.Manager)

SetPersonaManager sets the global persona manager used for persona listing and manual persona selection. This should be called during app initialisation.

func SetPersonaSelector added in v0.41.0 

func SetPersonaSelector(ps *PersonaSelector)

SetPersonaSelector sets the global persona selector used in the main conversation agent.

func SetSessionLLMOverrides added in v0.407.0 

func SetSessionLLMOverrides(sessionID string, overrides SessionLLMOverrides)

func TaskAgentTools 

func TaskAgentTools(lspClients map[string]*lsp.Client) []tools.BaseTool

Types

type AgentEvent 

type AgentEvent struct {
	Type       AgentEventType
	Message    message.Message
	Error      error
	Delta      string
	ToolCall   *message.ToolCall
	ToolResult *message.ToolResult

	// When summarizing
	SessionID string
	Progress  string
	Done      bool

	// Todos is populated when Type == AgentEventTypeTodosUpdated.
	Todos []tools.TodoItem

	// SystemMessage is populated when Type == AgentEventTypeSystemMessage.
	// It carries a human-readable status message (context compaction, retries, etc.)
	// that should be shown to the user regardless of the transport (TUI, ACP, web).
	SystemMessage string
}

type AgentEventType 

type AgentEventType string
const (
	AgentEventTypeError         AgentEventType = "error"
	AgentEventTypeResponse      AgentEventType = "response"
	AgentEventTypeSummarize     AgentEventType = "summarize"
	AgentEventTypeContentDelta  AgentEventType = "content_delta"
	AgentEventTypeThinkingDelta AgentEventType = "thinking_delta"
	AgentEventTypeToolCall      AgentEventType = "tool_call"
	AgentEventTypeToolResult    AgentEventType = "tool_result"
	// AgentEventTypeTodosUpdated is emitted when the TodoWrite tool runs successfully.
	// It carries the current todo list for non-ACP consumers (TUI, WebUI).
	AgentEventTypeTodosUpdated AgentEventType = "todos_updated"
	// AgentEventTypeSystemMessage carries internal status messages (context compaction,
	// retries, etc.) that should be displayed to the user but are not part of the
	// LLM response. Unlike ContentDelta these are sent with a blocking channel write
	// so they are never silently dropped.
	AgentEventTypeSystemMessage AgentEventType = "system_message"
)

type AgentParams 

type AgentParams struct {
	Prompt string `json:"prompt"`
}

type ContextEnricher added in v0.236.1 

type ContextEnricher interface {
	EnrichContext(ctx context.Context, query string) string
}

ContextEnricher is the interface used by the agent to enrich the user's prompt with context retrieved from the KB and code index before sending it to the LLM. A local interface is used to avoid import cycles between agent and rag packages.

type ContextTrimmer added in v0.407.0 

type ContextTrimmer interface {
	// ProfileTask returns the recommended tool names for the task.
	// Returns nil/empty to indicate "use all tools" (e.g., on error or low confidence).
	ProfileTask(ctx context.Context, firstMessage string, availableTools []ToolDescription) ([]string, error)
}

ContextTrimmer analyzes the user's first message and recommends a minimal tool set to reduce context window usage by filtering irrelevant tools from the initial API call. It is wired from app.go via SetContextTrimmer.

type EvaluationResult added in v0.324.0 

type EvaluationResult struct {
	Complete      bool
	Blocked       bool
	Stalled       bool
	Reason        string
	Progress      string
	NextStep      string
	Confidence    float64
	ProgressMade  bool
	Signature     string
	TodoSignature string
}

type GoalEvaluator added in v0.324.0 

type GoalEvaluator interface {
	Evaluate(ctx context.Context, goal *GoalState, lastMessage string, todos []llmtools.TodoItem) (EvaluationResult, error)
}

type GoalEvent added in v0.324.0 

type GoalEvent struct {
	Type      GoalEventType
	GoalState *GoalState
	Message   string
}

GoalEvent represents a state change event for a goal.

type GoalEventType added in v0.324.0 

type GoalEventType string

GoalEventType represents the type of goal event. 

const (
	GoalEventStart     GoalEventType = "goal_start"
	GoalEventIteration GoalEventType = "goal_iteration"
	GoalEventComplete  GoalEventType = "goal_complete"
	GoalEventFailed    GoalEventType = "goal_failed"
	GoalEventCancelled GoalEventType = "goal_cancelled"
	GoalEventBlocked   GoalEventType = "goal_blocked"
	GoalEventTimeout   GoalEventType = "goal_timeout"
	GoalEventStalled   GoalEventType = "goal_stalled"
)

type GoalOptions added in v0.324.0 

type GoalOptions struct {
	MaxIterations   int64
	MaxDuration     time.Duration
	StallIterations int
	InitialPrompt   string
}

type GoalRunner added in v0.324.0 

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

func NewGoalRunner added in v0.324.0 

func NewGoalRunner(agent Service, goalStore GoalStore) *GoalRunner

func (*GoalRunner) Run added in v0.324.0 

func (gr *GoalRunner) Run(ctx context.Context, sessionID string, objective string, opts GoalOptions) (<-chan AgentEvent, error)

type GoalState added in v0.324.0 

type GoalState struct {
	ID                      string
	SessionID               string
	Objective               string
	StatusValue             string
	Iteration               int
	MaxIterations           int
	MaxDurationSecs         int
	StartedAt               time.Time
	CompletedAt             *time.Time
	LastProgress            string
	NextStep                string
	BlockedReason           string
	CreatedAt               time.Time
	InitialTodoSignature    string
	LastTodoSignature       string
	LastEvaluationSignature string
	ConsecutiveNoProgress   int
	// contains filtered or unexported fields
}

GoalState represents the current state of a goal.

func NewGoalState added in v0.324.0 

func NewGoalState(id, sessionID, objective string, maxIter, maxDurSecs int) *GoalState

func (*GoalState) Advance added in v0.324.0 

func (g *GoalState) Advance(progress string, nextStep string)

func (*GoalState) CanTransitionTo added in v0.324.0 

func (g *GoalState) CanTransitionTo(next string) bool

func (*GoalState) Cancel added in v0.324.0 

func (g *GoalState) Cancel()

Cancel signals the goal to stop.

func (*GoalState) Elapsed added in v0.324.0 

func (g *GoalState) Elapsed() time.Duration

Elapsed returns the time elapsed since the goal started.

func (*GoalState) IsCancelled added in v0.324.0 

func (g *GoalState) IsCancelled() bool

IsCancelled returns true if the goal has been cancelled.

func (*GoalState) IsRunning added in v0.324.0 

func (g *GoalState) IsRunning() bool

IsRunning returns true if the goal is currently active.

func (*GoalState) IsTerminal added in v0.324.0 

func (g *GoalState) IsTerminal() bool

IsTerminal returns true if the status is a terminal state.

func (*GoalState) RecordIteration added in v0.324.0 

func (g *GoalState) RecordIteration(progress string, nextStep string, todoSignature string, evaluationSignature string, progressMade bool)

func (*GoalState) RemainingDuration added in v0.324.0 

func (g *GoalState) RemainingDuration() time.Duration

RemainingDuration returns the remaining time before max duration.

func (*GoalState) SetStatus added in v0.324.0 

func (g *GoalState) SetStatus(s string)

SetStatus updates the status and marks done if terminal.

func (*GoalState) Status added in v0.324.0 

func (g *GoalState) Status() string

Status returns the current status for serialization.

func (*GoalState) Transition added in v0.324.0 

func (g *GoalState) Transition(next string, now time.Time) error

type GoalStore added in v0.324.0 

type GoalStore interface {
	CreateGoal(ctx context.Context, arg db.CreateGoalParams) (db.SessionGoal, error)
	UpdateGoalStatus(ctx context.Context, arg db.UpdateGoalStatusParams) (db.SessionGoal, error)
}

type HeuristicGoalEvaluator added in v0.324.0 

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

func NewHeuristicGoalEvaluator added in v0.324.0 

func NewHeuristicGoalEvaluator() *HeuristicGoalEvaluator

func NewHeuristicGoalEvaluatorWithThreshold added in v0.324.0 

func NewHeuristicGoalEvaluatorWithThreshold(stallThreshold int) *HeuristicGoalEvaluator

func (*HeuristicGoalEvaluator) Evaluate added in v0.324.0 

func (e *HeuristicGoalEvaluator) Evaluate(_ context.Context, goal *GoalState, lastMessage string, todos []llmtools.TodoItem) (EvaluationResult, error)

type MCPClient 

type MCPClient interface {
	Initialize(
		ctx context.Context,
		request mcp.InitializeRequest,
	) (*mcp.InitializeResult, error)
	ListTools(ctx context.Context, request mcp.ListToolsRequest) (*mcp.ListToolsResult, error)
	CallTool(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)
	Close() error
}

type PersonaSelector added in v0.41.0 

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

PersonaSelector automatically selects and applies a persona for each user prompt. It uses a lite LLM provider (configured via agents["persona-selector"]) to pick the best matching persona from the personas directory, then prepends its content to the user message before it reaches the main conversation model.

func NewPersonaSelector added in v0.41.0 

func NewPersonaSelector(personaPath string) (*PersonaSelector, error)

NewPersonaSelector creates a PersonaSelector that loads personas from personaPath and uses the model configured under agents["persona-selector"] to perform selection. Returns an error if the persona-selector agent is not configured or the model is unavailable.

func (*PersonaSelector) SelectAndApply added in v0.41.0 

func (ps *PersonaSelector) SelectAndApply(ctx context.Context, userPrompt string) string

SelectAndApply selects the best persona for userPrompt and returns the prompt with the persona content prepended. Kept for backward compatibility; prefer SelectPersonaContent when the content will be injected into the system prompt.

func (*PersonaSelector) SelectPersonaContent added in v0.265.0 

func (ps *PersonaSelector) SelectPersonaContent(ctx context.Context, userPrompt string) string

SelectPersonaContent selects the best persona for userPrompt and returns its raw content (the persona instructions). Returns an empty string if no persona matches, the selector is disabled, or an error occurs. The content is intended to be injected into the system prompt rather than prepended to the user message.

type Service 

type Service interface {
	pubsub.Suscriber[AgentEvent]
	Model() models.Model
	Run(ctx context.Context, sessionID string, content string, attachments ...message.Attachment) (<-chan AgentEvent, error)
	LastRunSystemMessages(sessionID string) []string
	Cancel(sessionID string)
	IsSessionBusy(sessionID string) bool
	IsBusy() bool
	Update(agentName config.AgentName, modelID models.ModelID) (models.Model, error)
	Summarize(ctx context.Context, sessionID string) error
	SetLuaManager(fm *luaengine.FilterManager)
	// GetTools returns the tools available to this agent instance.
	GetTools() []tools.BaseTool
}

func NewAgent 

func NewAgent(
	agentName config.AgentName,
	sessions session.Service,
	messages message.Service,
	agentTools []tools.BaseTool,
	skillManager *skills.SkillManager,
) (Service, error)

type SessionLLMOverrides added in v0.407.0 

type SessionLLMOverrides struct {
	ReasoningEffort string
	ThinkingMode    config.ThinkingMode
}

SessionLLMOverrides holds per-session runtime overrides that should take precedence over agent config when building a request-scoped provider.

type ToolDescription added in v0.407.0 

type ToolDescription struct {
	Name        string
	Description string
}

ToolDescription carries the minimal information the ContextTrimmer needs about each tool.

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.