tools

package
v1.1.60 Latest Latest
Warning

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

 Go to latest Published: Jul 6, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ContextWithQuestionAsker 

func ContextWithQuestionAsker(ctx context.Context, asker QuestionAsker) context.Context

ContextWithQuestionAsker attaches a QuestionAsker to the context.

func ToolDefinition 

func ToolDefinition(t Tool) provider.ToolDefinition

ToolDefinition converts a Tool to a provider.ToolDefinition.

Types

type A2ADispatchTool 

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

A2ADispatchTool sends tasks to registered remote A2A agents.

func NewA2ADispatchTool 

func NewA2ADispatchTool(dispatcher A2ADispatcher) *A2ADispatchTool

NewA2ADispatchTool creates a new A2A dispatch tool.

func (*A2ADispatchTool) Description 

func (t *A2ADispatchTool) Description() string

func (*A2ADispatchTool) Execute 

func (t *A2ADispatchTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*A2ADispatchTool) Name 

func (t *A2ADispatchTool) Name() string

func (*A2ADispatchTool) Parameters 

func (t *A2ADispatchTool) Parameters() json.RawMessage

func (*A2ADispatchTool) PromptGuidelines 

func (t *A2ADispatchTool) PromptGuidelines() []string

func (*A2ADispatchTool) PromptSnippet 

func (t *A2ADispatchTool) PromptSnippet() string

type A2ADispatcher 

type A2ADispatcher interface {
	List() []AgentEntry
	Dispatch(ctx context.Context, name, message string) (string, error)
}

A2ADispatcher is the interface needed by the a2a_dispatch tool. It is satisfied by a2a.A2AManager.

type AgentEntry 

type AgentEntry struct {
	Name string
	URL  string
}

AgentEntry is a minimal view of a remote A2A agent.

type BackgroundJob 

type BackgroundJob struct {
	ID        int
	Command   string
	PID       int
	StartTime time.Time
	// contains filtered or unexported fields
}

BackgroundJob represents a running background process.

func (*BackgroundJob) IsDone 

func (job *BackgroundJob) IsDone() bool

IsDone returns whether the job is finished.

func (*BackgroundJob) MarkDone 

func (job *BackgroundJob) MarkDone(stdout, stderr []byte, err error)

MarkDone marks a job as finished and stores output.

func (*BackgroundJob) Status 

func (job *BackgroundJob) Status() string

Status returns a string representation of the job status.

type BashTool 

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

BashTool executes shell commands.

func NewBashTool 

func NewBashTool(r *Registry) *BashTool

NewBashTool creates a new bash tool with a new JobManager.

func NewBashToolWithJM 

func NewBashToolWithJM(r *Registry, jm *JobManager) *BashTool

NewBashToolWithJM creates a new bash tool with an existing JobManager.

func (*BashTool) Description 

func (t *BashTool) Description() string

func (*BashTool) Execute 

func (t *BashTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*BashTool) ExecutionTimeout 

func (t *BashTool) ExecutionTimeout(params map[string]any) (time.Duration, bool)

ExecutionTimeout lets bash align the agent-level tool deadline with the runtime behavior exposed by Execute.

func (*BashTool) GetJobManager 

func (t *BashTool) GetJobManager() *JobManager

GetJobManager returns the job manager for background processes.

func (*BashTool) Name 

func (t *BashTool) Name() string

func (*BashTool) Parameters 

func (t *BashTool) Parameters() json.RawMessage

func (*BashTool) PromptGuidelines 

func (t *BashTool) PromptGuidelines() []string

func (*BashTool) PromptSnippet 

func (t *BashTool) PromptSnippet() string

type EditTool 

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

EditTool performs precise text replacements in files.

func NewEditTool 

func NewEditTool(r *Registry) *EditTool

NewEditTool creates a new edit tool.

func (*EditTool) Description 

func (t *EditTool) Description() string

func (*EditTool) Execute 

func (t *EditTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*EditTool) Name 

func (t *EditTool) Name() string

func (*EditTool) Parameters 

func (t *EditTool) Parameters() json.RawMessage

func (*EditTool) PromptGuidelines 

func (t *EditTool) PromptGuidelines() []string

func (*EditTool) PromptSnippet 

func (t *EditTool) PromptSnippet() string

type ExecutionTimeoutProvider 

type ExecutionTimeoutProvider interface {
	ExecutionTimeout(params map[string]any) (time.Duration, bool)
}

ExecutionTimeoutProvider lets a tool override the agent's default execution timeout. The bool reports whether an override is provided. A non-positive duration disables the agent-level deadline while preserving parent cancellation.

type FileDiff 

type FileDiff struct {
	Path         string
	Added        int
	Deleted      int
	AddedLines   []int
	DeletedLines []int
	Unified      string
	Truncated    bool
}

FileDiff describes a file change produced by a write-like tool.

func BuildFileDiff 

func BuildFileDiff(path, oldContent, newContent string) *FileDiff

BuildFileDiff returns a compact, structured line diff for display and audit.

type FileLockManager 

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

FileLockManager coordinates in-process writes to individual files. It deliberately supports acquiring only one file at a time; write-like tools should not hold one file lock while waiting for another.

func DefaultFileLockManager 

func DefaultFileLockManager() *FileLockManager

DefaultFileLockManager returns the process-wide file lock manager used by default registries. It coordinates parent and sub-agent registries in the same process.

func NewFileLockManager 

func NewFileLockManager() *FileLockManager

NewFileLockManager creates an empty in-memory file lock manager.

func (*FileLockManager) Acquire 

func (m *FileLockManager) Acquire(ctx context.Context, path, owner string) (func(), error)

Acquire waits for exclusive access to path and returns a release function. Waiting is cancellable through ctx.

type FindTool 

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

FindTool searches for files by name pattern using the go-fd SDK.

func NewFindTool 

func NewFindTool(r *Registry) *FindTool

NewFindTool creates a new find tool.

func (*FindTool) Description 

func (t *FindTool) Description() string

func (*FindTool) Execute 

func (t *FindTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*FindTool) Name 

func (t *FindTool) Name() string

func (*FindTool) Parameters 

func (t *FindTool) Parameters() json.RawMessage

func (*FindTool) PromptGuidelines 

func (t *FindTool) PromptGuidelines() []string

func (*FindTool) PromptSnippet 

func (t *FindTool) PromptSnippet() string

type GrepTool 

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

GrepTool searches file contents using the go-ripgrep SDK.

func NewGrepTool 

func NewGrepTool(r *Registry) *GrepTool

NewGrepTool creates a new grep tool.

func (*GrepTool) Description 

func (t *GrepTool) Description() string

func (*GrepTool) Execute 

func (t *GrepTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*GrepTool) Name 

func (t *GrepTool) Name() string

func (*GrepTool) Parameters 

func (t *GrepTool) Parameters() json.RawMessage

func (*GrepTool) PromptGuidelines 

func (t *GrepTool) PromptGuidelines() []string

func (*GrepTool) PromptSnippet 

func (t *GrepTool) PromptSnippet() string

type JobManager 

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

JobManager manages background processes.

func NewJobManager 

func NewJobManager() *JobManager

NewJobManager creates a new job manager.

func (*JobManager) AddJob 

func (jm *JobManager) AddJob(cmd *exec.Cmd, command string, cancel context.CancelFunc) *BackgroundJob

AddJob adds a new background job.

func (*JobManager) GetJob 

func (jm *JobManager) GetJob(id int) *BackgroundJob

GetJob returns a job by ID.

func (*JobManager) KillJob 

func (jm *JobManager) KillJob(id int) error

KillJob kills a running job.

func (*JobManager) ListJobs 

func (jm *JobManager) ListJobs() []*BackgroundJob

ListJobs returns all jobs.

func (*JobManager) RemoveJob 

func (jm *JobManager) RemoveJob(id int)

RemoveJob removes a finished job.

type JobsTool 

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

JobsTool lists and manages background jobs.

func NewJobsTool 

func NewJobsTool(r *Registry, bashTool *BashTool) *JobsTool

NewJobsTool creates a new jobs tool.

func (*JobsTool) Description 

func (t *JobsTool) Description() string

func (*JobsTool) Execute 

func (t *JobsTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*JobsTool) Name 

func (t *JobsTool) Name() string

func (*JobsTool) Parameters 

func (t *JobsTool) Parameters() json.RawMessage

func (*JobsTool) PromptGuidelines 

func (t *JobsTool) PromptGuidelines() []string

func (*JobsTool) PromptSnippet 

func (t *JobsTool) PromptSnippet() string

type KillTool 

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

KillTool stops a running background job.

func NewKillTool 

func NewKillTool(r *Registry, bashTool *BashTool) *KillTool

NewKillTool creates a new kill tool.

func (*KillTool) Description 

func (t *KillTool) Description() string

func (*KillTool) Execute 

func (t *KillTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*KillTool) Name 

func (t *KillTool) Name() string

func (*KillTool) Parameters 

func (t *KillTool) Parameters() json.RawMessage

func (*KillTool) PromptGuidelines 

func (t *KillTool) PromptGuidelines() []string

func (*KillTool) PromptSnippet 

func (t *KillTool) PromptSnippet() string

type LsTool 

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

LsTool lists directory contents.

func NewLsTool 

func NewLsTool(r *Registry) *LsTool

NewLsTool creates a new ls tool.

func (*LsTool) Description 

func (t *LsTool) Description() string

func (*LsTool) Execute 

func (t *LsTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*LsTool) Name 

func (t *LsTool) Name() string

func (*LsTool) Parameters 

func (t *LsTool) Parameters() json.RawMessage

func (*LsTool) PromptGuidelines 

func (t *LsTool) PromptGuidelines() []string

func (*LsTool) PromptSnippet 

func (t *LsTool) PromptSnippet() string

type PlanStep 

type PlanStep struct {
	Title  string
	Status string
}

PlanStep describes one step in a task plan.

type PlanTool 

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

PlanTool publishes a structured task plan for UI and audit surfaces.

func NewPlanTool 

func NewPlanTool(r *Registry) *PlanTool

NewPlanTool creates a new plan tool.

func (*PlanTool) Description 

func (t *PlanTool) Description() string

func (*PlanTool) Execute 

func (t *PlanTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*PlanTool) Name 

func (t *PlanTool) Name() string

func (*PlanTool) Parameters 

func (t *PlanTool) Parameters() json.RawMessage

func (*PlanTool) PromptGuidelines 

func (t *PlanTool) PromptGuidelines() []string

func (*PlanTool) PromptSnippet 

func (t *PlanTool) PromptSnippet() string

type QuestionAsker 

type QuestionAsker interface {
	AskQuestion(ctx context.Context, question string, options []string, context string) string
}

QuestionAsker is the interface the tool uses to interact with the user. The agent implements this via RequestQuestion.

type QuestionTool 

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

QuestionTool asks the user a multiple-choice question during plan mode.

func NewQuestionTool 

func NewQuestionTool(r *Registry) *QuestionTool

NewQuestionTool creates a new question tool.

func (*QuestionTool) Description 

func (t *QuestionTool) Description() string

func (*QuestionTool) Execute 

func (t *QuestionTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*QuestionTool) Name 

func (t *QuestionTool) Name() string

func (*QuestionTool) Parameters 

func (t *QuestionTool) Parameters() json.RawMessage

func (*QuestionTool) PromptGuidelines 

func (t *QuestionTool) PromptGuidelines() []string

func (*QuestionTool) PromptSnippet 

func (t *QuestionTool) PromptSnippet() string

type ReadTool 

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

ReadTool reads file contents.

func NewReadTool 

func NewReadTool(r *Registry) *ReadTool

NewReadTool creates a new read tool.

func (*ReadTool) Description 

func (t *ReadTool) Description() string

func (*ReadTool) Execute 

func (t *ReadTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*ReadTool) Name 

func (t *ReadTool) Name() string

func (*ReadTool) Parameters 

func (t *ReadTool) Parameters() json.RawMessage

func (*ReadTool) PromptGuidelines 

func (t *ReadTool) PromptGuidelines() []string

func (*ReadTool) PromptSnippet 

func (t *ReadTool) PromptSnippet() string

type Registry 

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

Registry manages available tools.

func NewRegistry 

func NewRegistry(workDir string, sb sandbox.Sandbox) *Registry

NewRegistry creates a new tool registry.

func NewRegistryWithConfig 

func NewRegistryWithConfig(cfg RegistryConfig) *Registry

NewRegistryWithConfig creates a Registry with the given config.

func (*Registry) All 

func (r *Registry) All() []Tool

All returns all registered tools in order.

func (*Registry) Definitions 

func (r *Registry) Definitions() []provider.ToolDefinition

Definitions returns tool definitions for all registered tools.

func (*Registry) FileLocks 

func (r *Registry) FileLocks() *FileLockManager

FileLocks returns the registry's in-memory file lock manager.

func (*Registry) Get 

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

Get returns a tool by name.

func (*Registry) GetSandbox 

func (r *Registry) GetSandbox() sandbox.Sandbox

GetSandbox returns the registry's sandbox.

func (*Registry) GetWorkDir 

func (r *Registry) GetWorkDir() string

GetWorkDir returns the registry's working directory.

func (*Registry) ImagePolicy 

func (r *Registry) ImagePolicy(mode imageproc.Mode) imageproc.Policy

ImagePolicy returns the image preprocessing policy for the current registry context.

func (*Registry) JobManager 

func (r *Registry) JobManager() *JobManager

JobManager returns the registry's per-instance job manager.

func (*Registry) ModeTools 

func (r *Registry) ModeTools(mode string) []provider.ToolDefinition

ModeTools returns tool definitions appropriate for the given mode.

func (*Registry) Register 

func (r *Registry) Register(t Tool)

Register adds a tool to the registry.

func (*Registry) RegisterDefaults 

func (r *Registry) RegisterDefaults()

RegisterDefaults registers all default tools.

func (*Registry) RegisterDefaultsWithPlanTool 

func (r *Registry) RegisterDefaultsWithPlanTool(enablePlanTool bool)

RegisterDefaultsWithPlanTool registers all default tools, optionally including the plan tool.

func (*Registry) RegisterFiltered 

func (r *Registry) RegisterFiltered(toolNames []string)

RegisterFiltered registers only the specified tools by name.

func (*Registry) Remove 

func (r *Registry) Remove(name string)

Remove removes a tool by name. No-op if not found.

func (*Registry) ResolvePath 

func (r *Registry) ResolvePath(path string) (string, error)

ResolvePath resolves a user-provided path to an absolute path constrained to the work directory.

func (*Registry) SetImageHint 

func (r *Registry) SetImageHint(h imageproc.Hint)

SetImageHint updates provider/model context used by image-capable tools.

func (*Registry) SetSandbox 

func (r *Registry) SetSandbox(sb sandbox.Sandbox)

SetSandbox updates the sandbox used by tools.

func (*Registry) ToolGuidelines 

func (r *Registry) ToolGuidelines(toolNames []string) []string

ToolGuidelines returns prompt guidelines for the given tool names.

func (*Registry) ToolSnippets 

func (r *Registry) ToolSnippets(toolNames []string) map[string]string

ToolSnippets returns prompt snippets for the given tool names.

type RegistryConfig 

type RegistryConfig struct {
	WorkDir        string
	Sandbox        sandbox.Sandbox
	ToolFilter     []string         // optional: only register these tools (empty = all)
	SkillsMgr      *skills.Manager  // optional: skills manager for skill_ref tool
	EnablePlanTool *bool            // optional: defaults to true when nil
	FileLocks      *FileLockManager // optional: defaults to process-wide manager
	ImageHint      imageproc.Hint   // optional: provider/model hint for image preprocessing
}

RegistryConfig configures a Registry instance.

type SetTool 

type SetTool interface {
	SetSandbox(sb sandbox.Sandbox)
}

SetTool is an interface for tools that need sandbox updates.

type SkillRefTool 

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

SkillRefTool loads on-demand reference files from skills.

func NewSkillRefTool 

func NewSkillRefTool(skillsMgr *skills.Manager) *SkillRefTool

NewSkillRefTool creates a new skill reference loading tool.

func (*SkillRefTool) Description 

func (t *SkillRefTool) Description() string

func (*SkillRefTool) Execute 

func (t *SkillRefTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*SkillRefTool) Name 

func (t *SkillRefTool) Name() string

func (*SkillRefTool) Parameters 

func (t *SkillRefTool) Parameters() json.RawMessage

func (*SkillRefTool) PromptGuidelines 

func (t *SkillRefTool) PromptGuidelines() []string

func (*SkillRefTool) PromptSnippet 

func (t *SkillRefTool) PromptSnippet() string

type TaskPlan 

type TaskPlan struct {
	Title string
	Steps []PlanStep
	Note  string
}

TaskPlan describes a structured task plan emitted by the plan tool.

type Tool 

type Tool interface {
	// Name returns the tool's name.
	Name() string

	// Description returns a description of what the tool does.
	Description() string

	// PromptSnippet returns a short one-line description for the system prompt's Available tools section.
	PromptSnippet() string

	// PromptGuidelines returns guideline bullets for the system prompt's Guidelines section.
	PromptGuidelines() []string

	// Parameters returns the JSON Schema for the tool's parameters.
	Parameters() json.RawMessage

	// Execute runs the tool with the given parameters.
	Execute(ctx context.Context, params map[string]any) (ToolResult, error)
}

Tool is the interface that all tools must implement.

type ToolResult 

type ToolResult struct {
	Text     string                  // Plain text result (always populated for display/logging)
	Contents []provider.ContentBlock // Rich content blocks (text + images) for the LLM
	Diff     *FileDiff               // Optional structured file diff for UI/reporting
	Plan     *TaskPlan               // Optional structured task plan for UI/reporting
}

ToolResult represents the result of a tool execution. It can contain plain text and optional rich content blocks (e.g. images).

func NewDiffToolResult 

func NewDiffToolResult(text string, diff *FileDiff) ToolResult

NewDiffToolResult creates a text tool result with structured diff metadata.

func NewImageToolResult 

func NewImageToolResult(text, mimeType, base64Data string) ToolResult

NewImageToolResult creates a tool result that includes an image. text is the human-readable description, mimeType and base64Data are the image payload.

func NewImageToolResultWithContent 

func NewImageToolResultWithContent(text string, image provider.ImageContent) ToolResult

NewImageToolResultWithContent creates a tool result with a fully populated image payload.

func NewPlanToolResult 

func NewPlanToolResult(text string, plan *TaskPlan) ToolResult

NewPlanToolResult creates a text tool result with structured plan metadata.

func NewTextToolResult 

func NewTextToolResult(text string) ToolResult

NewTextToolResult creates a plain text tool result.

type WriteTool 

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

WriteTool writes content to files.

func NewWriteTool 

func NewWriteTool(r *Registry) *WriteTool

NewWriteTool creates a new write tool.

func (*WriteTool) Description 

func (t *WriteTool) Description() string

func (*WriteTool) Execute 

func (t *WriteTool) Execute(ctx context.Context, params map[string]any) (ToolResult, error)

func (*WriteTool) Name 

func (t *WriteTool) Name() string

func (*WriteTool) Parameters 

func (t *WriteTool) Parameters() json.RawMessage

func (*WriteTool) PromptGuidelines 

func (t *WriteTool) PromptGuidelines() []string

func (*WriteTool) PromptSnippet 

func (t *WriteTool) PromptSnippet() string

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.