tools

package
v1.7.1 Latest Latest
Warning

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

 Go to latest Published: Jun 20, 2026 License: Apache-2.0 Imports: 31 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 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.

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

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(_ 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 FileReadStamp added in v1.6.9 

type FileReadStamp struct {
	ReadAt  time.Time
	Mtime   time.Time
	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.

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

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

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(_ 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(_ 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(_ 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.