tool

Documentation

Index

• Constants
• Variables
• func BuiltinNames() []string
• func DefinitionToolName(name string) string
• func IsBuiltinName(name string) bool
• func NormalizeToolName(name string) string
• func RegisterBuiltin(name string, factory BuiltinFactory)
• func ValidateInput(schema map[string]interface{}, input json.RawMessage) error
• type BuiltinFactory
• type BuiltinOptions
• type CustomTool
• type ExecCommandInput
• type FilePathInput
• type MetadataProvider
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Get(name string) (Tool, bool)
  • func (r *Registry) GetDescriptors() []ToolDescriptor
  • func (r *Registry) Register(t Tool)
• type RiskLevel
• type Runner
  • func NewRunner(registry *Registry, policy *policy.Engine) *Runner
  • func (r *Runner) Execute(ctx context.Context, toolName string, input json.RawMessage, approvalID string) (json.RawMessage, error)
  • func (r *Runner) GetDescriptors() []ToolDescriptor
• type SandboxLevel
• type Tool
  • func InstantiateBuiltins(options BuiltinOptions) ([]Tool, error)
• type ToolDescriptor
• type ToolExecutor
• type ToolLoader
• type ToolMetadata
• type ToolType

Constants

const (
	DefaultBuiltinWebTimeout          = 10 * time.Second
	DefaultBuiltinWebMaxContentLength = 5000
)

Variables

var (
	ErrToolNotFound = errors.New("tool not found")
	ErrToolFailed   = errors.New("tool execution failed")
)

Functions

func BuiltinNames

func BuiltinNames() []string

BuiltinNames returns all registered built-in names in deterministic order.

func DefinitionToolName

func DefinitionToolName(name string) string

func IsBuiltinName

func IsBuiltinName(name string) bool

IsBuiltinName reports whether a tool name maps to a registered built-in tool.

func NormalizeToolName

func NormalizeToolName(name string) string

func RegisterBuiltin

func RegisterBuiltin(name string, factory BuiltinFactory)

RegisterBuiltin registers a built-in tool factory under a tool name. Intended to be called in init() from built-in tool files.

func ValidateInput

func ValidateInput(schema map[string]interface{}, input json.RawMessage) error

ValidateInput checks if the JSON input matches the tool's parameter schema. This is a lightweight implementation of JSON Schema validation.

Types

type BuiltinFactory

type BuiltinFactory func(options BuiltinOptions) (Tool, error)

type BuiltinOptions

type BuiltinOptions struct {
	WebTimeout          time.Duration
	WebBaseURL          string
	WebMaxContentLength int
	WeatherBaseURL      string
	WeatherTimeout      time.Duration
	FinanceBaseURL      string
	FinanceTimeout      time.Duration
	SportsBaseURL       string
	SportsTimeout       time.Duration
	ImageQueryBaseURL   string
	ImageQueryTimeout   time.Duration
	ScreenshotTimeout   time.Duration
	ScreenshotRenderer  string
	ApplyPatchCommand   string
}

BuiltinOptions carries runtime dependencies needed by built-in tool factories.

type CustomTool

type CustomTool struct {
	Name         string
	Language     ToolType
	ScriptPath   string
	Description  string
	Parameters   json.RawMessage
	Capabilities []string
	Source       string
	Risk         RiskLevel
	SandboxLevel SandboxLevel
}

type ExecCommandInput

type ExecCommandInput struct {
	Cmd             string   `json:"cmd"`
	Command         string   `json:"command"`
	Args            []string `json:"args"`
	TTY             bool     `json:"tty"`
	YieldTimeMS     int      `json:"yield_time_ms"`
	MaxOutputTokens int      `json:"max_output_tokens"`
	Workdir         string   `json:"workdir"`
	Shell           string   `json:"shell"`
	Login           *bool    `json:"login"`
	Justification   string   `json:"justification"`
	PrefixRule      []string `json:"prefix_rule"`
	SandboxPerms    string   `json:"sandbox_permissions"`
}

type FilePathInput

type FilePathInput struct {
	Path string `json:"path"`
}

type MetadataProvider

type MetadataProvider interface {
	ToolMetadata() ToolMetadata
}

type Registry

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

Registry holds all available tools.

func NewRegistry

func NewRegistry() *Registry

func (*Registry) Get

func (r *Registry) Get(name string) (Tool, bool)

func (*Registry) GetDescriptors

func (r *Registry) GetDescriptors() []ToolDescriptor

func (*Registry) Register

func (r *Registry) Register(t Tool)

type RiskLevel

type RiskLevel string

const (
	RiskLow    RiskLevel = "low"
	RiskMedium RiskLevel = "medium"
	RiskHigh   RiskLevel = "high"
)

type Runner

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

func NewRunner

func NewRunner(registry *Registry, policy *policy.Engine) *Runner

func (*Runner) Execute

func (r *Runner) Execute(ctx context.Context, toolName string, input json.RawMessage, approvalID string) (json.RawMessage, error)

Execute handles the full lifecycle: Check Policy -> Run Tool -> Return Result It accepts an optional approvalID for retrying previously denied requests.

func (*Runner) GetDescriptors

func (r *Runner) GetDescriptors() []ToolDescriptor

type SandboxLevel

type SandboxLevel string

const (
	SandboxBasic     SandboxLevel = "basic"
	SandboxMedium    SandboxLevel = "medium"
	SandboxAdvanced  SandboxLevel = "advanced"
	SandboxContainer SandboxLevel = "container"
)

type Tool

type Tool interface {
	Name() string
	Description() string
	Parameters() map[string]interface{}
	Execute(ctx context.Context, input json.RawMessage) (json.RawMessage, error)
}

Tool represents an executable capability.

func InstantiateBuiltins

func InstantiateBuiltins(options BuiltinOptions) ([]Tool, error)

InstantiateBuiltins constructs all built-in tools using their registered factories.

type ToolDescriptor

type ToolDescriptor struct {
	Definition contract.ToolDef
	Metadata   ToolMetadata
}

type ToolExecutor

type ToolExecutor interface {
	Execute(ctx context.Context, tool CustomTool, input json.RawMessage) (json.RawMessage, error)
	Validate(tool CustomTool) error
	GetRuntimeType() ToolType
}

type ToolLoader

type ToolLoader interface {
	LoadFromSkill(skillPath string) ([]*CustomTool, error)
	LoadFromSource(skillsPath string) ([]*CustomTool, error)
}

type ToolMetadata

type ToolMetadata struct {
	Source       string
	Capabilities []string
	Risk         RiskLevel
}

type ToolType

type ToolType string

const (
	ToolTypePython ToolType = "python"
	ToolTypeGo     ToolType = "go"
	ToolTypeJS     ToolType = "javascript"
	ToolTypeShell  ToolType = "shell"
	ToolTypeRuby   ToolType = "ruby"
	ToolTypeRust   ToolType = "rust"
)