Documentation
¶
Overview ¶
Package tool defines the tool interface and collection operations.
Index ¶
- Variables
- func ComposeDescription(t Tool) string
- func FileError(op, path string, err error) error
- func HTTPError(host string, statusCode int) error
- func NetworkError(host string, err error) error
- func ResolvePath(ctx context.Context, path string) string
- func SDKContextFromContext(ctx context.Context) any
- func ValidateInput[T any](args map[string]any, schema Schema) (*T, error)
- func ValidatePath(path string) error
- func WithSDKContext(ctx context.Context, sc any) context.Context
- func WithStreamCallback(ctx context.Context, cb StreamCallback) context.Context
- func WithWorkDir(ctx context.Context, dir string) context.Context
- func WorkDirFromContext(ctx context.Context) string
- type Base
- type Closer
- type Filter
- type LSPAware
- type Overrider
- type ParallelOverride
- type Parameters
- type PathDeclarer
- type PostHook
- type PreHook
- type Previewer
- type Property
- type ReadBeforePolicy
- type SandboxOverride
- type Schema
- type Schemas
- type StreamCallback
- type Text
- type Tool
- type Tools
- func (ts *Tools) Add(t Tool)
- func (ts Tools) ExcludeOptIn(optIn, enabled []string) Tools
- func (ts Tools) Filtered(include, exclude []string) Tools
- func (ts Tools) Get(name string) (Tool, error)
- func (ts Tools) Has(name string) bool
- func (ts Tools) Names() []string
- func (ts *Tools) Remove(name string)
- func (ts Tools) Schemas() Schemas
Constants ¶
This section is empty.
Variables ¶
var ErrToolCallParse = errors.New("tool call parse error")
ErrToolCallParse indicates a provider returned tool calls with unparseable JSON arguments. The assistant loop can detect this with errors.Is() to retry instead of terminating.
var ErrToolNotFound = errors.New("tool not found")
Functions ¶
func ComposeDescription ¶
ComposeDescription builds the full tool description from Description, Usage, and Examples. Used by GenerateSchema and by tools that build Schema dynamically (plugins).
func FileError ¶
FileError produces a clean, single-line error for LLM consumption. It unwraps through godyl's wrapping layers to the root OS error, classifies it, and returns "op path: reason" without stuttering.
Uses %v (not %w) because tool Execute() errors are terminal text for the LLM — they are never inspected with errors.Is() by Go callers.
func HTTPError ¶
HTTPError produces a clean, single-line error for LLM consumption from non-200 HTTP status codes.
func NetworkError ¶
NetworkError produces a clean, single-line error for LLM consumption from network/HTTP client errors. It classifies timeouts, DNS failures, and connection errors into actionable messages.
func ResolvePath ¶
ResolvePath converts a relative path to absolute using the context's workdir. Absolute paths and empty workdir are returned as-is.
func SDKContextFromContext ¶
SDKContextFromContext extracts the SDK context from the Go context, or nil.
func ValidateInput ¶
ValidateInput converts a map to a typed struct and validates it. Rejects unknown fields and enriches errors with valid parameter names.
func WithSDKContext ¶
WithSDKContext returns a derived context carrying an SDK context value. The value is typed as any because this package cannot import sdk.
func WithStreamCallback ¶
func WithStreamCallback(ctx context.Context, cb StreamCallback) context.Context
WithStreamCallback returns a derived context carrying a streaming callback.
func WithWorkDir ¶
WithWorkDir returns a derived context carrying the effective working directory.
func WorkDirFromContext ¶
WorkDirFromContext extracts the working directory from the context, or "".
Types ¶
type Base ¶
type Base struct {
Text Text
}
Base provides default accessors for Description(), Usage(), Examples(), and Available() (true). Embed in tool structs to avoid boilerplate for the core text methods. Optional behaviors (Pre/Post hooks, path declaration, sandbox/parallel overrides, LSP, etc.) are expressed as separate opt-in interfaces — implement only the ones your tool needs.
func (Base) Description ¶
type Closer ¶
type Closer interface {
Close()
}
Closer is optionally implemented by tools needing cleanup on session end.
type Filter ¶
type Filter struct {
// Enabled lists tool name patterns to include. Empty = all tools.
Enabled []string
// Disabled lists tool name patterns to exclude. Takes precedence over Enabled.
Disabled []string
}
Filter defines enabled/disabled glob patterns for tool filtering. Used by agents, modes, and tasks to control tool availability. Patterns support '*' wildcards (e.g. "mcp__*", "Todo*").
type LSPAware ¶
type LSPAware interface {
WantsLSP() bool
}
LSPAware is optionally implemented by tools whose output benefits from LSP diagnostics on modified files.
type Overrider ¶
type Overrider interface {
Overrides() bool
}
Overrider is optionally implemented by plugin tools that replace built-in tools.
type ParallelOverride ¶
type ParallelOverride interface {
Parallel() bool
}
ParallelOverride is optionally implemented by tools that override the default parallel=true behavior.
type Parameters ¶
Parameters describes the input parameters for a tool.
type PathDeclarer ¶
type PathDeclarer interface {
Paths(ctx context.Context, args map[string]any) (read, write []string, err error)
}
PathDeclarer is optionally implemented by tools that declare filesystem paths for sandbox pre-filtering.
type PostHook ¶
PostHook is optionally implemented by tools that need state updates after execution (e.g. filetime recording).
type PreHook ¶
PreHook is optionally implemented by tools that need validation before execution (e.g. filetime read-before-write enforcement).
type Previewer ¶
Previewer is optionally implemented by tools that can generate a diff preview for confirmation dialogs.
type Property ¶
type Property struct {
Type string
Description string
Enum []any
// Items describes the element type for arrays (e.g., array of objects).
Items *Property
// Properties and Required describe fields for object types.
Properties map[string]Property
Required []string
}
Property describes a single parameter. Supports nested schemas: Items for array element types, Properties/Required for object fields.
type ReadBeforePolicy ¶
type ReadBeforePolicy struct {
Write bool // require read before overwriting existing files (default: true)
Delete bool // require read before deleting files (default: false)
}
ReadBeforePolicy controls which file operations require a prior read.
func DefaultReadBeforePolicy ¶
func DefaultReadBeforePolicy() ReadBeforePolicy
DefaultReadBeforePolicy returns the default policy: write enforcement on, delete off.
type SandboxOverride ¶
type SandboxOverride interface {
Sandboxable() bool
}
SandboxOverride is optionally implemented by tools that override the default sandboxable=true behavior.
type Schema ¶
type Schema struct {
Name string
Description string
Parameters Parameters
}
Schema represents a provider-agnostic tool definition.
func GenerateSchema ¶
GenerateSchema creates a tool schema from a type using JSON schema reflection.
func (Schema) ParamNames ¶
ParamNames returns sorted parameter names for error messages.
type StreamCallback ¶
type StreamCallback func(line string)
StreamCallback is called with each complete line of output during streaming execution.
func StreamCallbackFromContext ¶
func StreamCallbackFromContext(ctx context.Context) StreamCallback
StreamCallbackFromContext extracts the streaming callback from the context, or nil.
type Text ¶
type Text struct {
Description string `yaml:"description"`
Usage string `yaml:"usage"`
Examples string `yaml:"examples"`
}
Text holds the user-facing text for a tool (description, usage instructions, examples). Loaded from Go defaults and optionally overridden by YAML config.
type Tool ¶
type Tool interface {
Name() string
Description() string
Usage() string
Examples() string
Schema() Schema
Execute(ctx context.Context, args map[string]any) (string, error)
Available() bool
}
Tool represents a callable tool for LLM function calling.
type Tools ¶
type Tools []Tool
Tools is a collection of tools.
func (Tools) ExcludeOptIn ¶
ExcludeOptIn removes tools that are in the optIn set unless they are explicitly mentioned (by name or narrow glob) in the enabled patterns. Bare "*" does not satisfy opt-in — only explicit names or narrow globs do.
Source Files
Directories