tools

package
v1.7.12 Latest Latest
Warning

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

 Go to latest Published: Jul 21, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Overview

Package tools provides the built-in agent tools — read, write, edit, and bash. The file tools share a FileReadState that enforces read-before-write and detects stale edits. Each tool implements agentcore.Tool.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CwdFromContext added in v1.7.3 

func CwdFromContext(ctx context.Context) string

CwdFromContext returns the working-directory override attached to ctx, or "" if none is set (the common case, where tools fall back to their constructed WorkDir). A live WithCwdFunc source is consulted first, then a static WithCwd.

func ExpandPath added in v1.5.1 

func ExpandPath(p string) string

ExpandPath normalizes a user-provided path:

  • Replaces Unicode special spaces with ASCII space
  • Expands ~ to the user's home directory

func IsSkipDir added in v1.5.1 

func IsSkipDir(name string) bool

IsSkipDir reports whether a directory name should be excluded from traversal.

func ResolvePath added in v1.5.1 

func ResolvePath(workDir, userPath string) string

ResolvePath resolves a user-provided path against a working directory. If userPath is empty, returns workDir. If absolute, returns as-is. Otherwise joins with workDir.

func WithCwd added in v1.7.3 

func WithCwd(parent context.Context, cwd string) context.Context

WithCwd returns a derived context carrying cwd as the working-directory override for cwd-bound tools. An empty cwd is a no-op (returns parent), so callers can pass through whatever they have without branching.

func WithCwdFunc added in v1.7.3 

func WithCwdFunc(parent context.Context, fn func() string) context.Context

WithCwdFunc carries fn as a live cwd source, invoked on every resolution so a cwd that changes after the context is derived takes effect immediately. A nil fn is a no-op. A non-empty fn result wins over a static WithCwd value; an empty one falls back to it.

Types

type BashTool 

type BashTool struct {
	WorkDir string
	Timeout time.Duration // default: 2 minutes
	// contains filtered or unexported fields
}

BashTool executes shell commands. Streams stdout+stderr via ReportToolProgress for real-time display. Final result applies tail truncation (2000 lines / 50KB). Supports run_in_background mode for long-running commands.

func NewBash 

func NewBash(workDir string) *BashTool

func (*BashTool) ActivityDescription added in v1.6.0 

func (t *BashTool) ActivityDescription(args json.RawMessage) string

ActivityDescription returns a short description including the command.

func (*BashTool) ConcurrencySafe added in v1.6.0 

func (t *BashTool) ConcurrencySafe(_ json.RawMessage) bool

ConcurrencySafe reports false — bash commands are not safe for concurrent execution.

func (*BashTool) Description 

func (t *BashTool) Description() string

func (*BashTool) Execute 

func (t *BashTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*BashTool) Label 

func (t *BashTool) Label() string

func (*BashTool) Name 

func (t *BashTool) Name() string

func (*BashTool) ReadOnly added in v1.6.0 

func (t *BashTool) ReadOnly(_ json.RawMessage) bool

ReadOnly reports false — bash commands may have side effects.

func (*BashTool) Schema 

func (t *BashTool) Schema() map[string]any

func (*BashTool) SetBgOutputFactory added in v1.5.3 

func (t *BashTool) SetBgOutputFactory(fn func(shellID string) (io.WriteCloser, string, error))

SetBgOutputFactory sets the factory that creates output writers for background shells. The factory receives the shell ID and returns a writer, file path, and error. If not set, background output is discarded.

func (*BashTool) SetNotifyFn added in v1.5.3 

func (t *BashTool) SetNotifyFn(fn func(agentcore.AgentMessage))

SetNotifyFn sets the callback invoked when a background shell completes. Typically bound to Agent.FollowUp so the main agent receives the result.

func (*BashTool) SetTaskRuntime added in v1.6.0 

func (t *BashTool) SetTaskRuntime(rt *task.Runtime)

SetTaskRuntime sets the shared task runtime for background task registration.

type DirEntry added in v1.7.2 

type DirEntry struct {
	Name  string
	IsDir bool
}

DirEntry is the minimal directory entry the read tool needs.

type EditTool 

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

EditTool performs exact string replacement in a file. Supports line ending normalization, fuzzy matching, and returns unified diff.

Validate enforces read-before-edit and detects stale writes when state is non-nil.

func NewEdit 

func NewEdit(workDir string, state *FileReadState, opts ...Option) *EditTool

NewEdit creates an edit tool rooted at workDir.

Pass the same non-nil FileReadState to NewRead, NewWrite, and NewEdit to enable read-before-write/edit validation. Pass nil to disable this tracking. By default the tool operates on the local filesystem; pass WithFS to inject a different WorkspaceFS backend.

func (*EditTool) ActivityDescription added in v1.6.0 

func (t *EditTool) ActivityDescription(_ json.RawMessage) string

func (*EditTool) ConcurrencySafe added in v1.6.0 

func (t *EditTool) ConcurrencySafe(_ json.RawMessage) bool

func (*EditTool) Description 

func (t *EditTool) Description() string

func (*EditTool) Execute 

func (t *EditTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*EditTool) Label 

func (t *EditTool) Label() string

func (*EditTool) Name 

func (t *EditTool) Name() string

func (*EditTool) Preview added in v1.5.1 

func (t *EditTool) Preview(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

Preview computes the diff without writing the file.

func (*EditTool) ReadOnly added in v1.6.0 

func (t *EditTool) ReadOnly(_ json.RawMessage) bool

func (*EditTool) Schema 

func (t *EditTool) Schema() map[string]any

func (*EditTool) Validate added in v1.6.9 

func (t *EditTool) Validate(ctx context.Context, args json.RawMessage) agentcore.ValidationResult

Validate enforces read-before-edit and detects stale writes. Unlike Write, edit always requires an existing file — a non-existent path fails. Error codes match WriteTool.Validate.

type FileInfo added in v1.7.2 

type FileInfo struct {
	Name    string
	Size    int64
	Mode    fs.FileMode
	ModTime time.Time
	IsDir   bool
	Version string
}

FileInfo is the backend-neutral subset of os.FileInfo the file tools need, plus Version.

Version is a backend-defined opaque token identifying the content revision. The OS backend leaves it empty (read-before-write falls back to ModTime). Backends serving unsaved editor buffers or remote objects may set it (e.g. a content hash or etag); when both the read stamp and the current FileInfo carry a non-empty Version, Write/Edit compare Version instead of ModTime to detect stale writes.

type FileReadStamp added in v1.6.9 

type FileReadStamp struct {
	ReadAt  time.Time
	Mtime   time.Time
	Version string
	Partial bool
}

FileReadStamp records when a file was read and its mtime at that moment. Write and edit tools consult these stamps via their Validator to enforce:

  • read-before-write: a file must be read before it is overwritten.
  • no-stale-write: the file must not have been modified externally between the last read and the write attempt.

Partial is true when the read used offset/limit. A partial read does not satisfy read-before-write — the LLM may not know about content outside the slice it read.

Version is the backend-defined content token recorded at read time (see WorkspaceFS.FileInfo.Version). It is empty for the OS backend; Write/Edit fall back to comparing Mtime when either side's Version is empty.

type FileReadState added in v1.6.9 

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

FileReadState is the session-scoped store of FileReadStamp keyed by absolute path. Read, Write, and Edit tools share one instance per session, passed at construction time.

func NewFileReadState added in v1.6.9 

func NewFileReadState() *FileReadState

func (*FileReadState) Get added in v1.6.9 

func (s *FileReadState) Get(path string) (FileReadStamp, bool)

func (*FileReadState) Reset added in v1.6.9 

func (s *FileReadState) Reset()

Reset drops all recorded stamps. Called by Session on /clear, Reset, and session switch so the LLM never writes based on stamps from a read it no longer has in its conversation history.

func (*FileReadState) Set added in v1.6.9 

func (s *FileReadState) Set(path string, stamp FileReadStamp)

type GlobTool added in v1.5.5 

type GlobTool struct {
	WorkDir string
}

GlobTool matches files by glob pattern and returns relative paths sorted by modification time (newest first). Uses rg --files if available, falls back to filepath.WalkDir.

func NewGlob added in v1.5.5 

func NewGlob(workDir string) *GlobTool

func (*GlobTool) ActivityDescription added in v1.6.0 

func (t *GlobTool) ActivityDescription(_ json.RawMessage) string

func (*GlobTool) ConcurrencySafe added in v1.6.0 

func (t *GlobTool) ConcurrencySafe(_ json.RawMessage) bool

func (*GlobTool) Description added in v1.5.5 

func (t *GlobTool) Description() string

func (*GlobTool) Execute added in v1.5.5 

func (t *GlobTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*GlobTool) Label added in v1.5.5 

func (t *GlobTool) Label() string

func (*GlobTool) Name added in v1.5.5 

func (t *GlobTool) Name() string

func (*GlobTool) ReadOnly added in v1.6.0 

func (t *GlobTool) ReadOnly(_ json.RawMessage) bool

func (*GlobTool) Schema added in v1.5.5 

func (t *GlobTool) Schema() map[string]any

type GrepTool 

type GrepTool struct {
	WorkDir string
}

GrepTool searches file contents by pattern. Uses ripgrep (rg) if available, falls back to regexp + bufio.Scanner.

func NewGrep 

func NewGrep(workDir string) *GrepTool

func (*GrepTool) ActivityDescription added in v1.6.0 

func (t *GrepTool) ActivityDescription(_ json.RawMessage) string

func (*GrepTool) ConcurrencySafe added in v1.6.0 

func (t *GrepTool) ConcurrencySafe(_ json.RawMessage) bool

func (*GrepTool) Description 

func (t *GrepTool) Description() string

func (*GrepTool) Execute 

func (t *GrepTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*GrepTool) Label 

func (t *GrepTool) Label() string

func (*GrepTool) Name 

func (t *GrepTool) Name() string

func (*GrepTool) ReadOnly added in v1.6.0 

func (t *GrepTool) ReadOnly(_ json.RawMessage) bool

func (*GrepTool) Schema 

func (t *GrepTool) Schema() map[string]any

type LsTool 

type LsTool struct {
	WorkDir string
}

LsTool lists directory contents with optional depth control.

func NewLs 

func NewLs(workDir string) *LsTool

func (*LsTool) ActivityDescription added in v1.6.0 

func (t *LsTool) ActivityDescription(_ json.RawMessage) string

func (*LsTool) ConcurrencySafe added in v1.6.0 

func (t *LsTool) ConcurrencySafe(_ json.RawMessage) bool

func (*LsTool) Description 

func (t *LsTool) Description() string

func (*LsTool) Execute 

func (t *LsTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*LsTool) Label 

func (t *LsTool) Label() string

func (*LsTool) Name 

func (t *LsTool) Name() string

func (*LsTool) ReadOnly added in v1.6.0 

func (t *LsTool) ReadOnly(_ json.RawMessage) bool

func (*LsTool) Schema 

func (t *LsTool) Schema() map[string]any

type OSWorkspaceFS added in v1.7.2 

type OSWorkspaceFS struct{}

OSWorkspaceFS is the default WorkspaceFS backed by the local filesystem. It ignores ctx and leaves FileInfo.Version empty.

func (OSWorkspaceFS) MkdirAll added in v1.7.2 

func (OSWorkspaceFS) MkdirAll(_ context.Context, path string, perm fs.FileMode) error

func (OSWorkspaceFS) Open added in v1.7.2 

func (OSWorkspaceFS) Open(_ context.Context, path string) (io.ReadCloser, error)

func (OSWorkspaceFS) ReadDir added in v1.7.2 

func (OSWorkspaceFS) ReadDir(_ context.Context, path string) ([]DirEntry, error)

func (OSWorkspaceFS) ReadFile added in v1.7.2 

func (OSWorkspaceFS) ReadFile(_ context.Context, path string) ([]byte, error)

func (OSWorkspaceFS) Stat added in v1.7.2 

func (OSWorkspaceFS) Stat(_ context.Context, path string) (FileInfo, error)

func (OSWorkspaceFS) WriteFile added in v1.7.2 

func (OSWorkspaceFS) WriteFile(_ context.Context, path string, data []byte, perm fs.FileMode) error

type Option added in v1.7.2 

type Option func(*toolOptions)

Option configures a file tool at construction time.

func WithFS added in v1.7.2 

func WithFS(fs WorkspaceFS) Option

WithFS injects a WorkspaceFS backend. When omitted, tools default to OSWorkspaceFS (local filesystem) — so existing NewRead/NewWrite/NewEdit callers keep their current behaviour unchanged.

type ReadTool 

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

ReadTool reads file contents with optional offset and limit. Supports directory listings and image files. Text output is streamed and truncated by line count / byte size. Binary files are rejected.

Successful reads record a stamp when state is non-nil. Write and Edit tools constructed with the same state enforce read-before-write and detect stale writes.

func NewRead 

func NewRead(workDir string, state *FileReadState, opts ...Option) *ReadTool

NewRead creates a read tool rooted at workDir.

Pass the same non-nil FileReadState to NewRead, NewWrite, and NewEdit to enable read-before-write/edit validation. Pass nil to disable this tracking. By default the tool operates on the local filesystem; pass WithFS to inject a different WorkspaceFS backend.

func (*ReadTool) ActivityDescription added in v1.6.0 

func (t *ReadTool) ActivityDescription(_ json.RawMessage) string

func (*ReadTool) ConcurrencySafe added in v1.6.0 

func (t *ReadTool) ConcurrencySafe(_ json.RawMessage) bool

func (*ReadTool) Description 

func (t *ReadTool) Description() string

func (*ReadTool) Execute 

func (t *ReadTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

Execute returns a text-only result (for backward compatibility / middleware).

func (*ReadTool) ExecuteContent added in v1.5.1 

func (t *ReadTool) ExecuteContent(ctx context.Context, args json.RawMessage) ([]agentcore.ContentBlock, error)

ExecuteContent returns rich content blocks (text or image). Implements agentcore.ContentTool.

func (*ReadTool) Label 

func (t *ReadTool) Label() string

func (*ReadTool) Name 

func (t *ReadTool) Name() string

func (*ReadTool) ReadOnly added in v1.6.0 

func (t *ReadTool) ReadOnly(_ json.RawMessage) bool

func (*ReadTool) Schema 

func (t *ReadTool) Schema() map[string]any

type ToolSearchTool added in v1.5.2 

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

ToolSearchTool provides LLM-driven discovery of deferred tools. It implements agentcore.Tool, agentcore.ContentTool, and agentcore.DeferFilter.

When called, it returns tool_reference content blocks that instruct the API server to load the referenced deferred tool schemas into the LLM context.

func NewToolSearchTool added in v1.5.2 

func NewToolSearchTool(deferred ...agentcore.Tool) *ToolSearchTool

NewToolSearchTool creates a ToolSearchTool that defers the given tools. Deferred tools are sent to the API with defer_loading: true and only loaded into LLM context when discovered via tool_reference blocks.

func (*ToolSearchTool) Activate added in v1.5.2 

func (t *ToolSearchTool) Activate(names ...string)

Activate marks the given tool names as activated so their schemas are sent to the API with defer_loading: true instead of being excluded. Used to restore activation state when resuming a session.

func (*ToolSearchTool) ActivityDescription added in v1.6.0 

func (t *ToolSearchTool) ActivityDescription(_ json.RawMessage) string

func (*ToolSearchTool) ConcurrencySafe added in v1.6.0 

func (t *ToolSearchTool) ConcurrencySafe(_ json.RawMessage) bool

func (*ToolSearchTool) DeferredNames added in v1.5.2 

func (t *ToolSearchTool) DeferredNames() []string

DeferredNames returns the names of all deferred (not yet activated) tools.

func (*ToolSearchTool) Description added in v1.5.2 

func (t *ToolSearchTool) Description() string

func (*ToolSearchTool) Execute added in v1.5.2 

func (t *ToolSearchTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

Execute implements agentcore.Tool. Delegates to ExecuteContent and returns a text summary. In practice, the agent loop uses ExecuteContent (ContentTool) and this method serves as a fallback.

func (*ToolSearchTool) ExecuteContent added in v1.5.2 

func (t *ToolSearchTool) ExecuteContent(_ context.Context, args json.RawMessage) ([]agentcore.ContentBlock, error)

ExecuteContent implements agentcore.ContentTool. Returns tool_reference content blocks for matched tools.

func (*ToolSearchTool) IsDeferred added in v1.5.2 

func (t *ToolSearchTool) IsDeferred(name string) bool

IsDeferred implements agentcore.DeferFilter. Returns true for deferred tools not yet activated (should be excluded from API).

func (*ToolSearchTool) Name added in v1.5.2 

func (t *ToolSearchTool) Name() string

func (*ToolSearchTool) PermissionMetadata added in v1.6.6 

func (t *ToolSearchTool) PermissionMetadata() permission.Metadata

func (*ToolSearchTool) ReadOnly added in v1.6.0 

func (t *ToolSearchTool) ReadOnly(_ json.RawMessage) bool

func (*ToolSearchTool) Schema added in v1.5.2 

func (t *ToolSearchTool) Schema() map[string]any

func (*ToolSearchTool) WasDeferred added in v1.5.2 

func (t *ToolSearchTool) WasDeferred(name string) bool

WasDeferred implements agentcore.DeferFilter. Returns true if the tool was originally in the deferred set (regardless of activation state). Activated deferred tools are sent with defer_loading: true.

type TruncationResult added in v1.5.1 

type TruncationResult struct {
	Content               string
	Truncated             bool
	TruncatedBy           string // "lines", "bytes", or ""
	TotalLines            int
	TotalBytes            int
	OutputLines           int
	OutputBytes           int
	FirstLineExceedsLimit bool // truncateHead: first line alone exceeds byte limit
	LastLinePartial       bool // truncateTail: final line was byte-sliced
}

TruncationResult holds detailed metadata about a truncation operation.

type WorkspaceFS added in v1.7.2 

type WorkspaceFS interface {
	// Stat returns metadata for the file or directory at path.
	Stat(ctx context.Context, path string) (FileInfo, error)

	// Open returns a streaming reader. Used for line-by-line text reads and
	// for sniffing the first bytes (MIME / binary detection) without loading
	// the whole file into memory.
	Open(ctx context.Context, path string) (io.ReadCloser, error)

	// ReadFile returns the full file contents. Used where the whole file is
	// needed anyway: image decode, edit full-content match, write old content.
	ReadFile(ctx context.Context, path string) ([]byte, error)

	// ReadDir lists directory entries (non-recursive).
	ReadDir(ctx context.Context, path string) ([]DirEntry, error)

	// WriteFile writes data to path, truncating any existing file.
	WriteFile(ctx context.Context, path string, data []byte, perm fs.FileMode) error

	// MkdirAll creates path and any missing parents.
	MkdirAll(ctx context.Context, path string, perm fs.FileMode) error
}

WorkspaceFS abstracts access to the agent's workspace files so the backend can be the local OS, an editor (serving unsaved buffers), a remote host, or an in-memory store. The read/write/edit tools operate through this interface instead of calling os.* directly.

All paths are absolute: tools call ResolvePath before handing a path to a WorkspaceFS method. Implementations that perform I/O over a transport should honour ctx cancellation; the OS backend ignores ctx.

type WriteTool 

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

WriteTool writes content to a file, creating directories as needed.

Validate enforces read-before-write and detects stale writes when state is non-nil.

func NewWrite 

func NewWrite(workDir string, state *FileReadState, opts ...Option) *WriteTool

NewWrite creates a write tool rooted at workDir.

Pass the same non-nil FileReadState to NewRead, NewWrite, and NewEdit to enable read-before-write/edit validation. Pass nil to disable this tracking. By default the tool operates on the local filesystem; pass WithFS to inject a different WorkspaceFS backend.

func (*WriteTool) ActivityDescription added in v1.6.0 

func (t *WriteTool) ActivityDescription(_ json.RawMessage) string

func (*WriteTool) ConcurrencySafe added in v1.6.0 

func (t *WriteTool) ConcurrencySafe(_ json.RawMessage) bool

func (*WriteTool) Description 

func (t *WriteTool) Description() string

func (*WriteTool) Execute 

func (t *WriteTool) Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*WriteTool) Label 

func (t *WriteTool) Label() string

func (*WriteTool) Name 

func (t *WriteTool) Name() string

func (*WriteTool) Preview added in v1.5.5 

func (t *WriteTool) Preview(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

func (*WriteTool) ReadOnly added in v1.6.0 

func (t *WriteTool) ReadOnly(_ json.RawMessage) bool

func (*WriteTool) Schema 

func (t *WriteTool) Schema() map[string]any

func (*WriteTool) Validate added in v1.6.9 

func (t *WriteTool) Validate(ctx context.Context, args json.RawMessage) agentcore.ValidationResult

Validate enforces read-before-write and detects stale writes.

Error codes (stable for tests):

  • 2: existing file has not been read this session, or only a partial slice was read.
  • 3: file was modified after the last read.

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.