tools

package
v1.5.8 Latest Latest
Warning

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

 Go to latest Published: Mar 30, 2026 License: Apache-2.0 Imports: 29 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 BackgroundShell added in v1.5.3 

type BackgroundShell struct {
	ID          string
	Command     string
	Description string
	Status      string // "running" | "completed" | "failed"
	StartedAt   time.Time
	EndedAt     time.Time
	OutputFile  string // path to output file on disk
	ExitCode    int
	PID         int
	// contains filtered or unexported fields
}

BackgroundShell tracks a background shell command's lifecycle. Output is written to a file on disk (OutputFile) instead of memory.

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) BackgroundShells added in v1.5.3 

func (t *BashTool) BackgroundShells() []BackgroundShell

BackgroundShells returns a snapshot of all background shells.

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) 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) StopAllBackgroundShells added in v1.5.3 

func (t *BashTool) StopAllBackgroundShells() int

StopAllBackgroundShells cancels all running background shells.

func (*BashTool) StopBackgroundShell added in v1.5.3 

func (t *BashTool) StopBackgroundShell(id string) bool

StopBackgroundShell cancels a running background shell by ID.

type EditTool 

type EditTool struct {
	WorkDir string
}

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

func NewEdit 

func NewEdit(workDir string) *EditTool

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) Schema 

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

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) 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) 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) 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) 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) 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) Schema 

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

type ReadTool 

type ReadTool struct {
	WorkDir string
}

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.

func NewRead 

func NewRead(workDir string) *ReadTool

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) 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) 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) 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
}

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

func NewWrite 

func NewWrite(workDir string) *WriteTool

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) Schema 

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

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.