tools

package
v0.0.32 Latest Latest
Warning

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

Go to latest
Published: Jan 16, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Overview

Package tools provides a permission-aware local tool system for term-llm.

Index

Constants

View Source
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

View Source
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.

View Source
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.

View Source
var MutatorKinds = []ToolKind{KindEdit, KindExecute}

MutatorKinds are tool kinds that can modify the filesystem.

View Source
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.

View Source
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 AllToolNames

func AllToolNames() []string

AllToolNames returns all valid CLI tool names.

func ClearApprovalHooks

func ClearApprovalHooks()

ClearApprovalHooks removes the approval hooks.

func ClearAskUserHooks added in v0.0.30

func ClearAskUserHooks()

ClearAskUserHooks removes the ask_user hooks.

func ExtractCommandPrefix

func ExtractCommandPrefix(cmd string) string

ExtractCommandPrefix extracts a shell command prefix for policy learning.

func GenerateDiff

func GenerateDiff(oldContent, newContent, filePath string) string

GenerateDiff creates a unified diff between old and new content.

func ParseImageData

func ParseImageData(result string) (mimeType string, base64Data string, ok bool)

ParseImageData extracts image data from a view_image tool result. Returns mime type and base64 data if found.

func ParseToolsFlag

func ParseToolsFlag(value string) []string

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

func ValidToolName(name string) bool

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

func (c *ApprovalCache) Clear()

Clear removes all cached approvals.

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

type AskUserOption struct {
	Label       string `json:"label"`
	Description string `json:"description"`
}

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 NewDirCache

func NewDirCache() *DirCache

NewDirCache creates a new DirCache.

func (*DirCache) Get

func (c *DirCache) Get(dir string) (ConfirmOutcome, bool)

Get checks if a directory is approved.

func (*DirCache) IsPathInApprovedDir

func (c *DirCache) IsPathInApprovedDir(path string) bool

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 GlobArgs

type GlobArgs struct {
	Pattern string `json:"pattern"`
	Path    string `json:"path,omitempty"`
}

GlobArgs are the arguments for glob.

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.

func (*GlobTool) Execute

func (t *GlobTool) Execute(ctx context.Context, args json.RawMessage) (string, error)

func (*GlobTool) Preview

func (t *GlobTool) Preview(args json.RawMessage) string

func (*GlobTool) Spec

func (t *GlobTool) Spec() llm.ToolSpec

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.

func (*GrepTool) Execute

func (t *GrepTool) Execute(ctx context.Context, args json.RawMessage) (string, error)

func (*GrepTool) Preview

func (t *GrepTool) Preview(args json.RawMessage) string

func (*GrepTool) Spec

func (t *GrepTool) Spec() llm.ToolSpec

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.

func (*ShellTool) Execute

func (t *ShellTool) Execute(ctx context.Context, args json.RawMessage) (string, error)

func (*ShellTool) Preview

func (t *ShellTool) Preview(args json.RawMessage) string

func (*ShellTool) Spec

func (t *ShellTool) Spec() llm.ToolSpec

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.

func (*ToolError) Error

func (e *ToolError) Error() string

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.

const (
	KindRead        ToolKind = "read"
	KindEdit        ToolKind = "edit"
	KindSearch      ToolKind = "search"
	KindExecute     ToolKind = "execute"
	KindImage       ToolKind = "image"
	KindInteractive ToolKind = "interactive"
)

func GetToolKind

func GetToolKind(specName string) ToolKind

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

type WriteFileArgs struct {
	FilePath string `json:"file_path"`
	Content  string `json:"content"`
}

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL