tools

package
v1.6.11 Latest Latest
Warning

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

 Go to latest Published: Jun 4, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

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.