tool

Documentation

Overview

Package tool defines SuperCode's model-callable tool boundary and registry.

Index

• Variables
• func CanRunInParallel(item Tool, arguments string) bool
• func ReportProgress(ctx context.Context, progress Progress)
• func SandboxStatus(root string) string
• func SandboxStatusWithOptions(root string, options SandboxOptions) string
• func WithProgressReporter(ctx context.Context, reporter func(Progress)) context.Context
• type Categorized
• type Category
  • func CategoryOf(item Tool) Category
• type Parallelizable
• type PermissionRequester
• type Progress
• type Registry
  • func NewRegistry(tools ...Tool) (*Registry, error)
  • func (r *Registry) Add(tools ...Tool) error
  • func (r *Registry) Definitions() []provider.ToolDefinition
  • func (r *Registry) Len() int
  • func (r *Registry) Lookup(name string) (Tool, bool)
  • func (r *Registry) Names() []string
• type Result
• type Risk
• type SandboxOptions
• type Tool
  • func Builtins(root string) ([]Tool, error)
  • func BuiltinsWithLifecycle(root string, options SandboxOptions) ([]Tool, io.Closer, error)
  • func BuiltinsWithOptions(root string, options SandboxOptions) ([]Tool, error)
  • func SearchTool(items []Tool) Tool

Variables

var ErrOutsideWorkspace = errors.New("path is outside the workspace")

Functions

func CanRunInParallel

func CanRunInParallel(item Tool, arguments string) bool

func ReportProgress

func ReportProgress(ctx context.Context, progress Progress)

ReportProgress emits a bounded incremental observation from any tool. It is a no-op when the caller is not running under an Agent progress context.

func SandboxStatus

func SandboxStatus(root string) string

SandboxStatus describes the command boundary selected for a workspace.

func SandboxStatusWithOptions

func SandboxStatusWithOptions(root string, options SandboxOptions) string

func WithProgressReporter

func WithProgressReporter(ctx context.Context, reporter func(Progress)) context.Context

WithProgressReporter installs the agent-owned progress sink for one tool invocation. The context scope prevents background processes from retaining a stale UI callback after that invocation returns.

Types

type Categorized

type Categorized interface{ Category() Category }

type Category

type Category string

const (
	CategoryTool       Category = "tool"
	CategoryFile       Category = "file"
	CategoryShell      Category = "shell"
	CategoryNetwork    Category = "network"
	CategoryMCP        Category = "mcp"
	CategorySkill      Category = "skill"
	CategoryPermission Category = "permission"
)

func CategoryOf

func CategoryOf(item Tool) Category

type Parallelizable

type Parallelizable interface {
	ParallelSafe(arguments string) bool
}

Parallelizable is an explicit opt-in for tools whose read operations are safe to overlap with other calls from the same model response. RiskRead by itself is not sufficient: process polling and stdin transport also use that risk while mutating shared runtime state.

type PermissionRequester

type PermissionRequester interface {
	PermissionRequest(arguments string) (permission.Request, error)
}

PermissionRequester lets the agent distinguish an access grant from a normal tool approval and apply the selected turn/session lifetime.

type Progress

type Progress struct {
	Delta     string
	SessionID int64
}

Progress is an incremental observation produced while a tool is still running. Delta is append-only text; callers should render it as untrusted terminal output.

type Registry

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

Registry keeps tool discovery independent from execution orchestration.

func NewRegistry

func NewRegistry(tools ...Tool) (*Registry, error)

func (*Registry) Add

func (r *Registry) Add(tools ...Tool) error

Add installs dynamically discovered tools before a runner starts.

func (*Registry) Definitions

func (r *Registry) Definitions() []provider.ToolDefinition

func (*Registry) Len

func (r *Registry) Len() int

func (*Registry) Lookup

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

func (*Registry) Names

func (r *Registry) Names() []string

type Result

type Result struct {
	Content string
	IsError bool
	Images  []provider.Image
}

Result is the bounded observation returned to the model.

type Risk

type Risk string

Risk controls whether a tool call can run without user approval.

const (
	RiskRead       Risk = "read"
	RiskWrite      Risk = "write"
	RiskExecute    Risk = "execute"
	RiskNetwork    Risk = "network"
	RiskPermission Risk = "permission"
)

type SandboxOptions

type SandboxOptions struct {
	ReadRoots   []string
	WriteRoots  []string
	DenyRoots   []string
	Permissions *permission.Manager
}

type Tool

type Tool interface {
	Definition() provider.ToolDefinition
	Risk(arguments string) Risk
	Summary(arguments string) string
	Execute(ctx context.Context, arguments string) (Result, error)
}

Tool is implemented by every built-in or future plugin tool.

func Builtins

func Builtins(root string) ([]Tool, error)

Builtins returns the standard workspace-scoped coding tool set.

func BuiltinsWithLifecycle

func BuiltinsWithLifecycle(root string, options SandboxOptions) ([]Tool, io.Closer, error)

BuiltinsWithLifecycle returns the standard tools together with the owner of background process resources. Long-lived hosts must close the lifecycle when shutting down; Builtins and BuiltinsWithOptions remain for compatibility.

func BuiltinsWithOptions

func BuiltinsWithOptions(root string, options SandboxOptions) ([]Tool, error)

func SearchTool

func SearchTool(items []Tool) Tool

SearchTool exposes a compact catalog for models and users when many dynamic MCP tools are installed. Execution still goes through the original registry.