tools

package
v0.0.0-...-8155ea7 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2026 License: GPL-2.0, GPL-3.0 Imports: 40 Imported by: 0

Documentation

Index

Constants

View Source 
const MaxReadFileSize = 64 * 1024 // 64KB limit to avoid context overflow
View Source 
const (
	MaxRegexPatternLength = 200
)

Variables

This section is empty.

Functions

func DelegationUserID 

func DelegationUserID(ctx context.Context) string

DelegationUserID returns the delegation partition from ctx, or "default" if unset.

func ToolChannel 

func ToolChannel(ctx context.Context) string

ToolChannel extracts the channel from ctx, or "" if unset.

func ToolChatID 

func ToolChatID(ctx context.Context) string

ToolChatID extracts the chatID from ctx, or "" if unset.

func ToolToSchema 

func ToolToSchema(tool Tool) map[string]any

func WithDelegationUserID 

func WithDelegationUserID(ctx context.Context, delegationUserID string) context.Context

WithDelegationUserID returns a child context carrying the delegation partition key (per-session / per-chat namespace for sub-agents and background tasks).

func WithToolContext 

func WithToolContext(ctx context.Context, channel, chatID string) context.Context

WithToolContext returns a child context carrying channel and chatID.

Types

type APIKeyIterator 

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

func (*APIKeyIterator) Next 

func (it *APIKeyIterator) Next() (string, bool)

type APIKeyPool 

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

func NewAPIKeyPool 

func NewAPIKeyPool(keys []string) *APIKeyPool

func (*APIKeyPool) NewIterator 

func (p *APIKeyPool) NewIterator() *APIKeyIterator

type AppendFileTool 

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

func NewAppendFileTool 

func NewAppendFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *AppendFileTool

func (*AppendFileTool) Description 

func (t *AppendFileTool) Description() string

func (*AppendFileTool) Execute 

func (t *AppendFileTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*AppendFileTool) Name 

func (t *AppendFileTool) Name() string

func (*AppendFileTool) Parameters 

func (t *AppendFileTool) Parameters() map[string]any

type AsyncCallback 

type AsyncCallback func(ctx context.Context, result *ToolResult)

AsyncCallback is a function type that async tools use to notify completion. When an async tool finishes its work, it calls this callback with the result.

The ctx parameter allows the callback to be canceled if the agent is shutting down. The result parameter contains the tool's execution result.

type AsyncExecutor 

type AsyncExecutor interface {
	Tool
	// ExecuteAsync runs the tool asynchronously. The callback cb will be
	// invoked (possibly from another goroutine) when the async operation
	// completes. cb is guaranteed to be non-nil by the caller (registry).
	ExecuteAsync(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult
}

AsyncExecutor is an optional interface that tools can implement to support asynchronous execution with completion callbacks.

Unlike the old AsyncTool pattern (SetCallback + Execute), AsyncExecutor receives the callback as a parameter of ExecuteAsync. This eliminates the data race where concurrent calls could overwrite each other's callbacks on a shared tool instance.

This is useful for:

  • Long-running operations that shouldn't block the agent loop
  • Subagent spawns that complete independently
  • Background tasks that need to report results later

Example: 

func (t *SpawnTool) ExecuteAsync(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult {
    go func() {
        result := t.runSubagent(ctx, args)
        if cb != nil { cb(ctx, result) }
    }()
    return AsyncResult("Subagent spawned, will report back")
}

type BM25SearchTool 

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

func NewBM25SearchTool 

func NewBM25SearchTool(r *ToolRegistry, ttl int, maxSearchResults int) *BM25SearchTool

func (*BM25SearchTool) Description 

func (t *BM25SearchTool) Description() string

func (*BM25SearchTool) Execute 

func (t *BM25SearchTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*BM25SearchTool) Name 

func (t *BM25SearchTool) Name() string

func (*BM25SearchTool) Parameters 

func (t *BM25SearchTool) Parameters() map[string]any

type BraveSearchProvider 

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

func (*BraveSearchProvider) Search 

func (p *BraveSearchProvider) Search(ctx context.Context, query string, count int) (string, error)

type CronTool 

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

CronTool provides scheduling capabilities for the agent

func NewCronTool 

func NewCronTool(
	cronService *cron.CronService, executor JobExecutor, msgBus *bus.MessageBus, workspace string, restrict bool,
	execTimeout time.Duration, config *config.Config,
) (*CronTool, error)

NewCronTool creates a new CronTool execTimeout: 0 means no timeout, >0 sets the timeout duration

func (*CronTool) Description 

func (t *CronTool) Description() string

Description returns the tool description

func (*CronTool) Execute 

func (t *CronTool) Execute(ctx context.Context, args map[string]any) *ToolResult

Execute runs the tool with the given arguments

func (*CronTool) ExecuteJob 

func (t *CronTool) ExecuteJob(ctx context.Context, job *cron.CronJob) string

ExecuteJob executes a cron job through the agent

func (*CronTool) Name 

func (t *CronTool) Name() string

Name returns the tool name

func (*CronTool) Parameters 

func (t *CronTool) Parameters() map[string]any

Parameters returns the tool parameters schema

type DuckDuckGoSearchProvider 

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

func (*DuckDuckGoSearchProvider) Search 

func (p *DuckDuckGoSearchProvider) Search(ctx context.Context, query string, count int) (string, error)

type EditFileTool 

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

EditFileTool edits a file by replacing old_text with new_text. The old_text must exist exactly in the file.

func NewEditFileTool 

func NewEditFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *EditFileTool

NewEditFileTool creates a new EditFileTool with optional directory restriction.

func (*EditFileTool) Description 

func (t *EditFileTool) Description() string

func (*EditFileTool) Execute 

func (t *EditFileTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*EditFileTool) Name 

func (t *EditFileTool) Name() string

func (*EditFileTool) Parameters 

func (t *EditFileTool) Parameters() map[string]any

type ExecTool 

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

func NewExecTool 

func NewExecTool(workingDir string, restrict bool) (*ExecTool, error)

func NewExecToolWithConfig 

func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Config) (*ExecTool, error)

func (*ExecTool) Description 

func (t *ExecTool) Description() string

func (*ExecTool) Execute 

func (t *ExecTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*ExecTool) Name 

func (t *ExecTool) Name() string

func (*ExecTool) Parameters 

func (t *ExecTool) Parameters() map[string]any

func (*ExecTool) SetAllowPatterns 

func (t *ExecTool) SetAllowPatterns(patterns []string) error

func (*ExecTool) SetRestrictToWorkspace 

func (t *ExecTool) SetRestrictToWorkspace(restrict bool)

func (*ExecTool) SetTimeout 

func (t *ExecTool) SetTimeout(timeout time.Duration)

type FindSkillsTool 

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

FindSkillsTool allows the LLM agent to search for installable skills from registries.

func NewFindSkillsTool 

func NewFindSkillsTool(registryMgr *skills.RegistryManager, cache *skills.SearchCache) *FindSkillsTool

NewFindSkillsTool creates a new FindSkillsTool. registryMgr is the shared registry manager (built from config in createToolRegistry). cache is the search cache for deduplicating similar queries.

func (*FindSkillsTool) Description 

func (t *FindSkillsTool) Description() string

func (*FindSkillsTool) Execute 

func (t *FindSkillsTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*FindSkillsTool) Name 

func (t *FindSkillsTool) Name() string

func (*FindSkillsTool) Parameters 

func (t *FindSkillsTool) Parameters() map[string]any

type FunctionCall 

type FunctionCall struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type GLMSearchProvider 

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

func (*GLMSearchProvider) Search 

func (p *GLMSearchProvider) Search(ctx context.Context, query string, count int) (string, error)

type HiddenToolDoc 

type HiddenToolDoc struct {
	Name        string
	Description string
}

HiddenToolDoc is a lightweight representation of a hidden tool for search indexing.

type HiddenToolSnapshot 

type HiddenToolSnapshot struct {
	Docs    []HiddenToolDoc
	Version uint64
}

HiddenToolSnapshot holds a consistent snapshot of hidden tools and the registry version at which it was taken. Used by BM25SearchTool cache.

type I2CTool 

type I2CTool struct{}

I2CTool provides I2C bus interaction for reading sensors and controlling peripherals.

func NewI2CTool 

func NewI2CTool() *I2CTool

func (*I2CTool) Description 

func (t *I2CTool) Description() string

func (*I2CTool) Execute 

func (t *I2CTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*I2CTool) Name 

func (t *I2CTool) Name() string

func (*I2CTool) Parameters 

func (t *I2CTool) Parameters() map[string]any

type InstallSkillTool 

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

InstallSkillTool allows the LLM agent to install skills from registries. It shares the same RegistryManager that FindSkillsTool uses, so all registries configured in config are available for installation.

func NewInstallSkillTool 

func NewInstallSkillTool(registryMgr *skills.RegistryManager, workspace string, shieldEngine *shield.ShieldEngine) *InstallSkillTool

NewInstallSkillTool creates a new InstallSkillTool. registryMgr is the shared registry manager (same instance as FindSkillsTool). workspace is the root workspace directory; skills install to {workspace}/skills/{slug}/. shield is the optional shield engine for threat evaluation (can be nil).

func (*InstallSkillTool) Description 

func (t *InstallSkillTool) Description() string

func (*InstallSkillTool) Execute 

func (t *InstallSkillTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*InstallSkillTool) Name 

func (t *InstallSkillTool) Name() string

func (*InstallSkillTool) Parameters 

func (t *InstallSkillTool) Parameters() map[string]any

type JobExecutor 

type JobExecutor interface {
	ProcessDirectWithChannel(ctx context.Context, content, sessionKey, channel, chatID string) (string, error)
}

JobExecutor is the interface for executing cron jobs through the agent

type LLMProvider 

type LLMProvider interface {
	Chat(
		ctx context.Context,
		messages []Message,
		tools []ToolDefinition,
		model string,
		options map[string]any,
	) (*LLMResponse, error)
	GetDefaultModel() string
}

type LLMResponse 

type LLMResponse struct {
	Content      string     `json:"content"`
	ToolCalls    []ToolCall `json:"tool_calls,omitempty"`
	FinishReason string     `json:"finish_reason"`
	Usage        *UsageInfo `json:"usage,omitempty"`
}

type ListDirTool 

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

func NewListDirTool 

func NewListDirTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *ListDirTool

func (*ListDirTool) Description 

func (t *ListDirTool) Description() string

func (*ListDirTool) Execute 

func (t *ListDirTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*ListDirTool) Name 

func (t *ListDirTool) Name() string

func (*ListDirTool) Parameters 

func (t *ListDirTool) Parameters() map[string]any

type MCPManager 

type MCPManager interface {
	CallTool(
		ctx context.Context,
		serverName, toolName string,
		arguments map[string]any,
	) (*mcp.CallToolResult, error)
}

MCPManager defines the interface for MCP manager operations This allows for easier testing with mock implementations

type MCPTool 

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

MCPTool wraps an MCP tool to implement the Tool interface

func NewMCPTool 

func NewMCPTool(manager MCPManager, serverName string, tool *mcp.Tool) *MCPTool

NewMCPTool creates a new MCP tool wrapper

func (*MCPTool) Description 

func (t *MCPTool) Description() string

Description returns the tool description

func (*MCPTool) Execute 

func (t *MCPTool) Execute(ctx context.Context, args map[string]any) *ToolResult

Execute executes the MCP tool

func (*MCPTool) Name 

func (t *MCPTool) Name() string

Name returns the tool name, prefixed with the server name. The total length is capped at 64 characters (OpenAI-compatible API limit). A short hash of the original (unsanitized) server and tool names is appended whenever sanitization is lossy or the name is truncated, ensuring that two names which differ only in disallowed characters remain distinct after sanitization.

func (*MCPTool) Parameters 

func (t *MCPTool) Parameters() map[string]any

Parameters returns the tool parameters schema

type MemoryTool 

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

MemoryTool allows the agent to record and search memories

func NewMemoryTool 

func NewMemoryTool(provider MemoryToolProvider) *MemoryTool

NewMemoryTool creates a new memory tool

func (*MemoryTool) Description 

func (t *MemoryTool) Description() string

func (*MemoryTool) Execute 

func (t *MemoryTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*MemoryTool) Name 

func (t *MemoryTool) Name() string

func (*MemoryTool) Parameters 

func (t *MemoryTool) Parameters() map[string]any

type MemoryToolProvider 

type MemoryToolProvider interface {
	GetAdaptiveMemory() *adaptive_memory.Engine
}

MemoryToolProvider interface for memory tool dependency injection

type Message 

type Message struct {
	Role       string     `json:"role"`
	Content    string     `json:"content"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

type MessageTool 

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

func NewMessageTool 

func NewMessageTool() *MessageTool

func (*MessageTool) Description 

func (t *MessageTool) Description() string

func (*MessageTool) Execute 

func (t *MessageTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*MessageTool) HasSentInRound 

func (t *MessageTool) HasSentInRound() bool

HasSentInRound returns true if the message tool sent a message during the current round.

func (*MessageTool) Name 

func (t *MessageTool) Name() string

func (*MessageTool) Parameters 

func (t *MessageTool) Parameters() map[string]any

func (*MessageTool) ResetSentInRound 

func (t *MessageTool) ResetSentInRound()

ResetSentInRound resets the per-round send tracker. Called by the agent loop at the start of each inbound message processing round.

func (*MessageTool) SetSendCallback 

func (t *MessageTool) SetSendCallback(callback SendCallback)

type PerplexitySearchProvider 

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

func (*PerplexitySearchProvider) Search 

func (p *PerplexitySearchProvider) Search(ctx context.Context, query string, count int) (string, error)

type ReadFileTool 

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

func NewReadFileTool 

func NewReadFileTool(
	workspace string,
	restrict bool,
	maxReadFileSize int,
	allowPaths ...[]*regexp.Regexp,
) *ReadFileTool

func (*ReadFileTool) Description 

func (t *ReadFileTool) Description() string

func (*ReadFileTool) Execute 

func (t *ReadFileTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*ReadFileTool) Name 

func (t *ReadFileTool) Name() string

func (*ReadFileTool) Parameters 

func (t *ReadFileTool) Parameters() map[string]any

type RegexSearchTool 

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

func NewRegexSearchTool 

func NewRegexSearchTool(r *ToolRegistry, ttl int, maxSearchResults int) *RegexSearchTool

func (*RegexSearchTool) Description 

func (t *RegexSearchTool) Description() string

func (*RegexSearchTool) Execute 

func (t *RegexSearchTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*RegexSearchTool) Name 

func (t *RegexSearchTool) Name() string

func (*RegexSearchTool) Parameters 

func (t *RegexSearchTool) Parameters() map[string]any

type SPITool 

type SPITool struct{}

SPITool provides SPI bus interaction for high-speed peripheral communication.

func NewSPITool 

func NewSPITool() *SPITool

func (*SPITool) Description 

func (t *SPITool) Description() string

func (*SPITool) Execute 

func (t *SPITool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*SPITool) Name 

func (t *SPITool) Name() string

func (*SPITool) Parameters 

func (t *SPITool) Parameters() map[string]any

type SearXNGSearchProvider 

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

func (*SearXNGSearchProvider) Search 

func (p *SearXNGSearchProvider) Search(ctx context.Context, query string, count int) (string, error)

type SearchProvider 

type SearchProvider interface {
	Search(ctx context.Context, query string, count int) (string, error)
}

type SendCallback 

type SendCallback func(channel, chatID, content string) error

type SendFileTool 

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

SendFileTool allows the LLM to send a local file (image, document, etc.) to the user on the current chat channel via the MediaStore pipeline.

func NewSendFileTool 

func NewSendFileTool(workspace string, restrict bool, maxFileSize int, store media.MediaStore) *SendFileTool

func (*SendFileTool) Description 

func (t *SendFileTool) Description() string

func (*SendFileTool) Execute 

func (t *SendFileTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*SendFileTool) Name 

func (t *SendFileTool) Name() string

func (*SendFileTool) Parameters 

func (t *SendFileTool) Parameters() map[string]any

func (*SendFileTool) SetContext 

func (t *SendFileTool) SetContext(channel, chatID string)

func (*SendFileTool) SetMediaStore 

func (t *SendFileTool) SetMediaStore(store media.MediaStore)

type ShieldAction 

type ShieldAction string

ShieldAction represents the enforcement action. 

const (
	ActionBlock           ShieldAction = "block"
	ActionRequireApproval ShieldAction = "require_approval"
	ActionLog             ShieldAction = "log"
)

type ShieldDecision 

type ShieldDecision struct {
	Action     ShieldAction `json:"action"`
	Scope      ShieldScope  `json:"scope"`
	ThreatID   string       `json:"threat_id,omitempty"`
	Reason     string       `json:"reason"`
	MatchedOn  string       `json:"matched_on,omitempty"`
	MatchValue string       `json:"match_value,omitempty"`
}

ShieldDecision represents the enforcement decision.

type ShieldEvaluator 

type ShieldEvaluator interface {
	IsActive() bool
	Evaluate(event ShieldEvent) ShieldDecision
}

ShieldEvaluator is an interface for shield evaluation (to avoid circular import).

func NewShieldEvaluatorFromEngine 

func NewShieldEvaluatorFromEngine(eng *shield.ShieldEngine) ShieldEvaluator

NewShieldEvaluatorFromEngine returns a ShieldEvaluator backed by eng, or nil if eng is nil.

type ShieldEvent 

type ShieldEvent struct {
	Scope     ShieldScope    `json:"scope"`
	ToolName  string         `json:"tool_name,omitempty"`
	ToolArgs  map[string]any `json:"tool_args,omitempty"`
	Domain    string         `json:"domain,omitempty"`
	URL       string         `json:"url,omitempty"`
	SkillName string         `json:"skill_name,omitempty"`
}

ShieldEvent represents an event for shield evaluation.

type ShieldScope 

type ShieldScope string

ShieldScope represents the event scope. 

const (
	ScopeToolCall      ShieldScope = "tool.call"
	ScopeSkillInstall  ShieldScope = "skill.install"
	ScopeSkillExecute  ShieldScope = "skill.execute"
	ScopeNetworkEgress ShieldScope = "network.egress"
	ScopeSecretsRead   ShieldScope = "secrets.read"
	ScopePrompt        ShieldScope = "prompt"
)

type SpawnTool 

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

func NewSpawnTool 

func NewSpawnTool(manager *SubagentManager) *SpawnTool

func (*SpawnTool) Description 

func (t *SpawnTool) Description() string

func (*SpawnTool) Execute 

func (t *SpawnTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*SpawnTool) ExecuteAsync 

func (t *SpawnTool) ExecuteAsync(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult

ExecuteAsync implements AsyncExecutor. The callback is passed through to the subagent manager as a call parameter — never stored on the SpawnTool instance.

func (*SpawnTool) Name 

func (t *SpawnTool) Name() string

func (*SpawnTool) Parameters 

func (t *SpawnTool) Parameters() map[string]any

func (*SpawnTool) SetAllowlistChecker 

func (t *SpawnTool) SetAllowlistChecker(check func(targetAgentID string) bool)

type SubagentManager 

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

func NewSubagentManager 

func NewSubagentManager(
	provider providers.LLMProvider,
	defaultModel, workspace string,
) *SubagentManager

func (*SubagentManager) GetTask 

func (sm *SubagentManager) GetTask(taskID string) (*SubagentTask, bool)

func (*SubagentManager) ListTasks 

func (sm *SubagentManager) ListTasks() []*SubagentTask

func (*SubagentManager) RegisterTool 

func (sm *SubagentManager) RegisterTool(tool Tool)

RegisterTool registers a tool for subagent execution.

func (*SubagentManager) SetLLMOptions 

func (sm *SubagentManager) SetLLMOptions(maxTokens int, temperature float64)

SetLLMOptions sets max tokens and temperature for subagent LLM calls.

func (*SubagentManager) SetTools 

func (sm *SubagentManager) SetTools(tools *ToolRegistry)

SetTools sets the tool registry for subagent execution. If not set, subagent will have access to the provided tools.

func (*SubagentManager) Spawn 

func (sm *SubagentManager) Spawn(
	ctx context.Context,
	task, label, agentID, originChannel, originChatID string,
	callback AsyncCallback,
) (string, error)

type SubagentTask 

type SubagentTask struct {
	ID            string
	Task          string
	Label         string
	AgentID       string
	OriginChannel string
	OriginChatID  string
	Status        string
	Result        string
	Created       int64
}

type SubagentTool 

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

SubagentTool executes a subagent task synchronously and returns the result. Unlike SpawnTool which runs tasks asynchronously, SubagentTool waits for completion and returns the result directly in the ToolResult.

func NewSubagentTool 

func NewSubagentTool(manager *SubagentManager) *SubagentTool

func (*SubagentTool) Description 

func (t *SubagentTool) Description() string

func (*SubagentTool) Execute 

func (t *SubagentTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*SubagentTool) Name 

func (t *SubagentTool) Name() string

func (*SubagentTool) Parameters 

func (t *SubagentTool) Parameters() map[string]any

type TavilySearchProvider 

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

func (*TavilySearchProvider) Search 

func (p *TavilySearchProvider) Search(ctx context.Context, query string, count int) (string, error)

type Tool 

type Tool interface {
	Name() string
	Description() string
	Parameters() map[string]any
	Execute(ctx context.Context, args map[string]any) *ToolResult
}

Tool is the interface that all tools must implement.

type ToolCall 

type ToolCall struct {
	ID        string         `json:"id"`
	Type      string         `json:"type"`
	Function  *FunctionCall  `json:"function,omitempty"`
	Name      string         `json:"name,omitempty"`
	Arguments map[string]any `json:"arguments,omitempty"`
}

type ToolDefinition 

type ToolDefinition struct {
	Type     string                 `json:"type"`
	Function ToolFunctionDefinition `json:"function"`
}

type ToolEntry 

type ToolEntry struct {
	Tool   Tool
	IsCore bool
	TTL    int
}

type ToolFunctionDefinition 

type ToolFunctionDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters"`
}

type ToolLoopConfig 

type ToolLoopConfig struct {
	Provider      providers.LLMProvider
	Model         string
	Tools         *ToolRegistry
	MaxIterations int
	LLMOptions    map[string]any
}

ToolLoopConfig configures the tool execution loop.

type ToolLoopResult 

type ToolLoopResult struct {
	Content    string
	Iterations int
}

ToolLoopResult contains the result of running the tool loop.

func RunToolLoop 

func RunToolLoop(
	ctx context.Context,
	config ToolLoopConfig,
	messages []providers.Message,
	channel, chatID string,
) (*ToolLoopResult, error)

RunToolLoop executes the LLM + tool call iteration loop. This is the core agent logic that can be reused by both main agent and subagents.

type ToolRegistry 

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

func NewToolRegistry 

func NewToolRegistry() *ToolRegistry

func (*ToolRegistry) Count 

func (r *ToolRegistry) Count() int

Count returns the number of registered tools.

func (*ToolRegistry) Execute 

func (r *ToolRegistry) Execute(ctx context.Context, name string, args map[string]any) *ToolResult

func (*ToolRegistry) ExecuteWithContext 

func (r *ToolRegistry) ExecuteWithContext(
	ctx context.Context,
	name string,
	args map[string]any,
	channel, chatID, delegationUserID string,
	asyncCallback AsyncCallback,
) *ToolResult

ExecuteWithContext executes a tool with channel/chatID/delegationUserID context and optional async callback. If the tool implements AsyncExecutor and a non-nil callback is provided, ExecuteAsync is called instead of Execute — the callback is a parameter, never stored as mutable state on the tool.

func (*ToolRegistry) Get 

func (r *ToolRegistry) Get(name string) (Tool, bool)

func (*ToolRegistry) GetDefinitions 

func (r *ToolRegistry) GetDefinitions() []map[string]any

func (*ToolRegistry) GetSummaries 

func (r *ToolRegistry) GetSummaries() []string

GetSummaries returns human-readable summaries of all registered tools. Returns a slice of "name - description" strings.

func (*ToolRegistry) List 

func (r *ToolRegistry) List() []string

List returns a list of all registered tool names.

func (*ToolRegistry) MergeFrom 

func (r *ToolRegistry) MergeFrom(src *ToolRegistry)

MergeFrom copies all tools from the source registry into this registry. Used to merge plugin tools into agent registries. Skips tools already present.

func (*ToolRegistry) PromoteTools 

func (r *ToolRegistry) PromoteTools(names []string, ttl int)

PromoteTools atomically sets the TTL for multiple non-core tools. This prevents a concurrent TickTTL from decrementing between promotions.

func (*ToolRegistry) Register 

func (r *ToolRegistry) Register(tool Tool)

func (*ToolRegistry) RegisterHidden 

func (r *ToolRegistry) RegisterHidden(tool Tool)

RegisterHidden saves hidden tools (visible only via TTL)

func (*ToolRegistry) SearchBM25 

func (r *ToolRegistry) SearchBM25(query string, maxSearchResults int) []ToolSearchResult

SearchBM25 ranks hidden tools against query using BM25 via utils.BM25Engine. This non-cached variant rebuilds the engine on every call. Used by tests and any code that doesn't hold a BM25SearchTool instance.

func (*ToolRegistry) SearchRegex 

func (r *ToolRegistry) SearchRegex(pattern string, maxSearchResults int) ([]ToolSearchResult, error)

func (*ToolRegistry) SnapshotHiddenTools 

func (r *ToolRegistry) SnapshotHiddenTools() HiddenToolSnapshot

SnapshotHiddenTools returns all non-core tools and the current registry version under a single read-lock, guaranteeing consistency between the two values.

func (*ToolRegistry) TickTTL 

func (r *ToolRegistry) TickTTL()

TickTTL decreases TTL only for non-core tools

func (*ToolRegistry) ToProviderDefs 

func (r *ToolRegistry) ToProviderDefs() []providers.ToolDefinition

ToProviderDefs converts tool definitions to provider-compatible format. This is the format expected by LLM provider APIs.

func (*ToolRegistry) Version 

func (r *ToolRegistry) Version() uint64

Version returns the current registry version (atomically).

type ToolResult 

type ToolResult struct {
	// ForLLM is the content sent to the LLM for context.
	// Required for all results.
	ForLLM string `json:"for_llm"`

	// ForUser is the content sent directly to the user.
	// If empty, no user message is sent.
	// Silent=true overrides this field.
	ForUser string `json:"for_user,omitempty"`

	// Silent suppresses sending any message to the user.
	// When true, ForUser is ignored even if set.
	Silent bool `json:"silent"`

	// IsError indicates whether the tool execution failed.
	// When true, the result should be treated as an error.
	IsError bool `json:"is_error"`

	// Async indicates whether the tool is running asynchronously.
	// When true, the tool will complete later and notify via callback.
	Async bool `json:"async"`

	// RequiresApproval indicates that this tool result needs user approval.
	// When true, the agent should handle the approval flow before proceeding.
	RequiresApproval bool `json:"requires_approval,omitempty"`

	// Err is the underlying error (not JSON serialized).
	// Used for internal error handling and logging.
	Err error `json:"-"`

	// Media contains media store refs produced by this tool.
	// When non-empty, the agent will publish these as OutboundMediaMessage.
	Media []string `json:"media,omitempty"`
}

ToolResult represents the structured return value from tool execution. It provides clear semantics for different types of results and supports async operations, user-facing messages, and error handling.

func AsyncResult 

func AsyncResult(forLLM string) *ToolResult

AsyncResult creates a ToolResult for async operations. The task will run in the background and complete later.

Use this for long-running operations like: - Subagent spawns - Background processing - External API calls with callbacks

Example: 

result := AsyncResult("Subagent spawned, will report back")

func ErrorResult 

func ErrorResult(message string) *ToolResult

ErrorResult creates a ToolResult representing an error. Sets IsError=true and includes the error message.

Example: 

result := ErrorResult("Failed to connect to database: connection refused")

func MediaResult 

func MediaResult(forLLM string, mediaRefs []string) *ToolResult

MediaResult creates a ToolResult with media refs for the user. The agent will publish these refs as OutboundMediaMessage.

Example: 

result := MediaResult("Image generated successfully", []string{"media://abc123"})

func NewToolResult 

func NewToolResult(forLLM string) *ToolResult

NewToolResult creates a basic ToolResult with content for the LLM. Use this when you need a simple result with default behavior.

Example: 

result := NewToolResult("File updated successfully")

func SilentResult 

func SilentResult(forLLM string) *ToolResult

SilentResult creates a ToolResult that is silent (no user message). The content is only sent to the LLM for context.

Use this for operations that should not spam the user, such as: - File reads/writes - Status updates - Background operations

Example: 

result := SilentResult("Config file saved")

func UserResult 

func UserResult(content string) *ToolResult

UserResult creates a ToolResult with content for both LLM and user. Both ForLLM and ForUser are set to the same content.

Use this when the user needs to see the result directly: - Command execution output - Fetched web content - Query results

Example: 

result := UserResult("Total files found: 42")

func (*ToolResult) MarshalJSON 

func (tr *ToolResult) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON serialization. The Err field is excluded from JSON output via the json:"-" tag.

func (*ToolResult) WithError 

func (tr *ToolResult) WithError(err error) *ToolResult

WithError sets the Err field and returns the result for chaining. This preserves the error for logging while keeping it out of JSON.

Example: 

result := ErrorResult("Operation failed").WithError(err)

type ToolSearchResult 

type ToolSearchResult struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

ToolSearchResult represents the result returned to the LLM. Parameters are omitted from the JSON response to save context tokens; the LLM will see full schemas via ToProviderDefs after promotion.

type UsageInfo 

type UsageInfo struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type WebFetchTool 

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

func NewWebFetchTool 

func NewWebFetchTool(maxChars int, fetchLimitBytes int64) (*WebFetchTool, error)

func NewWebFetchToolWithProxy 

func NewWebFetchToolWithProxy(maxChars int, proxy string, fetchLimitBytes int64) (*WebFetchTool, error)

func (*WebFetchTool) Description 

func (t *WebFetchTool) Description() string

func (*WebFetchTool) Execute 

func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*WebFetchTool) Name 

func (t *WebFetchTool) Name() string

func (*WebFetchTool) Parameters 

func (t *WebFetchTool) Parameters() map[string]any

func (*WebFetchTool) WithShield 

func (t *WebFetchTool) WithShield(shield ShieldEvaluator) *WebFetchTool

WithShield sets the shield evaluator for the tool.

type WebSearchTool 

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

func NewWebSearchTool 

func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error)

func (*WebSearchTool) Description 

func (t *WebSearchTool) Description() string

func (*WebSearchTool) Execute 

func (t *WebSearchTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*WebSearchTool) Name 

func (t *WebSearchTool) Name() string

func (*WebSearchTool) Parameters 

func (t *WebSearchTool) Parameters() map[string]any

type WebSearchToolOptions 

type WebSearchToolOptions struct {
	BraveAPIKeys         []string
	BraveMaxResults      int
	BraveEnabled         bool
	TavilyAPIKeys        []string
	TavilyBaseURL        string
	TavilyMaxResults     int
	TavilyEnabled        bool
	DuckDuckGoMaxResults int
	DuckDuckGoEnabled    bool
	PerplexityAPIKeys    []string
	PerplexityMaxResults int
	PerplexityEnabled    bool
	SearXNGBaseURL       string
	SearXNGMaxResults    int
	SearXNGEnabled       bool
	GLMSearchAPIKey      string
	GLMSearchBaseURL     string
	GLMSearchEngine      string
	GLMSearchMaxResults  int
	GLMSearchEnabled     bool
	Proxy                string
}

type WriteFileTool 

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

func NewWriteFileTool 

func NewWriteFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *WriteFileTool

func (*WriteFileTool) Description 

func (t *WriteFileTool) Description() string

func (*WriteFileTool) Execute 

func (t *WriteFileTool) Execute(ctx context.Context, args map[string]any) *ToolResult

func (*WriteFileTool) Name 

func (t *WriteFileTool) Name() string

func (*WriteFileTool) Parameters 

func (t *WriteFileTool) Parameters() map[string]any

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.