tools

package
v0.0.0-...-4bd36a1 Latest Latest
Warning

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

 Go to latest Published: Mar 26, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

NemesisBot - AI agent License: MIT Copyright (c) 2026 NemesisBot contributors

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ToolToSchema 

func ToolToSchema(tool Tool) map[string]interface{}

ToolToSchema converts a Tool to its OpenAI function calling schema format. This schema is used by LLM providers to understand available tools.

The returned schema has the following structure: 

{
  "type": "function",
  "function": {
    "name": "tool_name",
    "description": "Tool description",
    "parameters": {/* JSON Schema */}
  }
}

Parameters:

  • tool: The tool to convert

Returns: 

A map representing the tool schema in OpenAI function calling format

Types

type AppendFileTool 

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

func NewAppendFileTool 

func NewAppendFileTool(workspace string, restrict bool) *AppendFileTool

func (*AppendFileTool) Description 

func (t *AppendFileTool) Description() string

func (*AppendFileTool) Execute 

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

func (*AppendFileTool) Name 

func (t *AppendFileTool) Name() string

func (*AppendFileTool) Parameters 

func (t *AppendFileTool) Parameters() map[string]interface{}

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.

Example usage in an async tool: 

func (t *MyAsyncTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult {
    // Start async work in background
    go func() {
        result := doAsyncWork()
        if t.callback != nil {
            t.callback(ctx, result)
        }
    }()
    return AsyncResult("Async task started")
}

type AsyncExecTool 

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

AsyncExecTool executes commands asynchronously (starts them and returns quickly)

func NewAsyncExecTool 

func NewAsyncExecTool(workingDir string, restrict bool) *AsyncExecTool

NewAsyncExecTool creates a new AsyncExecTool

func NewAsyncExecToolWithConfig 

func NewAsyncExecToolWithConfig(workingDir string, restrict bool, config *config.Config) *AsyncExecTool

NewAsyncExecToolWithConfig creates a new AsyncExecTool with custom configuration

func (*AsyncExecTool) Description 

func (t *AsyncExecTool) Description() string

func (*AsyncExecTool) Execute 

func (t *AsyncExecTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult

func (*AsyncExecTool) Name 

func (t *AsyncExecTool) Name() string

func (*AsyncExecTool) Parameters 

func (t *AsyncExecTool) Parameters() map[string]interface{}

func (*AsyncExecTool) SetAllowPatterns 

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

func (*AsyncExecTool) SetDefaultWaitTime 

func (t *AsyncExecTool) SetDefaultWaitTime(waitTime time.Duration)

func (*AsyncExecTool) SetRestrictToWorkspace 

func (t *AsyncExecTool) SetRestrictToWorkspace(restrict bool)

type AsyncTool 

type AsyncTool interface {
	Tool
	// SetCallback registers a callback function to be invoked when the async operation completes.
	// The callback will be called from a goroutine and should handle thread-safety if needed.
	SetCallback(cb AsyncCallback)
}

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

Async tools return immediately with an AsyncResult, then notify completion via the callback set by SetCallback.

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: 

type SpawnTool struct {
    callback AsyncCallback
}

func (t *SpawnTool) SetCallback(cb AsyncCallback) {
    t.callback = cb
}

func (t *SpawnTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult {
    go t.runSubagent(ctx, args)
    return AsyncResult("Subagent spawned, will report back")
}

type BootstrapCompleter 

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

BootstrapCompleter handles completion of bootstrap initialization

func NewCompleteBootstrapTool 

func NewCompleteBootstrapTool(workspace string) *BootstrapCompleter

NewCompleteBootstrapTool creates a tool for completing bootstrap initialization

func (*BootstrapCompleter) Description 

func (bc *BootstrapCompleter) Description() string

Description implements the Tool interface

func (*BootstrapCompleter) Execute 

func (bc *BootstrapCompleter) Execute(ctx context.Context, args map[string]interface{}) *ToolResult

Execute implements the Tool interface

func (*BootstrapCompleter) Name 

func (bc *BootstrapCompleter) Name() string

Name implements the Tool interface

func (*BootstrapCompleter) Parameters 

func (bc *BootstrapCompleter) Parameters() map[string]interface{}

Parameters implements the Tool interface

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 ClusterRPCTool 

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

ClusterRPCTool enables agents to make RPC calls to other bots in the cluster

func NewClusterRPCTool 

func NewClusterRPCTool(cluster *cluster.Cluster) *ClusterRPCTool

NewClusterRPCTool creates a new cluster RPC tool

func (*ClusterRPCTool) Description 

func (t *ClusterRPCTool) Description() string

Description returns the tool description

func (*ClusterRPCTool) Execute 

func (t *ClusterRPCTool) Execute(ctx context.Context, params map[string]interface{}) *ToolResult

Execute executes the cluster RPC tool

func (*ClusterRPCTool) GetAvailablePeers 

func (t *ClusterRPCTool) GetAvailablePeers(ctx context.Context) (string, error)

GetAvailablePeers returns information about available peers

func (*ClusterRPCTool) GetCapabilities 

func (t *ClusterRPCTool) GetCapabilities(ctx context.Context) (string, error)

GetCapabilities returns all available capabilities in the cluster

func (*ClusterRPCTool) Name 

func (t *ClusterRPCTool) Name() string

Name returns the tool name

func (*ClusterRPCTool) Parameters 

func (t *ClusterRPCTool) Parameters() map[string]interface{}

Parameters returns the tool parameters schema

type ContextualTool 

type ContextualTool interface {
	Tool
	SetContext(channel, chatID string)
}

ContextualTool is an optional interface that tools can implement to receive the current message context (channel, chatID)

type CreateDirTool 

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

CreateDirTool creates a directory

func NewCreateDirTool 

func NewCreateDirTool(workspace string, restrict bool) *CreateDirTool

NewCreateDirTool creates a new directory creation tool

func (*CreateDirTool) Description 

func (t *CreateDirTool) Description() string

func (*CreateDirTool) Execute 

func (t *CreateDirTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult

func (*CreateDirTool) Name 

func (t *CreateDirTool) Name() string

func (*CreateDirTool) Parameters 

func (t *CreateDirTool) Parameters() map[string]interface{}

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

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]interface{}) *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]interface{}

Parameters returns the tool parameters schema

func (*CronTool) SetContext 

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

SetContext sets the current session context for job creation

type DeleteDirTool 

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

DeleteDirTool deletes a directory

func NewDeleteDirTool 

func NewDeleteDirTool(workspace string, restrict bool) *DeleteDirTool

NewDeleteDirTool creates a new directory deletion tool

func (*DeleteDirTool) Description 

func (t *DeleteDirTool) Description() string

func (*DeleteDirTool) Execute 

func (t *DeleteDirTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult

func (*DeleteDirTool) Name 

func (t *DeleteDirTool) Name() string

func (*DeleteDirTool) Parameters 

func (t *DeleteDirTool) Parameters() map[string]interface{}

type DeleteFileTool 

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

DeleteFileTool deletes a file

func NewDeleteFileTool 

func NewDeleteFileTool(workspace string, restrict bool) *DeleteFileTool

NewDeleteFileTool creates a new file deletion tool

func (*DeleteFileTool) Description 

func (t *DeleteFileTool) Description() string

func (*DeleteFileTool) Execute 

func (t *DeleteFileTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult

func (*DeleteFileTool) Name 

func (t *DeleteFileTool) Name() string

func (*DeleteFileTool) Parameters 

func (t *DeleteFileTool) Parameters() map[string]interface{}

type DuckDuckGoSearchProvider 

type DuckDuckGoSearchProvider struct{}

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(allowedDir string, restrict bool) *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]interface{}) *ToolResult

func (*EditFileTool) Name 

func (t *EditFileTool) Name() string

func (*EditFileTool) Parameters 

func (t *EditFileTool) Parameters() map[string]interface{}

type ExecTool 

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

func NewExecTool 

func NewExecTool(workingDir string, restrict bool) *ExecTool

func NewExecToolWithConfig 

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

func (*ExecTool) Description 

func (t *ExecTool) Description() string

func (*ExecTool) Execute 

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

func (*ExecTool) Name 

func (t *ExecTool) Name() string

func (*ExecTool) Parameters 

func (t *ExecTool) Parameters() map[string]interface{}

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 is a tool that searches for available skills from configured registries.

func NewFindSkillsTool 

func NewFindSkillsTool(registryManager *skills.RegistryManager, searchCache *skills.SearchCache) *FindSkillsTool

NewFindSkillsTool creates a new find_skills tool.

func (*FindSkillsTool) Description 

func (t *FindSkillsTool) Description() string

Description returns the tool description.

func (*FindSkillsTool) Execute 

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

Execute executes the find_skills tool.

func (*FindSkillsTool) Name 

func (t *FindSkillsTool) Name() string

Name returns the tool name.

func (*FindSkillsTool) ParameterSchema 

func (t *FindSkillsTool) ParameterSchema() map[string]interface{}

ParameterSchema returns the tool's parameter schema.

type FunctionCall 

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

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]interface{}) *ToolResult

func (*I2CTool) Name 

func (t *I2CTool) Name() string

func (*I2CTool) Parameters 

func (t *I2CTool) Parameters() map[string]interface{}

type InstallSkillTool 

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

InstallSkillTool is a tool that installs a skill from a configured registry.

func NewInstallSkillTool 

func NewInstallSkillTool(registryManager *skills.RegistryManager, installer *skills.SkillInstaller) *InstallSkillTool

NewInstallSkillTool creates a new install_skill tool.

func (*InstallSkillTool) Description 

func (t *InstallSkillTool) Description() string

Description returns the tool description.

func (*InstallSkillTool) Execute 

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

Execute executes the install_skill tool.

func (*InstallSkillTool) Name 

func (t *InstallSkillTool) Name() string

Name returns the tool name.

func (*InstallSkillTool) ParameterSchema 

func (t *InstallSkillTool) ParameterSchema() map[string]interface{}

ParameterSchema returns the tool's parameter schema.

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]interface{}) (*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) *ListDirTool

NewListDirTool creates a new directory listing tool. It restricts directory access to the specified workspace for security.

Parameters:

  • workspace: The base directory for file operations. If empty, no restrictions apply.
  • restrict: If true, only directories within the workspace can be listed.

Returns: 

A configured ListDirTool ready for use.

Security:

  • When restrict is true, symbolic links are resolved to prevent escape attacks
  • Lists both files and directories with metadata

func (*ListDirTool) Description 

func (t *ListDirTool) Description() string

func (*ListDirTool) Execute 

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

func (*ListDirTool) Name 

func (t *ListDirTool) Name() string

func (*ListDirTool) Parameters 

func (t *ListDirTool) Parameters() map[string]interface{}

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]interface{}) *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]interface{}

func (*MessageTool) SetContext 

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

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 PluginableTool 

type PluginableTool struct {
	Tool Tool
	// contains filtered or unexported fields
}

PluginableTool wraps a Tool to add plugin support

func (*PluginableTool) Description 

func (p *PluginableTool) Description() string

Description returns the tool description

func (*PluginableTool) Execute 

func (p *PluginableTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult

Execute executes the tool with plugin interception

func (*PluginableTool) Name 

func (p *PluginableTool) Name() string

Name returns the tool name

func (*PluginableTool) Parameters 

func (p *PluginableTool) Parameters() map[string]interface{}

Parameters returns the tool parameters

type ReadFileTool 

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

func NewReadFileTool 

func NewReadFileTool(workspace string, restrict bool) *ReadFileTool

NewReadFileTool creates a new file reading tool. It restricts file access to the specified workspace for security.

Parameters:

  • workspace: The base directory for file operations. If empty, no restrictions apply.
  • restrict: If true, only files within the workspace can be accessed.

Returns: 

A configured ReadFileTool ready for use.

Security:

  • When restrict is true, symbolic links are resolved to prevent escape attacks
  • Absolute paths outside workspace are denied
  • Relative paths are resolved against the workspace

func (*ReadFileTool) Description 

func (t *ReadFileTool) Description() string

func (*ReadFileTool) Execute 

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

func (*ReadFileTool) Name 

func (t *ReadFileTool) Name() string

func (*ReadFileTool) Parameters 

func (t *ReadFileTool) Parameters() map[string]interface{}

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]interface{}) *ToolResult

func (*SPITool) Name 

func (t *SPITool) Name() string

func (*SPITool) Parameters 

func (t *SPITool) Parameters() map[string]interface{}

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 SleepTool 

type SleepTool struct{}

SleepTool suspends execution for a specified duration. This is a simple utility tool for testing and debugging purposes.

func NewSleepTool 

func NewSleepTool() *SleepTool

func (*SleepTool) Description 

func (t *SleepTool) Description() string

func (*SleepTool) Execute 

func (t *SleepTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult

func (*SleepTool) Name 

func (t *SleepTool) Name() string

func (*SleepTool) Parameters 

func (t *SleepTool) Parameters() map[string]interface{}

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]interface{}) *ToolResult

func (*SpawnTool) Name 

func (t *SpawnTool) Name() string

func (*SpawnTool) Parameters 

func (t *SpawnTool) Parameters() map[string]interface{}

func (*SpawnTool) SetAllowlistChecker 

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

func (*SpawnTool) SetCallback 

func (t *SpawnTool) SetCallback(cb AsyncCallback)

SetCallback implements AsyncTool interface for async completion notification

func (*SpawnTool) SetContext 

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

type SubagentManager 

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

func NewSubagentManager 

func NewSubagentManager(provider providers.LLMProvider, defaultModel, workspace string, bus *bus.MessageBus) *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) 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]interface{}) *ToolResult

func (*SubagentTool) Name 

func (t *SubagentTool) Name() string

func (*SubagentTool) Parameters 

func (t *SubagentTool) Parameters() map[string]interface{}

func (*SubagentTool) SetContext 

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

type Tool 

type Tool interface {
	Name() string
	Description() string
	Parameters() map[string]interface{}
	Execute(ctx context.Context, args map[string]interface{}) *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]interface{} `json:"arguments,omitempty"`
}

type ToolDefinition 

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

type ToolFunctionDefinition 

type ToolFunctionDefinition struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description"`
	Parameters  map[string]interface{} `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

NewToolRegistry creates a new empty tool registry. The registry is thread-safe and can be used to manage tool lifecycle.

Returns: 

A new ToolRegistry instance ready to register and execute tools.

Example: 

registry := NewToolRegistry()
registry.Register(NewReadFileTool("/workspace", true))
result := registry.Execute(ctx, "read_file", map[string]interface{}{"path": "file.txt"})

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]interface{}) *ToolResult

func (*ToolRegistry) ExecuteWithContext 

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

ExecuteWithContext executes a tool with channel/chatID context and optional async callback. If the tool implements AsyncTool and a non-nil callback is provided, the callback will be set on the tool before execution.

func (*ToolRegistry) Get 

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

func (*ToolRegistry) GetDefinitions 

func (r *ToolRegistry) GetDefinitions() []map[string]interface{}

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) Register 

func (r *ToolRegistry) Register(tool Tool)

func (*ToolRegistry) RegisterWithPlugin 

func (r *ToolRegistry) RegisterWithPlugin(tool Tool, pluginMgr *plugin.Manager, user, source, workspace string)

RegisterWithPlugin registers a tool with plugin support. The tool will be wrapped to allow plugins to intercept its execution.

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.

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"`

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

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 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 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) *WebFetchTool

func (*WebFetchTool) Description 

func (t *WebFetchTool) Description() string

func (*WebFetchTool) Execute 

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

func (*WebFetchTool) Name 

func (t *WebFetchTool) Name() string

func (*WebFetchTool) Parameters 

func (t *WebFetchTool) Parameters() map[string]interface{}

type WebSearchTool 

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

func NewWebSearchTool 

func NewWebSearchTool(opts WebSearchToolOptions) *WebSearchTool

func (*WebSearchTool) Description 

func (t *WebSearchTool) Description() string

func (*WebSearchTool) Execute 

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

func (*WebSearchTool) Name 

func (t *WebSearchTool) Name() string

func (*WebSearchTool) Parameters 

func (t *WebSearchTool) Parameters() map[string]interface{}

type WebSearchToolOptions 

type WebSearchToolOptions struct {
	BraveAPIKey          string
	BraveMaxResults      int
	BraveEnabled         bool
	DuckDuckGoMaxResults int
	DuckDuckGoEnabled    bool
	PerplexityAPIKey     string
	PerplexityMaxResults int
	PerplexityEnabled    bool
}

type WriteFileTool 

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

func NewWriteFileTool 

func NewWriteFileTool(workspace string, restrict bool) *WriteFileTool

NewWriteFileTool creates a new file writing tool. It restricts file access to the specified workspace for security.

Parameters:

  • workspace: The base directory for file operations. If empty, no restrictions apply.
  • restrict: If true, only files within the workspace can be written.

Returns: 

A configured WriteFileTool ready for use.

Security:

  • When restrict is true, symbolic links are resolved to prevent escape attacks
  • Creates parent directories if they don't exist
  • Files are written with permissions 0644

func (*WriteFileTool) Description 

func (t *WriteFileTool) Description() string

func (*WriteFileTool) Execute 

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

func (*WriteFileTool) Name 

func (t *WriteFileTool) Name() string

func (*WriteFileTool) Parameters 

func (t *WriteFileTool) Parameters() map[string]interface{}

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.