tools

package
v0.3.29-beta Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package tools defines interfaces and types for kodelet's tool system including tool execution, result structures, state management, and JSON schema generation for LLM tool integration.

Index

Constants

View Source 
const (
	// ApplyPatchOperationAdd indicates a file add operation.
	ApplyPatchOperationAdd = "add"
	// ApplyPatchOperationDelete indicates a file delete operation.
	ApplyPatchOperationDelete = "delete"
	// ApplyPatchOperationUpdate indicates a file update operation.
	ApplyPatchOperationUpdate = "update"
)
View Source 
const (
	GrepTruncatedByFileLimit  = "file_limit"
	GrepTruncatedByOutputSize = "output_size"
)

GrepTruncationReason constants for truncation messaging

Variables

This section is empty.

Functions

func ExtractMetadata 

func ExtractMetadata(metadata ToolMetadata, target any) bool

ExtractMetadata is a helper that handles both pointer and value type assertions This is necessary because JSON unmarshaling creates value types, while direct creation uses pointer types

func StringifyToolResult 

func StringifyToolResult(result, err string) string

StringifyToolResult formats a tool result and optional error into a string representation

Types

type ApplyPatchChange 

type ApplyPatchChange struct {
	Path        string `json:"path"`
	Operation   string `json:"operation"` // add|delete|update
	OldContent  string `json:"oldContent,omitempty"`
	NewContent  string `json:"newContent,omitempty"`
	UnifiedDiff string `json:"unifiedDiff,omitempty"`
	MovePath    string `json:"movePath,omitempty"`
}

ApplyPatchChange describes one file-level change from an apply_patch invocation.

type ApplyPatchInput 

type ApplyPatchInput struct {
	Input string `json:"input" jsonschema:"description=The entire contents of the apply_patch command"`
}

ApplyPatchInput defines the JSON input for the apply_patch tool.

type ApplyPatchMetadata 

type ApplyPatchMetadata struct {
	Changes  []ApplyPatchChange `json:"changes"`
	Added    []string           `json:"added,omitempty"`
	Modified []string           `json:"modified,omitempty"`
	Deleted  []string           `json:"deleted,omitempty"`
}

ApplyPatchMetadata contains metadata about an apply_patch operation.

func (ApplyPatchMetadata) ToolType 

func (m ApplyPatchMetadata) ToolType() string

ToolType returns the tool type identifier for apply_patch operations.

type BaseToolResult 

type BaseToolResult struct {
	Result string `json:"result"`
	Error  string `json:"error"`
}

BaseToolResult provides a basic implementation of the ToolResult interface

func (BaseToolResult) AssistantFacing 

func (t BaseToolResult) AssistantFacing() string

AssistantFacing returns a formatted string representation of the result for the LLM

func (BaseToolResult) GetError 

func (t BaseToolResult) GetError() string

GetError returns the error message if any

func (BaseToolResult) GetResult 

func (t BaseToolResult) GetResult() string

GetResult returns the result string

func (BaseToolResult) IsError 

func (t BaseToolResult) IsError() bool

IsError returns true if the tool execution resulted in an error

func (BaseToolResult) StructuredData 

func (t BaseToolResult) StructuredData() StructuredToolResult

StructuredData returns a structured representation of the tool result

type BashInput 

type BashInput struct {
	Description string `json:"description" jsonschema:"description=A description of the command to run"`
	Command     string `json:"command" jsonschema:"description=The bash command to run"`
	Timeout     int    `json:"timeout" jsonschema:"description=Timeout in seconds (10-120)"`
}

BashInput defines the input parameters for the bash tool.

type BashMetadata 

type BashMetadata struct {
	Command       string        `json:"command"`
	ExitCode      int           `json:"exitCode"`
	Output        string        `json:"output"`
	ExecutionTime time.Duration `json:"executionTime"`
	WorkingDir    string        `json:"workingDir,omitempty"`
}

BashMetadata contains metadata about a bash command execution

func (BashMetadata) ToolType 

func (m BashMetadata) ToolType() string

ToolType returns the tool type identifier for bash command execution

type BlockedMetadata 

type BlockedMetadata struct {
	ToolName string `json:"tool_name"`
	Reason   string `json:"reason"`
}

BlockedMetadata contains metadata about a blocked tool invocation

func (BlockedMetadata) ToolType 

func (m BlockedMetadata) ToolType() string

ToolType returns the tool type identifier for blocked tools

type BlockedToolResult 

type BlockedToolResult struct {
	ToolName string `json:"tool_name"`
	Reason   string `json:"reason"`
}

BlockedToolResult represents a tool that was blocked by a lifecycle hook

func NewBlockedToolResult 

func NewBlockedToolResult(toolName, reason string) BlockedToolResult

NewBlockedToolResult creates a new BlockedToolResult with the given tool name and reason

func (BlockedToolResult) AssistantFacing 

func (t BlockedToolResult) AssistantFacing() string

AssistantFacing returns a formatted string representation of the blocked result for the LLM

func (BlockedToolResult) GetError 

func (t BlockedToolResult) GetError() string

GetError returns the blocked reason as an error message

func (BlockedToolResult) GetResult 

func (t BlockedToolResult) GetResult() string

GetResult returns an empty string as blocked tools have no result

func (BlockedToolResult) IsError 

func (t BlockedToolResult) IsError() bool

IsError returns true as blocked tools are treated as errors

func (BlockedToolResult) StructuredData 

func (t BlockedToolResult) StructuredData() StructuredToolResult

StructuredData returns a structured representation of the blocked tool result

type CodeExecutionMetadata 

type CodeExecutionMetadata struct {
	Code    string `json:"code"`
	Output  string `json:"output"`
	Runtime string `json:"runtime"`
}

CodeExecutionMetadata contains metadata about a code execution operation

func (CodeExecutionMetadata) ToolType 

func (m CodeExecutionMetadata) ToolType() string

ToolType returns the tool type identifier for code execution operations

type CodeSearchInput 

type CodeSearchInput struct {
	Pattern       string `` /* 127-byte string literal not displayed */
	Path          string `` /* 193-byte string literal not displayed */
	Include       string `` /* 154-byte string literal not displayed */
	IgnoreCase    bool   `` /* 156-byte string literal not displayed */
	FixedStrings  bool   `json:"fixed_strings" jsonschema:"description=If true treat pattern as literal string instead of regex. Default is false"`
	SurroundLines int    `` /* 131-byte string literal not displayed */
	MaxResults    int    `` /* 149-byte string literal not displayed */
}

CodeSearchInput defines the input parameters for the grep_tool.

type CustomToolMetadata 

type CustomToolMetadata struct {
	ExecutionTime time.Duration `json:"executionTime"`
	Output        string        `json:"output"`
}

CustomToolMetadata contains metadata about a custom tool execution

func (CustomToolMetadata) ToolType 

func (m CustomToolMetadata) ToolType() string

ToolType returns the tool type identifier for custom tool execution

type Edit 

type Edit struct {
	StartLine  int    `json:"startLine"`
	EndLine    int    `json:"endLine"`
	OldContent string `json:"oldContent"`
	NewContent string `json:"newContent"`
}

Edit represents a single text replacement in a file

type FileEditInput 

type FileEditInput struct {
	FilePath   string `json:"file_path" jsonschema:"description=The absolute path of the file to edit"`
	OldText    string `json:"old_text" jsonschema:"description=The text to be replaced"`
	NewText    string `json:"new_text" jsonschema:"description=The text to replace the old text with"`
	ReplaceAll bool   `` /* 133-byte string literal not displayed */
}

FileEditInput defines the input parameters for the file_edit tool.

type FileEditMetadata 

type FileEditMetadata struct {
	FilePath      string `json:"filePath"`
	Edits         []Edit `json:"edits"`
	Language      string `json:"language,omitempty"`
	ReplaceAll    bool   `json:"replaceAll,omitempty"`
	ReplacedCount int    `json:"replacedCount,omitempty"`
}

FileEditMetadata contains metadata about a file edit operation

func (FileEditMetadata) ToolType 

func (m FileEditMetadata) ToolType() string

ToolType returns the tool type identifier for file edit operations

type FileInfo 

type FileInfo struct {
	Path     string    `json:"path"`
	Size     int64     `json:"size"`
	ModTime  time.Time `json:"modTime"`
	Type     string    `json:"type"` // "file" or "directory"
	Language string    `json:"language,omitempty"`
}

FileInfo represents information about a matched file

type FileReadInput 

type FileReadInput struct {
	FilePath  string `json:"file_path" jsonschema:"description=The absolute path of the file to read"`
	Offset    int    `json:"offset" jsonschema:"description=The 1-indexed line number to start reading from. Default: 1"`
	LineLimit int    `json:"line_limit" jsonschema:"description=The maximum number of lines to read from the offset. Default: 2000. Max: 2000"`
}

FileReadInput defines the input parameters for the file_read tool.

type FileReadMetadata 

type FileReadMetadata struct {
	FilePath       string   `json:"filePath"`
	Offset         int      `json:"offset"`
	LineLimit      int      `json:"lineLimit"`
	Lines          []string `json:"lines"`
	Language       string   `json:"language,omitempty"`
	Truncated      bool     `json:"truncated"`
	RemainingLines int      `json:"remainingLines,omitempty"`
}

FileReadMetadata contains metadata about a file read operation

func (FileReadMetadata) ToolType 

func (m FileReadMetadata) ToolType() string

ToolType returns the tool type identifier for file read operations

type FileWriteInput 

type FileWriteInput struct {
	FilePath string `json:"file_path" jsonschema:"description=The absolute path of the file to write,required"`
	Text     string `json:"text" jsonschema:"description=The text of the file MUST BE provided"`
}

FileWriteInput defines the input parameters for the file_write tool.

type FileWriteMetadata 

type FileWriteMetadata struct {
	FilePath string `json:"filePath"`
	Content  string `json:"content"`
	Size     int64  `json:"size"`
	Language string `json:"language,omitempty"`
}

FileWriteMetadata contains metadata about a file write operation

func (FileWriteMetadata) ToolType 

func (m FileWriteMetadata) ToolType() string

ToolType returns the tool type identifier for file write operations

type GlobInput 

type GlobInput struct {
	Pattern         string `json:"pattern" jsonschema:"description=The glob pattern"`
	Path            string `` /* 156-byte string literal not displayed */
	IgnoreGitignore bool   `` /* 149-byte string literal not displayed */
}

GlobInput defines the input parameters for the glob_tool.

type GlobMetadata 

type GlobMetadata struct {
	Pattern   string     `json:"pattern"`
	Path      string     `json:"path,omitempty"`
	Files     []FileInfo `json:"files"`
	Truncated bool       `json:"truncated"`
}

GlobMetadata contains metadata about a glob pattern match operation

func (GlobMetadata) ToolType 

func (m GlobMetadata) ToolType() string

ToolType returns the tool type identifier for glob operations

type GrepMetadata 

type GrepMetadata struct {
	Pattern          string         `json:"pattern"`
	Path             string         `json:"path,omitempty"`
	Include          string         `json:"include,omitempty"`
	Results          []SearchResult `json:"results"`
	Truncated        bool           `json:"truncated"`
	TruncationReason string         `json:"truncationReason,omitempty"`
	MaxResults       int            `json:"maxResults,omitempty"`
}

GrepMetadata contains metadata about a grep search operation

func (GrepMetadata) ToolType 

func (m GrepMetadata) ToolType() string

ToolType returns the tool type identifier for grep operations

type ImageDimensions 

type ImageDimensions struct {
	Width  int `json:"width"`
	Height int `json:"height"`
}

ImageDimensions represents the dimensions of an image

type ImageRecognitionMetadata 

type ImageRecognitionMetadata struct {
	ImagePath string          `json:"imagePath"`
	ImageType string          `json:"imageType"` // "local" or "remote"
	Prompt    string          `json:"prompt"`
	Analysis  string          `json:"analysis"`
	ImageSize ImageDimensions `json:"imageSize,omitempty"`
}

ImageRecognitionMetadata contains metadata about an image recognition operation

func (ImageRecognitionMetadata) ToolType 

func (m ImageRecognitionMetadata) ToolType() string

ToolType returns the tool type identifier for image recognition operations

type MCPContent 

type MCPContent struct {
	Type     string         `json:"type"`
	Text     string         `json:"text,omitempty"`
	Data     string         `json:"data,omitempty"`
	MimeType string         `json:"mimeType,omitempty"`
	URI      string         `json:"uri,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

MCPContent represents a content block returned by an MCP tool

type MCPToolMetadata 

type MCPToolMetadata struct {
	MCPToolName   string         `json:"mcpToolName"`
	ServerName    string         `json:"serverName,omitempty"`
	Parameters    map[string]any `json:"parameters,omitempty"`
	Content       []MCPContent   `json:"content"`
	ContentText   string         `json:"contentText"`
	ExecutionTime time.Duration  `json:"executionTime"`
}

MCPToolMetadata contains metadata about an MCP tool execution

func (MCPToolMetadata) ToolType 

func (m MCPToolMetadata) ToolType() string

ToolType returns the tool type identifier for MCP tool execution

type OpenAIWebSearchMetadata 

type OpenAIWebSearchMetadata struct {
	CallID  string   `json:"callId"`
	Status  string   `json:"status"`
	Action  string   `json:"action"`
	Queries []string `json:"queries,omitempty"`
	Sources []string `json:"sources,omitempty"`
	Results []string `json:"results,omitempty"`
	URL     string   `json:"url,omitempty"`
	Pattern string   `json:"pattern,omitempty"`
}

OpenAIWebSearchMetadata contains metadata about a native OpenAI web search operation.

func (OpenAIWebSearchMetadata) ToolType 

func (m OpenAIWebSearchMetadata) ToolType() string

ToolType returns the tool type identifier for native OpenAI web search operations.

type ReadConversationInput 

type ReadConversationInput struct {
	ConversationID string `json:"conversation_id" jsonschema:"description=The ID of the saved conversation to read"`
	Goal           string `json:"goal" jsonschema:"description=What information to extract from the conversation"`
}

ReadConversationInput defines the input parameters for the read_conversation tool.

type ReadConversationMetadata 

type ReadConversationMetadata struct {
	ConversationID string `json:"conversationID"`
	Goal           string `json:"goal"`
	Content        string `json:"content"`
}

ReadConversationMetadata contains metadata about a read_conversation operation.

func (ReadConversationMetadata) ToolType 

func (m ReadConversationMetadata) ToolType() string

ToolType returns the tool type identifier for read_conversation operations.

type SearchMatch 

type SearchMatch struct {
	LineNumber int    `json:"lineNumber"`
	Content    string `json:"content"`
	MatchStart int    `json:"matchStart"`
	MatchEnd   int    `json:"matchEnd"`
	IsContext  bool   `json:"isContext,omitempty"`
}

SearchMatch represents a single match in a search result

type SearchResult 

type SearchResult struct {
	FilePath string        `json:"filePath"`
	Language string        `json:"language,omitempty"`
	Matches  []SearchMatch `json:"matches"`
}

SearchResult represents the search results for a single file

type SkillMetadata 

type SkillMetadata struct {
	SkillName string `json:"skillName"`
	Directory string `json:"directory"`
}

SkillMetadata contains metadata about a skill invocation

func (SkillMetadata) ToolType 

func (m SkillMetadata) ToolType() string

ToolType returns the tool type identifier for skill operations

type State 

type State interface {
	SetFileLastAccessed(path string, lastAccessed time.Time) error
	GetFileLastAccessed(path string) (time.Time, error)
	ClearFileLastAccessed(path string) error
	TodoFilePath() (string, error)
	SetTodoFilePath(path string)
	SetFileLastAccess(fileLastAccess map[string]time.Time)
	FileLastAccess() map[string]time.Time
	BasicTools() []Tool
	MCPTools() []Tool
	Tools() []Tool

	// Context discovery
	DiscoverContexts() map[string]string

	// LLM configuration access
	GetLLMConfig() any // Returns llmtypes.Config but using any to avoid circular import
	WorkingDirectory() string

	// File locking for atomic operations
	// LockFile acquires an exclusive lock for the given file path to prevent race conditions
	// during read-modify-write operations. Must be paired with UnlockFile.
	LockFile(path string)
	// UnlockFile releases the lock for the given file path
	UnlockFile(path string)
}

State defines the interface for managing tool execution state and context

type StructuredToolResult 

type StructuredToolResult struct {
	ToolName  string       `json:"toolName"`
	Success   bool         `json:"success"`
	Error     string       `json:"error,omitempty"`
	Metadata  ToolMetadata `json:"metadata,omitempty"`
	Timestamp time.Time    `json:"timestamp"`
}

StructuredToolResult represents a tool's execution result with structured metadata

func (StructuredToolResult) MarshalJSON 

func (s StructuredToolResult) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshaling for StructuredToolResult

func (*StructuredToolResult) UnmarshalJSON 

func (s *StructuredToolResult) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom JSON unmarshaling for StructuredToolResult

type SubAgentMetadata 

type SubAgentMetadata struct {
	Question string `json:"question"`
	Response string `json:"response"`
	Workflow string `json:"workflow,omitempty"`
	Cwd      string `json:"cwd,omitempty"`
}

SubAgentMetadata contains metadata about a sub-agent invocation

func (SubAgentMetadata) ToolType 

func (m SubAgentMetadata) ToolType() string

ToolType returns the tool type identifier for sub-agent operations

type TodoItem 

type TodoItem struct {
	ID        string    `json:"id"`
	Content   string    `json:"content"`
	Status    string    `json:"status"`
	Priority  string    `json:"priority"`
	CreatedAt time.Time `json:"createdAt,omitempty"`
	UpdatedAt time.Time `json:"updatedAt,omitempty"`
}

TodoItem represents a single todo list item

type TodoMetadata 

type TodoMetadata struct {
	Action     string     `json:"action"` // "read" or "write"
	TodoList   []TodoItem `json:"todoList"`
	Statistics TodoStats  `json:"statistics,omitempty"`
}

TodoMetadata contains metadata about a todo list operation

func (TodoMetadata) ToolType 

func (m TodoMetadata) ToolType() string

ToolType returns the tool type identifier for todo operations

type TodoStats 

type TodoStats struct {
	Total      int `json:"total"`
	Completed  int `json:"completed"`
	InProgress int `json:"inProgress"`
	Pending    int `json:"pending"`
}

TodoStats contains statistics about the todo list

type Tool 

type Tool interface {
	GenerateSchema() *jsonschema.Schema
	Name() string
	Description() string
	ValidateInput(state State, parameters string) error
	Execute(ctx context.Context, state State, parameters string) ToolResult
	TracingKVs(parameters string) ([]attribute.KeyValue, error)
}

Tool defines the interface for all kodelet tools

type ToolMetadata 

type ToolMetadata interface {
	ToolType() string
}

ToolMetadata is a marker interface for tool-specific metadata structures

type ToolResult 

type ToolResult interface {
	AssistantFacing() string
	IsError() bool
	GetError() string  // xxx: to be removed
	GetResult() string // xxx: to be removed
	StructuredData() StructuredToolResult
}

ToolResult represents the outcome of a tool execution

type WebFetchMetadata 

type WebFetchMetadata struct {
	URL           string `json:"url"`
	ContentType   string `json:"contentType"`
	Size          int64  `json:"size"`
	SavedPath     string `json:"savedPath,omitempty"`
	Prompt        string `json:"prompt,omitempty"`
	ProcessedType string `json:"processedType"` // "saved", "markdown", "ai_extracted"
	Content       string `json:"content"`       // The actual fetched content
}

WebFetchMetadata contains metadata about a web fetch operation

func (WebFetchMetadata) ToolType 

func (m WebFetchMetadata) ToolType() string

ToolType returns the tool type identifier for web fetch operations

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.