tools

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Jun 11, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

Package tools provides the standard coding toolbox for the agent runtime: bash, read, write, edit, editdiff, find, grep, imageresize, and plan.

Each constructor returns an github.com/kfet/agent.AgentTool that can be registered on a ToolSet. Tools that touch the filesystem resolve paths relative to a working directory supplied at construction time, and tool errors are returned as LLM-facing payloads rather than host-level failures.

Index

Constants

View Source 
const (
	DefaultMaxBytes   = pinexec.DefaultMaxBytes
	DefaultMaxLines   = pinexec.DefaultMaxLines
	GrepMaxLineLength = pinexec.GrepMaxLineLength
)

Constants.

Variables

View Source 
var (
	StripAnsi      = pinexec.StripAnsi
	AppendColorEnv = pinexec.AppendColorEnv
	FormatSize     = pinexec.FormatSize
	TruncateLine   = pinexec.TruncateLine
	TruncateHead   = pinexec.TruncateHead
	TruncateTail   = pinexec.TruncateTail
)

Functions — re-exported as vars so the godoc and signature stay canonical in pinexec and don't drift here.

View Source 
var DefaultBashTimeout = 10 * time.Second

DefaultBashTimeout is applied when the agent does not pass an explicit timeout. Agents can override (up or down) via the "timeout" parameter. It is a var (not const) so tests can shorten it.

View Source 
var SupportedImageExtensions = map[string]string{
	".jpg":  "image/jpeg",
	".jpeg": "image/jpeg",
	".png":  "image/png",
	".gif":  "image/gif",
	".webp": "image/webp",
}

SupportedImageExtensions lists file extensions treated as images.

Functions

func ExpandPath 

func ExpandPath(filePath string) string

ExpandPath expands ~ to the user's home directory and normalizes Unicode spaces.

func FormatDimensionNote 

func FormatDimensionNote(r ResizedImage) string

FormatDimensionNote returns a note about the resize for the model.

func IsHidden 

func IsHidden(name string) bool

IsHidden returns true if a path component starts with a dot.

func NewBashTool 

func NewBashTool(cwd string) agent.AgentTool

NewBashTool creates the bash tool for the given working directory.

func NewBashToolWithPrefix 

func NewBashToolWithPrefix(cwd, commandPrefix string) agent.AgentTool

NewBashToolWithPrefix creates a bash tool that prepends a shell command prefix (e.g., "source /etc/profile") before each command.

func NewEditTool 

func NewEditTool(cwd string) agent.AgentTool

NewEditTool creates the edit (find-and-replace) tool.

func NewEditToolWithReadWriter 

func NewEditToolWithReadWriter(cwd string, readFn ReadFileFn, writeFn WriteFileFn) agent.AgentTool

NewEditToolWithReadWriter creates an edit tool that uses readFn/writeFn for file I/O. This enables ACP client file delegation (Zed's "Reject All"/"Keep All" review UI).

func NewFindTool 

func NewFindTool(cwd string) agent.AgentTool

NewFindTool creates the find tool for the given working directory.

func NewGrepTool 

func NewGrepTool(cwd string) agent.AgentTool

NewGrepTool creates the grep tool for the given working directory.

func NewPlanTool 

func NewPlanTool(sink PlanSink, publisher CardPublisher) agent.AgentTool

NewPlanTool creates the plan tool.

  • sink is required and is called on every plan update.
  • publisher is optional. When non-nil it is invoked after sink with the same arguments plus the tool-call id, so host code can mirror the plan state into a card store, status bar, telemetry sink, etc.

func NewReadTool 

func NewReadTool(cwd string) agent.AgentTool

NewReadTool creates the read tool for the given working directory.

func NewReadToolWithReader 

func NewReadToolWithReader(cwd string, readFn ReadFileFn) agent.AgentTool

NewReadToolWithReader creates a read tool that delegates text file reads to readFn. Image files are still read locally (ACP clients don't expose binary file reading).

func NewWriteTool 

func NewWriteTool(cwd string) agent.AgentTool

NewWriteTool creates the write tool for the given working directory.

func NewWriteToolWithWriter 

func NewWriteToolWithWriter(cwd string, writeFn WriteFileFn) agent.AgentTool

NewWriteToolWithWriter creates a write tool that delegates file writes to writeFn.

func ResolveReadPath 

func ResolveReadPath(filePath string, cwd string) string

ResolveReadPath resolves a path for reading, trying macOS filename variants if the literal path doesn't exist.

func ResolveToCwd 

func ResolveToCwd(filePath string, cwd string) string

ResolveToCwd resolves a path relative to the given cwd. Handles ~ expansion and absolute paths.

Types

type BashToolParams 

type BashToolParams struct {
	Command string   `json:"command"`
	Timeout *float64 `json:"timeout,omitempty"` // seconds
	Cwd     string   `json:"cwd,omitempty"`     // optional per-call working directory override
}

BashToolParams are the parameters for the bash tool.

type CardPublisher 

type CardPublisher func(title string, entries []agent.PlanEntry, metadata map[string]string, entryID string)

CardPublisher is an optional callback invoked on every successful plan mutation. Host code may use it to render the current plan in its own UI (status bar, observable card, etc.) — the plan tool itself stays free of that dependency.

May be nil; the plan tool is silent when no publisher is provided.

type EditDiffResult 

type EditDiffResult struct {
	Diff             string
	FirstChangedLine *int
}

EditDiffResult contains the diff string and first changed line.

func GenerateDiffString 

func GenerateDiffString(oldContent, newContent string, contextLines int) EditDiffResult

GenerateDiffString generates a unified diff with line numbers and context.

type EditToolDetails 

type EditToolDetails struct {
	Diff             string `json:"diff"`
	FirstChangedLine *int   `json:"firstChangedLine,omitempty"`
}

EditToolDetails contains the diff result from an edit operation.

type EditToolParams 

type EditToolParams struct {
	Path    string `json:"path"`
	OldText string `json:"oldText"`
	NewText string `json:"newText"`
}

EditToolParams are the parameters for the edit tool.

type FindToolDetails 

type FindToolDetails struct {
	Truncation         *TruncationResult `json:"truncation,omitempty"`
	ResultLimitReached *int              `json:"resultLimitReached,omitempty"`
}

FindToolDetails contains details about the find result.

type FindToolParams 

type FindToolParams struct {
	Pattern string `json:"pattern"`
	Path    string `json:"path,omitempty"`
	Limit   *int   `json:"limit,omitempty"`
}

FindToolParams are the parameters for the find tool.

type GrepToolDetails 

type GrepToolDetails struct {
	Truncation        *TruncationResult `json:"truncation,omitempty"`
	MatchLimitReached *int              `json:"matchLimitReached,omitempty"`
	LinesTruncated    bool              `json:"linesTruncated,omitempty"`
}

GrepToolDetails contains details about the grep result.

type GrepToolParams 

type GrepToolParams struct {
	Pattern    string `json:"pattern"`
	Path       string `json:"path,omitempty"`
	Glob       string `json:"glob,omitempty"`
	IgnoreCase bool   `json:"ignoreCase,omitempty"`
	Literal    bool   `json:"literal,omitempty"`
	Context    int    `json:"context,omitempty"`
	Limit      *int   `json:"limit,omitempty"`
}

GrepToolParams are the parameters for the grep tool.

type PlanSink 

type PlanSink interface {
	UpdatePlan(title string, entries []agent.PlanEntry, metadata map[string]string)
}

PlanSink is the minimal interface the plan tool needs from a session: a place to commit the updated plan. Implementations live outside this package (typically in the host session package).

type ReadFileFn 

type ReadFileFn func(ctx context.Context, path string) (string, error)

ReadFileFn is a function that reads a file and returns its text content. Used for ACP client delegation.

type ReadToolDetails 

type ReadToolDetails struct {
	Truncation *TruncationResult `json:"truncation,omitempty"`
	// Hash is the content hash of the file. Always set on a successful
	// text/image read so the model can later pass it back as if_hash.
	Hash string `json:"hash,omitempty"`
	// Unchanged is true when an if_hash matched and the full body was elided.
	Unchanged bool `json:"unchanged,omitempty"`
}

ReadToolDetails contains details about a read result.

type ReadToolParams 

type ReadToolParams struct {
	Path   string `json:"path"`
	Offset *int   `json:"offset,omitempty"` // 1-indexed line number
	Limit  *int   `json:"limit,omitempty"`
	IfHash string `json:"if_hash,omitempty"` // optional: confirm-unchanged opt-in
}

ReadToolParams are the parameters for the read tool.

type ResizeImageOptions 

type ResizeImageOptions struct {
	MaxWidth    int
	MaxHeight   int
	MaxBytes    int
	JPEGQuality int
}

ResizeImageOptions configures image resizing.

type ResizedImage 

type ResizedImage struct {
	Data           string // base64
	MimeType       string
	OriginalWidth  int
	OriginalHeight int
	Width          int
	Height         int
	WasResized     bool
}

ResizedImage contains the result of an image resize operation.

func ResizeImage 

func ResizeImage(b64Data, mimeType string, options *ResizeImageOptions) ResizedImage

ResizeImage resizes an image to fit within the max dimensions and file size. Returns the original image unchanged if it already fits.

type TruncationOptions 

type TruncationOptions = pinexec.TruncationOptions

Types.

type TruncationResult 

type TruncationResult = pinexec.TruncationResult

Types.

type WriteFileFn 

type WriteFileFn func(ctx context.Context, path, content string) error

WriteFileFn is a function that writes content to a file path. Used for ACP client delegation.

type WriteToolParams 

type WriteToolParams struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

WriteToolParams are the parameters for the write tool.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.