tools

Documentation

Overview

Ported from: packages/coding-agent/src/core/tools/bash.ts Upstream hash: 1caadb2e

Ported from: packages/coding-agent/src/core/tools/edit.ts + edit-diff.ts Upstream hash: 1caadb2e

Ported from: packages/coding-agent/src/core/tools/edit-diff.ts Upstream hash: 1caadb2e

This file contains diff generation and exported aliases for the edit-diff helpers (unexported originals live in edit.go).

Ported from: packages/coding-agent/src/core/tools/find.ts Upstream hash: 1caadb2e

Ported from: packages/coding-agent/src/core/tools/grep.ts Upstream hash: 1caadb2e

Ported from: packages/coding-agent/src/utils/image-resize.ts Upstream hash: 1caadb2e

Ported from: packages/coding-agent/src/core/tools/path-utils.ts Upstream hash: 1caadb2e

Ported from: packages/coding-agent/src/core/tools/read.ts Upstream hash: 1caadb2e

Ported from: packages/coding-agent/src/core/tools/write.ts Upstream hash: 1caadb2e

Index

• Constants
• Variables
• func ExpandPath(filePath string) string
• func FormatDimensionNote(r ResizedImage) string
• func IsHidden(name string) bool
• func NewBashTool(cwd string) agent.AgentTool
• func NewBashToolWithPrefix(cwd, commandPrefix string) agent.AgentTool
• func NewEditTool(cwd string) agent.AgentTool
• func NewEditToolWithReadWriter(cwd string, readFn ReadFileFn, writeFn WriteFileFn) agent.AgentTool
• func NewFindTool(cwd string) agent.AgentTool
• func NewGrepTool(cwd string) agent.AgentTool
• func NewPlanTool(sink PlanSink, publisher CardPublisher) agent.AgentTool
• func NewReadTool(cwd string) agent.AgentTool
• func NewReadToolWithReader(cwd string, readFn ReadFileFn) agent.AgentTool
• func NewWriteTool(cwd string) agent.AgentTool
• func NewWriteToolWithWriter(cwd string, writeFn WriteFileFn) agent.AgentTool
• func ResolveReadPath(filePath string, cwd string) string
• func ResolveToCwd(filePath string, cwd string) string
• type BashToolParams
• type CardPublisher
• type EditDiffResult
  • func GenerateDiffString(oldContent, newContent string, contextLines int) EditDiffResult
• type EditToolDetails
• type EditToolParams
• type FindToolDetails
• type FindToolParams
• type GrepToolDetails
• type GrepToolParams
• type PlanSink
• type ReadFileFn
• type ReadToolDetails
• type ReadToolParams
• type ResizeImageOptions
• type ResizedImage
  • func ResizeImage(b64Data, mimeType string, options *ResizeImageOptions) ResizedImage
• type TruncationOptions
• type TruncationResult
• type WriteFileFn
• type WriteToolParams

Constants

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

Constants.

Variables

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.

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.

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 a fir-style observable "plan/active" card (see docs/design/observable-cards.md) — 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 pkg/agent/tools (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"`
}

ReadToolDetails contains details about truncation that occurred.

type ReadToolParams

type ReadToolParams struct {
	Path   string `json:"path"`
	Offset *int   `json:"offset,omitempty"` // 1-indexed line number
	Limit  *int   `json:"limit,omitempty"`
}

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.