tools

Documentation

Index

• func ExecuteToolContent(ctx context.Context, t Tool, args map[string]any) ([]ai.ContentBlock, error)
• func IsBinary(data string) bool
• func ResolvePath(workDir, path string) (string, error)
• func ResolveProjectPath(projectRoot, path string) (string, error)
• func SplitLines(text string) []string
• func StringArg(args map[string]any, keys ...string) string
• func VisionFromContext(ctx context.Context) bool
• func WithVision(ctx context.Context, supported bool) context.Context
• type ContentTool
• type Definition
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) BuiltinNames() []string
  • func (r *Registry) Close() error
  • func (r *Registry) Definitions() []Definition
  • func (r *Registry) Execute(ctx context.Context, name string, args map[string]any) (string, error)
  • func (r *Registry) ExecuteContent(ctx context.Context, name string, args map[string]any) ([]ai.ContentBlock, error)
  • func (r *Registry) Has(name string) bool
  • func (r *Registry) Register(t Tool)
• type Tool
• type TruncatedBy
• type TruncationResult
  • func TruncateHead(output string) TruncationResult
  • func TruncateTail(output string) TruncationResult

Functions

func ExecuteToolContent

func ExecuteToolContent(ctx context.Context, t Tool, args map[string]any) ([]ai.ContentBlock, error)

ExecuteToolContent runs a tool and returns its result as content blocks. Tools implementing ContentTool are called directly; others have their string output wrapped in a single TextContent block. Any partial text is preserved alongside an error so callers can surface it.

func IsBinary

func IsBinary(data string) bool

IsBinary reports whether data appears to be binary (non-text) content. It samples up to the first 8KB and checks for a high ratio of non-UTF-8 bytes or null bytes, which are reliable indicators of binary data.

func ResolvePath

func ResolvePath(workDir, path string) (string, error)

ResolvePath resolves path relative to workDir when it is not already absolute.

func ResolveProjectPath

func ResolveProjectPath(projectRoot, path string) (string, error)

ResolveProjectPath resolves path relative to projectRoot when it is not already absolute. Relative paths require a non-empty project root.

func SplitLines

func SplitLines(text string) []string

SplitLines splits text into lines preserving newline suffixes. Trims the trailing empty element that strings.SplitAfter produces.

func StringArg

func StringArg(args map[string]any, keys ...string) string

StringArg returns the first non-empty string value found for the provided keys.

func VisionFromContext

func VisionFromContext(ctx context.Context) bool

VisionFromContext reports whether the active model accepts images. It defaults to true (fail-open) when unset, so image-capable behavior is the default and only models explicitly known to lack vision trigger text fallbacks.

func WithVision

func WithVision(ctx context.Context, supported bool) context.Context

WithVision records whether the active model can accept image input, so tools (e.g. read) can decide whether to return images inline or fall back to text.

Types

type ContentTool

type ContentTool interface {
	ExecuteContent(ctx context.Context, args map[string]any) ([]ai.ContentBlock, error)
}

ContentTool is an optional interface for tools whose result may include non-text content (e.g. images). Tools that only emit text need not implement it; ExecuteToolContent wraps their string output automatically.

type Definition

type Definition = ai.ToolDefinition

Definition is a callable tool definition exposed to a model.

type Registry

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

Registry holds named tools and provides lookup + definitions.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates an empty tool registry. Tools are registered externally via Register().

func (*Registry) BuiltinNames

func (r *Registry) BuiltinNames() []string

BuiltinNames returns the names of all currently registered tools.

func (*Registry) Close

func (r *Registry) Close() error

Close shuts down any tools that expose a Close method.

func (*Registry) Definitions

func (r *Registry) Definitions() []Definition

Definitions returns all tool definitions for passing to the LLM.

func (*Registry) Execute

func (r *Registry) Execute(ctx context.Context, name string, args map[string]any) (string, error)

Execute runs the named tool with given arguments.

func (*Registry) ExecuteContent

func (r *Registry) ExecuteContent(ctx context.Context, name string, args map[string]any) ([]ai.ContentBlock, error)

ExecuteContent runs the named tool and returns its result as content blocks, preserving non-text content (e.g. images) from tools that emit it.

func (*Registry) Has

func (r *Registry) Has(name string) bool

Has reports whether the registry contains a tool with the given name.

func (*Registry) Register

func (r *Registry) Register(t Tool)

Register adds a tool to the registry.

type Tool

type Tool interface {
	Definition() Definition
	Execute(ctx context.Context, args map[string]any) (string, error)
}

Tool is a tool that can be executed by the Go runner.

type TruncatedBy

type TruncatedBy string

const (
	TruncatedByNone  TruncatedBy = ""
	TruncatedByLines TruncatedBy = "lines"
	TruncatedByBytes TruncatedBy = "bytes"
)

type TruncationResult

type TruncationResult struct {
	Content               string
	Truncated             bool
	TruncatedBy           TruncatedBy
	TotalLines            int
	TotalBytes            int
	OutputLines           int
	OutputBytes           int
	LastLinePartial       bool
	FirstLineExceedsLimit bool
	MaxLines              int
	MaxBytes              int
}

TruncationResult holds truncated output plus metadata about what happened. Content remains the user-facing string, including truncation headers/footers.

func TruncateHead

func TruncateHead(output string) TruncationResult

TruncateHead keeps the first N lines / bytes (whichever limit is hit first). Suitable for file reads and search results where the beginning matters most. Never returns a partial line.

func TruncateTail

func TruncateTail(output string) TruncationResult

TruncateTail keeps the last N lines / bytes (whichever limit is hit first). Suitable for command output and logs where the end matters most. When the last line alone exceeds the byte limit, it keeps a UTF-8-safe tail slice.