Documentation
¶
Overview ¶
Package tools provides a permission-aware local tool system for term-llm.
Index ¶
- Constants
- Variables
- func AllToolNames() []string
- func ClearApprovalHooks()
- func ClearAskUserHooks()
- func ExtractCommandPrefix(cmd string) string
- func GenerateDiff(oldContent, newContent, filePath string) string
- func ParseImageData(result string) (mimeType string, base64Data string, ok bool)
- func ParseToolsFlag(value string) []string
- func SetApprovalHooks(onStart, onEnd func())
- func SetAskUserHooks(onStart, onEnd func())
- func ValidToolName(name string) bool
- type ApprovalCache
- func (c *ApprovalCache) Clear()
- func (c *ApprovalCache) Get(toolName, path string) (ConfirmOutcome, bool)
- func (c *ApprovalCache) GetForDirectory(toolName, dir string) (ConfirmOutcome, bool)
- func (c *ApprovalCache) Set(toolName, path string, outcome ConfirmOutcome)
- func (c *ApprovalCache) SetForDirectory(toolName, dir string, outcome ConfirmOutcome)
- type ApprovalManager
- func (m *ApprovalManager) ApproveDirectory(toolName, dir string, outcome ConfirmOutcome)
- func (m *ApprovalManager) ApprovePath(toolName, path string, outcome ConfirmOutcome)
- func (m *ApprovalManager) ApproveShellPattern(pattern string)
- func (m *ApprovalManager) CheckPathApproval(toolName, path, toolInfo string, isWrite bool) (ConfirmOutcome, error)
- func (m *ApprovalManager) CheckShellApproval(command string) (ConfirmOutcome, error)
- type ApprovalRequest
- type AskUserAnswer
- type AskUserArgs
- type AskUserOption
- type AskUserQuestion
- type AskUserResult
- type AskUserTool
- type Attachment
- type ConfirmOutcome
- type DirCache
- type EditFileArgs
- type EditFileTool
- type FileEntry
- type GlobArgs
- type GlobTool
- type GrepArgs
- type GrepMatch
- type GrepTool
- type ImageGenerateArgs
- type ImageGenerateTool
- type LocalToolRegistry
- func (r *LocalToolRegistry) AddReadDir(dir string) error
- func (r *LocalToolRegistry) AddShellPattern(pattern string) error
- func (r *LocalToolRegistry) AddWriteDir(dir string) error
- func (r *LocalToolRegistry) Get(specName string) (llm.Tool, bool)
- func (r *LocalToolRegistry) GetSpecs() []llm.ToolSpec
- func (r *LocalToolRegistry) IsEnabled(cliName string) bool
- func (r *LocalToolRegistry) Permissions() *ToolPermissions
- func (r *LocalToolRegistry) RegisterWithEngine(engine *llm.Engine)
- func (r *LocalToolRegistry) SetLimits(limits OutputLimits)
- type OutputLimits
- type ReadFileArgs
- type ReadFileTool
- type ShellApprovalCache
- type ShellArgs
- type ShellResult
- type ShellTool
- type ToolConfig
- func (c *ToolConfig) BuildPermissions() (*ToolPermissions, error)
- func (c *ToolConfig) CanAutoRunShell() bool
- func (c *ToolConfig) CanRunShellNonTTY() bool
- func (c *ToolConfig) EnabledSpecNames() []string
- func (c *ToolConfig) IsToolEnabled(cliName string) bool
- func (c ToolConfig) Merge(other ToolConfig) ToolConfig
- func (c *ToolConfig) Validate() []error
- type ToolDisplay
- type ToolError
- type ToolErrorType
- type ToolKind
- type ToolManager
- type ToolMetadata
- type ToolPayload
- type ToolPermissions
- func (p *ToolPermissions) AddReadDir(dir string) error
- func (p *ToolPermissions) AddShellPattern(pattern string) error
- func (p *ToolPermissions) AddWriteDir(dir string) error
- func (p *ToolPermissions) CheckSymlinkEscape(path string, allowedDirs []string) error
- func (p *ToolPermissions) CompileShellPatterns() error
- func (p *ToolPermissions) IsPathAllowedForRead(path string) (bool, error)
- func (p *ToolPermissions) IsPathAllowedForWrite(path string) (bool, error)
- func (p *ToolPermissions) IsShellCommandAllowed(command string) bool
- type ViewImageArgs
- type ViewImageTool
- type WriteFileArgs
- type WriteFileTool
Constants ¶
const ( ReadFileToolName = "read_file" WriteFileToolName = "write_file" EditFileToolName = "edit_file" ShellToolName = "shell" GrepToolName = "grep" GlobToolName = "glob" ViewImageToolName = "view_image" ImageGenerateToolName = "image_generate" AskUserToolName = "ask_user" )
Tool specification names
Variables ¶
var ( OnApprovalStart func() // Called before showing prompt (pause TUI) OnApprovalEnd func() // Called after prompt answered (resume TUI) )
ApprovalUIHooks allows the TUI to coordinate with approval prompts. Set these callbacks before running the ask command to pause/resume the UI.
var ( OnAskUserStart func() // Called before showing ask_user UI (pause TUI) OnAskUserEnd func() // Called after ask_user UI answered (resume TUI) )
AskUserUIHooks allows the TUI to coordinate with ask_user tool prompts.
var MutatorKinds = []ToolKind{KindEdit, KindExecute}
MutatorKinds are tool kinds that can modify the filesystem.
var SpecToCliName = map[string]string{ ReadFileToolName: "read", WriteFileToolName: "write", EditFileToolName: "edit", ShellToolName: "shell", GrepToolName: "grep", GlobToolName: "find", ViewImageToolName: "view", ImageGenerateToolName: "image", AskUserToolName: "ask_user", }
SpecToCliName returns the CLI name for a tool spec name.
var ToolNameMapping = map[string]string{ "read": ReadFileToolName, "write": WriteFileToolName, "edit": EditFileToolName, "shell": ShellToolName, "grep": GrepToolName, "find": GlobToolName, "view": ViewImageToolName, "image": ImageGenerateToolName, "ask_user": AskUserToolName, }
CLI name to spec name mapping
Functions ¶
func ClearAskUserHooks ¶ added in v0.0.30
func ClearAskUserHooks()
ClearAskUserHooks removes the ask_user hooks.
func ExtractCommandPrefix ¶
ExtractCommandPrefix extracts a shell command prefix for policy learning.
func GenerateDiff ¶
GenerateDiff creates a unified diff between old and new content.
func ParseImageData ¶
ParseImageData extracts image data from a view_image tool result. Returns mime type and base64 data if found.
func ParseToolsFlag ¶
ParseToolsFlag parses a comma-separated list of tool names. Special values: "all" or "*" expand to all available tools.
func SetApprovalHooks ¶
func SetApprovalHooks(onStart, onEnd func())
SetApprovalHooks sets callbacks for TUI coordination during approval prompts.
func SetAskUserHooks ¶ added in v0.0.30
func SetAskUserHooks(onStart, onEnd func())
SetAskUserHooks sets callbacks for TUI coordination during ask_user prompts.
func ValidToolName ¶
ValidToolName checks if a name is a valid CLI tool name.
Types ¶
type ApprovalCache ¶
type ApprovalCache struct {
// contains filtered or unexported fields
}
ApprovalCache provides session-scoped caching for tool+path decisions.
func NewApprovalCache ¶
func NewApprovalCache() *ApprovalCache
NewApprovalCache creates a new ApprovalCache.
func (*ApprovalCache) Get ¶
func (c *ApprovalCache) Get(toolName, path string) (ConfirmOutcome, bool)
Get retrieves a cached approval decision.
func (*ApprovalCache) GetForDirectory ¶
func (c *ApprovalCache) GetForDirectory(toolName, dir string) (ConfirmOutcome, bool)
GetForDirectory checks if there's an approval for a directory.
func (*ApprovalCache) Set ¶
func (c *ApprovalCache) Set(toolName, path string, outcome ConfirmOutcome)
Set stores an approval decision.
func (*ApprovalCache) SetForDirectory ¶
func (c *ApprovalCache) SetForDirectory(toolName, dir string, outcome ConfirmOutcome)
SetForDirectory stores an approval for all paths under a directory. This is used when user approves "always" for a directory.
type ApprovalManager ¶
type ApprovalManager struct {
// Callback for prompting user (set by TUI or CLI)
PromptFunc func(req *ApprovalRequest) (ConfirmOutcome, string)
// contains filtered or unexported fields
}
ApprovalManager coordinates approval requests and caching.
func NewApprovalManager ¶
func NewApprovalManager(perms *ToolPermissions) *ApprovalManager
NewApprovalManager creates a new ApprovalManager.
func (*ApprovalManager) ApproveDirectory ¶
func (m *ApprovalManager) ApproveDirectory(toolName, dir string, outcome ConfirmOutcome)
ApproveDirectory adds a directory approval to the session cache.
func (*ApprovalManager) ApprovePath ¶
func (m *ApprovalManager) ApprovePath(toolName, path string, outcome ConfirmOutcome)
ApprovePath adds a path/directory approval to the session cache.
func (*ApprovalManager) ApproveShellPattern ¶
func (m *ApprovalManager) ApproveShellPattern(pattern string)
ApproveShellPattern adds a pattern to the session cache.
func (*ApprovalManager) CheckPathApproval ¶
func (m *ApprovalManager) CheckPathApproval(toolName, path, toolInfo string, isWrite bool) (ConfirmOutcome, error)
CheckPathApproval checks if a path is approved for the given tool. Approvals are directory-scoped and tool-agnostic - approving a directory for one tool allows all tools to access files within it. toolInfo is optional context for display (e.g., filename being accessed).
func (*ApprovalManager) CheckShellApproval ¶
func (m *ApprovalManager) CheckShellApproval(command string) (ConfirmOutcome, error)
CheckShellApproval checks if a shell command is approved.
type ApprovalRequest ¶
type ApprovalRequest struct {
ToolName string
Path string // For file tools
Command string // For shell tool
Description string // Human-readable description
Options []string // Directory options for file tools
ToolInfo string // Preview info for display (filename, URL, etc.)
// Callbacks
OnApprove func(choice string, saveToConfig bool) // choice is dir path or pattern
OnDeny func()
}
ApprovalRequest represents a pending approval request.
type AskUserAnswer ¶ added in v0.0.30
type AskUserAnswer struct {
QuestionIndex int `json:"question_index"`
Header string `json:"header"`
Selected string `json:"selected"`
IsCustom bool `json:"is_custom"`
}
AskUserAnswer represents the user's answer to a question.
func RunAskUser ¶ added in v0.0.30
func RunAskUser(questions []AskUserQuestion) ([]AskUserAnswer, error)
RunAskUser presents the questions to the user and returns their answers.
type AskUserArgs ¶ added in v0.0.30
type AskUserArgs struct {
Questions []AskUserQuestion `json:"questions"`
}
AskUserArgs are the arguments passed to the ask_user tool.
type AskUserOption ¶ added in v0.0.30
AskUserOption represents a choice for a question.
type AskUserQuestion ¶ added in v0.0.30
type AskUserQuestion struct {
Header string `json:"header"`
Question string `json:"question"`
Options []AskUserOption `json:"options"`
}
AskUserQuestion represents a question to present to the user.
type AskUserResult ¶ added in v0.0.30
type AskUserResult struct {
Answers []AskUserAnswer `json:"answers,omitempty"`
Error string `json:"error,omitempty"`
Type string `json:"type,omitempty"`
}
AskUserResult is the complete result returned by the tool.
type AskUserTool ¶ added in v0.0.30
type AskUserTool struct{}
AskUserTool implements the ask_user tool.
func NewAskUserTool ¶ added in v0.0.30
func NewAskUserTool() *AskUserTool
NewAskUserTool creates a new ask_user tool.
func (*AskUserTool) Execute ¶ added in v0.0.30
func (t *AskUserTool) Execute(ctx context.Context, args json.RawMessage) (string, error)
Execute runs the ask_user tool.
func (*AskUserTool) Preview ¶ added in v0.0.30
func (t *AskUserTool) Preview(args json.RawMessage) string
Preview returns a short description of the tool call.
func (*AskUserTool) Spec ¶ added in v0.0.30
func (t *AskUserTool) Spec() llm.ToolSpec
Spec returns the tool specification.
type Attachment ¶
type Attachment struct {
Path string `json:"path"`
MimeType string `json:"mime_type,omitempty"`
Data []byte `json:"data,omitempty"`
}
Attachment represents a file attachment in tool results.
type ConfirmOutcome ¶
type ConfirmOutcome string
ConfirmOutcome represents the result of a user confirmation prompt.
const ( ProceedOnce ConfirmOutcome = "once" // Single approval ProceedAlways ConfirmOutcome = "always" // Session-scoped approval ProceedAlwaysAndSave ConfirmOutcome = "always_save" // Persist to config Cancel ConfirmOutcome = "cancel" // User denied )
func HuhApprovalPrompt ¶
func HuhApprovalPrompt(req *ApprovalRequest) (ConfirmOutcome, string)
HuhApprovalPrompt prompts the user for approval using a huh form. This provides a nicer UI than the TTY-based prompt.
func TTYApprovalPrompt ¶
func TTYApprovalPrompt(req *ApprovalRequest) (ConfirmOutcome, string)
TTYApprovalPrompt prompts the user for directory access approval via /dev/tty. This allows prompting even when stdin is piped.
type DirCache ¶
type DirCache struct {
// contains filtered or unexported fields
}
DirCache provides tool-agnostic directory approval caching. When a directory is approved, all tools can access files within it.
func (*DirCache) Get ¶
func (c *DirCache) Get(dir string) (ConfirmOutcome, bool)
Get checks if a directory is approved.
func (*DirCache) IsPathInApprovedDir ¶
IsPathInApprovedDir checks if a path is within any approved directory.
func (*DirCache) Set ¶
func (c *DirCache) Set(dir string, outcome ConfirmOutcome)
Set stores a directory approval.
type EditFileArgs ¶
type EditFileArgs struct {
FilePath string `json:"file_path"`
// Mode 1: Delegated edit (natural language)
Instructions string `json:"instructions,omitempty"`
LineRange string `json:"line_range,omitempty"` // e.g., "10-20"
// Mode 2: Direct edit (deterministic)
OldText string `json:"old_text,omitempty"`
NewText string `json:"new_text,omitempty"`
}
EditFileArgs supports two modes: - Mode 1 (Delegated): instructions + optional line_range - Mode 2 (Direct): old_text + new_text
type EditFileTool ¶
type EditFileTool struct {
// contains filtered or unexported fields
}
EditFileTool implements the edit_file tool with dual modes.
func NewEditFileTool ¶
func NewEditFileTool(approval *ApprovalManager) *EditFileTool
NewEditFileTool creates a new EditFileTool.
func (*EditFileTool) Execute ¶
func (t *EditFileTool) Execute(ctx context.Context, args json.RawMessage) (string, error)
func (*EditFileTool) Preview ¶
func (t *EditFileTool) Preview(args json.RawMessage) string
func (*EditFileTool) Spec ¶
func (t *EditFileTool) Spec() llm.ToolSpec
type FileEntry ¶
type FileEntry struct {
FilePath string `json:"file_path"`
IsDir bool `json:"is_dir"`
SizeBytes int64 `json:"size_bytes"`
ModTime time.Time `json:"mod_time"`
}
FileEntry represents a file in glob results.
type GlobTool ¶
type GlobTool struct {
// contains filtered or unexported fields
}
GlobTool implements the glob tool.
func NewGlobTool ¶
func NewGlobTool(approval *ApprovalManager) *GlobTool
NewGlobTool creates a new GlobTool.
type GrepArgs ¶
type GrepArgs struct {
Pattern string `json:"pattern"`
Path string `json:"path,omitempty"`
Include string `json:"include,omitempty"` // glob filter e.g., "*.go"
MaxResults int `json:"max_results,omitempty"`
}
GrepArgs are the arguments for grep.
type GrepMatch ¶
type GrepMatch struct {
FilePath string `json:"file_path"`
LineNumber int `json:"line_number"`
Match string `json:"match"`
Context string `json:"context,omitempty"` // 3 lines of context
}
GrepMatch represents a single grep match.
type GrepTool ¶
type GrepTool struct {
// contains filtered or unexported fields
}
GrepTool implements the grep tool.
func NewGrepTool ¶
func NewGrepTool(approval *ApprovalManager, limits OutputLimits) *GrepTool
NewGrepTool creates a new GrepTool.
type ImageGenerateArgs ¶
type ImageGenerateArgs struct {
Prompt string `json:"prompt"`
InputImage string `json:"input_image,omitempty"` // Path for editing/variation
AspectRatio string `json:"aspect_ratio,omitempty"` // e.g., "16:9", "4:3"
OutputPath string `json:"output_path,omitempty"` // Save location
}
ImageGenerateArgs are the arguments for image_generate.
type ImageGenerateTool ¶
type ImageGenerateTool struct {
// contains filtered or unexported fields
}
ImageGenerateTool implements the image_generate tool.
func NewImageGenerateTool ¶
func NewImageGenerateTool(approval *ApprovalManager, cfg *config.Config, providerOverride string) *ImageGenerateTool
NewImageGenerateTool creates a new ImageGenerateTool.
func (*ImageGenerateTool) Execute ¶
func (t *ImageGenerateTool) Execute(ctx context.Context, args json.RawMessage) (string, error)
func (*ImageGenerateTool) Preview ¶
func (t *ImageGenerateTool) Preview(args json.RawMessage) string
func (*ImageGenerateTool) Spec ¶
func (t *ImageGenerateTool) Spec() llm.ToolSpec
type LocalToolRegistry ¶
type LocalToolRegistry struct {
// contains filtered or unexported fields
}
LocalToolRegistry manages local tools and their registration with the engine.
func NewLocalToolRegistry ¶
func NewLocalToolRegistry(toolConfig *ToolConfig, appConfig *config.Config, approvalMgr *ApprovalManager) (*LocalToolRegistry, error)
NewLocalToolRegistry creates a new registry from configuration. The approvalMgr parameter is used for interactive permission prompts.
func (*LocalToolRegistry) AddReadDir ¶
func (r *LocalToolRegistry) AddReadDir(dir string) error
AddReadDir adds a directory to the read allowlist at runtime.
func (*LocalToolRegistry) AddShellPattern ¶
func (r *LocalToolRegistry) AddShellPattern(pattern string) error
AddShellPattern adds a shell pattern to the allowlist at runtime.
func (*LocalToolRegistry) AddWriteDir ¶
func (r *LocalToolRegistry) AddWriteDir(dir string) error
AddWriteDir adds a directory to the write allowlist at runtime.
func (*LocalToolRegistry) Get ¶
func (r *LocalToolRegistry) Get(specName string) (llm.Tool, bool)
Get returns a tool by spec name.
func (*LocalToolRegistry) GetSpecs ¶
func (r *LocalToolRegistry) GetSpecs() []llm.ToolSpec
GetSpecs returns tool specs for all enabled tools.
func (*LocalToolRegistry) IsEnabled ¶
func (r *LocalToolRegistry) IsEnabled(cliName string) bool
IsEnabled checks if a tool is enabled.
func (*LocalToolRegistry) Permissions ¶
func (r *LocalToolRegistry) Permissions() *ToolPermissions
Permissions returns the underlying permissions manager.
func (*LocalToolRegistry) RegisterWithEngine ¶
func (r *LocalToolRegistry) RegisterWithEngine(engine *llm.Engine)
RegisterWithEngine registers all enabled tools with the LLM engine.
func (*LocalToolRegistry) SetLimits ¶
func (r *LocalToolRegistry) SetLimits(limits OutputLimits)
SetLimits updates the output limits.
type OutputLimits ¶
type OutputLimits struct {
MaxLines int // Max lines for read_file (default 2000)
MaxBytes int64 // Max bytes per tool output (default 50KB)
MaxResults int // Max results for grep/glob (default 100/200)
CumulativeSoft int64 // Soft cumulative limit per turn (default 100KB)
CumulativeHard int64 // Hard cumulative limit per turn (default 200KB)
}
OutputLimits defines limits for tool output.
func DefaultOutputLimits ¶
func DefaultOutputLimits() OutputLimits
DefaultOutputLimits returns the default output limits.
type ReadFileArgs ¶
type ReadFileArgs struct {
FilePath string `json:"file_path"`
StartLine int `json:"start_line,omitempty"`
EndLine int `json:"end_line,omitempty"`
}
ReadFileArgs are the arguments for read_file.
type ReadFileTool ¶
type ReadFileTool struct {
// contains filtered or unexported fields
}
ReadFileTool implements the read_file tool.
func NewReadFileTool ¶
func NewReadFileTool(approval *ApprovalManager, limits OutputLimits) *ReadFileTool
NewReadFileTool creates a new ReadFileTool.
func (*ReadFileTool) Execute ¶
func (t *ReadFileTool) Execute(ctx context.Context, args json.RawMessage) (string, error)
func (*ReadFileTool) Preview ¶
func (t *ReadFileTool) Preview(args json.RawMessage) string
func (*ReadFileTool) Spec ¶
func (t *ReadFileTool) Spec() llm.ToolSpec
type ShellApprovalCache ¶
type ShellApprovalCache struct {
// contains filtered or unexported fields
}
ShellApprovalCache caches shell command pattern approvals for the session.
func NewShellApprovalCache ¶
func NewShellApprovalCache() *ShellApprovalCache
NewShellApprovalCache creates a new ShellApprovalCache.
func (*ShellApprovalCache) AddPattern ¶
func (c *ShellApprovalCache) AddPattern(pattern string)
AddPattern adds a pattern to the session cache.
func (*ShellApprovalCache) GetPatterns ¶
func (c *ShellApprovalCache) GetPatterns() []string
GetPatterns returns all session-approved patterns.
type ShellArgs ¶
type ShellArgs struct {
Command string `json:"command"`
WorkingDir string `json:"working_dir,omitempty"`
TimeoutSeconds int `json:"timeout_seconds,omitempty"`
}
ShellArgs are the arguments for the shell tool.
type ShellResult ¶
type ShellResult struct {
Stdout string `json:"stdout"`
Stderr string `json:"stderr"`
ExitCode int `json:"exit_code"`
TimedOut bool `json:"timed_out,omitempty"`
}
ShellResult contains the result of a shell command.
type ShellTool ¶
type ShellTool struct {
// contains filtered or unexported fields
}
ShellTool implements the shell tool.
func NewShellTool ¶
func NewShellTool(approval *ApprovalManager, config *ToolConfig, limits OutputLimits) *ShellTool
NewShellTool creates a new ShellTool.
type ToolConfig ¶
type ToolConfig struct {
Enabled []string `mapstructure:"enabled"` // Enabled tool names (CLI names)
ReadDirs []string `mapstructure:"read_dirs"` // Directories for read operations
WriteDirs []string `mapstructure:"write_dirs"` // Directories for write operations
ShellAllow []string `mapstructure:"shell_allow"` // Shell command patterns
ShellAutoRun bool `mapstructure:"shell_auto_run"` // Auto-approve matching shell
ShellAutoRunEnv string `mapstructure:"shell_auto_run_env"` // Env var required for auto-run
ShellNonTTYEnv string `mapstructure:"shell_non_tty_env"` // Env var for non-TTY execution
ImageProvider string `mapstructure:"image_provider"` // Override for image provider
}
ToolConfig holds configuration for the local tool system.
func DefaultToolConfig ¶
func DefaultToolConfig() ToolConfig
DefaultToolConfig returns sensible defaults for tool configuration.
func NewToolConfigFromFields ¶
func NewToolConfigFromFields(enabled, readDirs, writeDirs, shellAllow []string, shellAutoRun bool, shellAutoRunEnv, shellNonTTYEnv, imageProvider string) ToolConfig
NewToolConfigFromFields creates a ToolConfig from individual field values. This allows callers from the config package to create ToolConfigs without circular imports.
func (*ToolConfig) BuildPermissions ¶
func (c *ToolConfig) BuildPermissions() (*ToolPermissions, error)
BuildPermissions creates a ToolPermissions from this config.
func (*ToolConfig) CanAutoRunShell ¶
func (c *ToolConfig) CanAutoRunShell() bool
CanAutoRunShell checks if shell commands can be auto-run.
func (*ToolConfig) CanRunShellNonTTY ¶
func (c *ToolConfig) CanRunShellNonTTY() bool
CanRunShellNonTTY checks if shell can run in non-TTY mode.
func (*ToolConfig) EnabledSpecNames ¶
func (c *ToolConfig) EnabledSpecNames() []string
EnabledSpecNames returns the spec names for all enabled tools.
func (*ToolConfig) IsToolEnabled ¶
func (c *ToolConfig) IsToolEnabled(cliName string) bool
IsToolEnabled checks if a tool is enabled.
func (ToolConfig) Merge ¶
func (c ToolConfig) Merge(other ToolConfig) ToolConfig
Merge combines this config with another, with other taking precedence for non-empty values.
func (*ToolConfig) Validate ¶
func (c *ToolConfig) Validate() []error
Validate checks the configuration for errors.
type ToolDisplay ¶
type ToolDisplay struct {
Title string `json:"title,omitempty"`
Preview string `json:"preview,omitempty"`
FilePath string `json:"file_path,omitempty"`
}
ToolDisplay contains optional display metadata for UI.
type ToolError ¶
type ToolError struct {
Type ToolErrorType `json:"type"`
Message string `json:"message"`
}
ToolError provides structured error information for retry logic.
func NewToolError ¶
func NewToolError(errType ToolErrorType, message string) *ToolError
NewToolError creates a new ToolError.
func NewToolErrorf ¶
func NewToolErrorf(errType ToolErrorType, format string, args ...interface{}) *ToolError
NewToolErrorf creates a new ToolError with formatted message.
type ToolErrorType ¶
type ToolErrorType string
ToolErrorType provides structured errors for agent retry logic.
const ( ErrFileNotFound ToolErrorType = "FILE_NOT_FOUND" ErrInvalidParams ToolErrorType = "INVALID_PARAMS" ErrPathNotInWorkspace ToolErrorType = "PATH_NOT_IN_WORKSPACE" ErrExecutionFailed ToolErrorType = "EXECUTION_FAILED" ErrPermissionDenied ToolErrorType = "PERMISSION_DENIED" ErrBinaryFile ToolErrorType = "BINARY_FILE" ErrFileTooLarge ToolErrorType = "FILE_TOO_LARGE" ErrImageGenFailed ToolErrorType = "IMAGE_GEN_FAILED" ErrUnsupportedFormat ToolErrorType = "UNSUPPORTED_FORMAT" ErrTimeout ToolErrorType = "TIMEOUT" ErrSymlinkEscape ToolErrorType = "SYMLINK_ESCAPE" )
type ToolKind ¶
type ToolKind string
ToolKind categorizes tools for permission grouping.
func GetToolKind ¶
GetToolKind returns the kind for a tool spec name.
type ToolManager ¶
type ToolManager struct {
Registry *LocalToolRegistry
ApprovalMgr *ApprovalManager
}
ToolManager provides a high-level interface for tool management in commands.
func NewToolManager ¶
func NewToolManager(toolConfig *ToolConfig, appConfig *config.Config) (*ToolManager, error)
NewToolManager creates a new tool manager from config.
func (*ToolManager) GetSpecs ¶
func (m *ToolManager) GetSpecs() []llm.ToolSpec
GetSpecs returns all tool specs for the request.
func (*ToolManager) SetupEngine ¶
func (m *ToolManager) SetupEngine(engine *llm.Engine)
SetupEngine registers tools with the engine.
type ToolMetadata ¶
type ToolMetadata struct {
ExecutionTimeMs int64 `json:"execution_time_ms"`
PermissionCheckMs int64 `json:"permission_check_ms,omitempty"`
OutputBytes int64 `json:"output_bytes"`
Truncated bool `json:"truncated,omitempty"`
}
ToolMetadata contains execution metrics.
type ToolPayload ¶
type ToolPayload struct {
Output string `json:"output"`
Display *ToolDisplay `json:"display,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
Attachments []Attachment `json:"attachments,omitempty"`
Error *ToolError `json:"error,omitempty"`
}
ToolPayload is an optional JSON payload for tools that need display/metadata. This is encoded in ToolResult.Content when UI metadata is required.
func (*ToolPayload) ToJSON ¶
func (p *ToolPayload) ToJSON() string
ToJSON encodes the payload as JSON for use in ToolResult.Content.
type ToolPermissions ¶
type ToolPermissions struct {
ReadDirs []string // Directories for read/grep/glob/view
WriteDirs []string // Directories for write/edit
ShellAllow []string // Shell command patterns (glob syntax)
// contains filtered or unexported fields
}
ToolPermissions manages allowlists for tool access.
func NewToolPermissions ¶
func NewToolPermissions() *ToolPermissions
NewToolPermissions creates a new ToolPermissions instance.
func (*ToolPermissions) AddReadDir ¶
func (p *ToolPermissions) AddReadDir(dir string) error
AddReadDir adds a directory to the read allowlist.
func (*ToolPermissions) AddShellPattern ¶
func (p *ToolPermissions) AddShellPattern(pattern string) error
AddShellPattern adds a shell command pattern to the allowlist.
func (*ToolPermissions) AddWriteDir ¶
func (p *ToolPermissions) AddWriteDir(dir string) error
AddWriteDir adds a directory to the write allowlist.
func (*ToolPermissions) CheckSymlinkEscape ¶
func (p *ToolPermissions) CheckSymlinkEscape(path string, allowedDirs []string) error
CheckSymlinkEscape checks if a path escapes via symlink. Returns an error if the resolved path is outside the allowed directories.
func (*ToolPermissions) CompileShellPatterns ¶
func (p *ToolPermissions) CompileShellPatterns() error
CompileShellPatterns pre-compiles all shell patterns.
func (*ToolPermissions) IsPathAllowedForRead ¶
func (p *ToolPermissions) IsPathAllowedForRead(path string) (bool, error)
IsPathAllowedForRead checks if a path is allowed for read operations.
func (*ToolPermissions) IsPathAllowedForWrite ¶
func (p *ToolPermissions) IsPathAllowedForWrite(path string) (bool, error)
IsPathAllowedForWrite checks if a path is allowed for write operations.
func (*ToolPermissions) IsShellCommandAllowed ¶
func (p *ToolPermissions) IsShellCommandAllowed(command string) bool
IsShellCommandAllowed checks if a shell command matches any allowlist pattern.
type ViewImageArgs ¶
type ViewImageArgs struct {
FilePath string `json:"file_path"`
Detail string `json:"detail,omitempty"` // "low", "high", or "auto"
}
ViewImageArgs are the arguments for view_image.
type ViewImageTool ¶
type ViewImageTool struct {
// contains filtered or unexported fields
}
ViewImageTool implements the view_image tool.
func NewViewImageTool ¶
func NewViewImageTool(approval *ApprovalManager) *ViewImageTool
NewViewImageTool creates a new ViewImageTool.
func (*ViewImageTool) Execute ¶
func (t *ViewImageTool) Execute(ctx context.Context, args json.RawMessage) (string, error)
func (*ViewImageTool) Preview ¶
func (t *ViewImageTool) Preview(args json.RawMessage) string
func (*ViewImageTool) Spec ¶
func (t *ViewImageTool) Spec() llm.ToolSpec
type WriteFileArgs ¶
WriteFileArgs are the arguments for write_file.
type WriteFileTool ¶
type WriteFileTool struct {
// contains filtered or unexported fields
}
WriteFileTool implements the write_file tool.
func NewWriteFileTool ¶
func NewWriteFileTool(approval *ApprovalManager) *WriteFileTool
NewWriteFileTool creates a new WriteFileTool.
func (*WriteFileTool) Execute ¶
func (t *WriteFileTool) Execute(ctx context.Context, args json.RawMessage) (string, error)
func (*WriteFileTool) Preview ¶
func (t *WriteFileTool) Preview(args json.RawMessage) string
func (*WriteFileTool) Spec ¶
func (t *WriteFileTool) Spec() llm.ToolSpec