tool

Documentation

Overview

Package tool manages the tool registry: loading skill definitions from *.skill.yaml files, validating tool names, and dispatching executions.

Index

• func Execute(ctx context.Context, def model.ToolDefinition, args map[string]any) model.ToolResult
• func MetricSnapshot() (retryTotal, backoffTotal, rateLimitWaitTotal int64)
• type Executor
  • func (e *Executor) Execute(ctx context.Context, def model.ToolDefinition, args map[string]any) model.ToolResult
• type HostLimiter
  • func NewHostLimiter(specs map[string]string) (*HostLimiter, error)
  • func (l *HostLimiter) Wait(ctx context.Context, host string) (waited bool, err error)
• type Registry
  • func Load(dir string) (*Registry, error)
  • func NewRegistry() *Registry
  • func (r *Registry) ApplyExtractors(toolName, content string, vars map[string]string)
  • func (r *Registry) GetSkills(skillNames []string) []model.Skill
  • func (r *Registry) GetTool(name string) (model.ToolDefinition, bool)
  • func (r *Registry) GetTools(skillNames []string) []model.ToolDefinition
  • func (r *Registry) GetToolset(name string) (model.Toolset, bool)
  • func (r *Registry) GetToolsetTools(toolsetNames []string) []model.ToolDefinition
  • func (r *Registry) Register(s model.Skill) error
  • func (r *Registry) RegisterToolset(s model.Toolset) error
  • func (r *Registry) ResolveTools(skillNames, toolsetNames, toolNames []string) []model.ToolDefinition

Functions

func Execute

func Execute(ctx context.Context, def model.ToolDefinition, args map[string]any) model.ToolResult

Execute dispatches a ToolCall without MCP support. Kept for backward compatibility; use Executor.Execute when MCP tools are needed.

func MetricSnapshot

func MetricSnapshot() (retryTotal, backoffTotal, rateLimitWaitTotal int64)

MetricSnapshot returns a point-in-time copy of the outbound tool counters.

Types

type Executor

type Executor struct {
	// MCP is the registry of running MCP server clients.
	// Nil means mcp-type tools are unavailable.
	MCP *mcp.Registry
	// QueueMgr, when non-nil, enables the outbound DLQ: permanent failures and
	// exhausted-retry failures are enqueued to the "outbound-dlq" queue.
	QueueMgr *queue.Manager
	// AgentName is propagated into outbound-DLQ items for traceability.
	AgentName string
	// Limiter, when non-nil, applies per-host token-bucket throttling before
	// every outbound HTTP or MCP-backed call (including retries).
	Limiter *HostLimiter
}

Executor dispatches tool calls to the appropriate backend. The zero value (all fields nil) handles http-type tools only.

func (*Executor) Execute

func (e *Executor) Execute(ctx context.Context, def model.ToolDefinition, args map[string]any) model.ToolResult

Execute dispatches a ToolCall to the appropriate executor based on def.Type. Authentication header values are never logged.

type HostLimiter

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

HostLimiter applies per-host token-bucket rate limiting. Each host bucket allows up to burst tokens immediately; thereafter one token is added every interval. The zero value (nil pointer) is safe to call — Wait returns immediately when the limiter is nil.

func NewHostLimiter

func NewHostLimiter(specs map[string]string) (*HostLimiter, error)

NewHostLimiter builds a HostLimiter from a host→rateSpec map. Each rateSpec is "N/s", "N/m", or "N/h" where N is the token count per period. An empty map returns a limiter that never blocks.

func (*HostLimiter) Wait

func (l *HostLimiter) Wait(ctx context.Context, host string) (waited bool, err error)

Wait blocks until the token bucket for host allows one more request, or until ctx is cancelled. It returns (true, nil) when it had to wait, (false, nil) when the token was available immediately, and (false, err) on context cancel. Hosts with no configured limit pass through immediately.

type Registry

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

Registry holds all loaded skills and their tools, indexed for fast lookup.

func Load

func Load(dir string) (*Registry, error)

Load reads all *.skill.yaml files from dir and registers their skills and tools. Returns an error if dir cannot be read or any file fails to parse. A non-existent dir is silently ignored.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty Registry.

func (*Registry) ApplyExtractors

func (r *Registry) ApplyExtractors(toolName, content string, vars map[string]string)

ApplyExtractors scans content against all extraction rules registered for toolName. For each rule whose pattern matches, capture group 1 is written into vars under the rule's store key. Rules are applied in registration order; later matches overwrite earlier ones for the same store key. Noop when r is nil.

func (*Registry) GetSkills

func (r *Registry) GetSkills(skillNames []string) []model.Skill

GetSkills returns the Skill definitions for the named skills, in order. Unknown names are silently skipped.

func (*Registry) GetTool

func (r *Registry) GetTool(name string) (model.ToolDefinition, bool)

GetTool returns the ToolDefinition for name, and false if not found.

func (*Registry) GetTools

func (r *Registry) GetTools(skillNames []string) []model.ToolDefinition

GetTools returns the combined tool list for the named skills, in skill order. Unknown skill names are silently skipped. Duplicate tools (same name across skills) are deduplicated; the first occurrence wins.

func (*Registry) GetToolset

func (r *Registry) GetToolset(name string) (model.Toolset, bool)

GetToolset returns the Toolset for name, and false if not found.

func (*Registry) GetToolsetTools

func (r *Registry) GetToolsetTools(toolsetNames []string) []model.ToolDefinition

GetToolsetTools returns the combined tool list for the named toolsets, in toolset order. Unknown toolset names are silently skipped. Duplicate tools are deduplicated; first wins.

func (*Registry) Register

func (r *Registry) Register(s model.Skill) error

Register adds a skill and indexes its tools. Returns an error on duplicate tool names or on invalid extract pattern regexps. This is the low-level entry point used by Load and directly by tests.

func (*Registry) RegisterToolset

func (r *Registry) RegisterToolset(s model.Toolset) error

RegisterToolset adds a named toolset. Every referenced tool must already be registered.

func (*Registry) ResolveTools

func (r *Registry) ResolveTools(skillNames, toolsetNames, toolNames []string) []model.ToolDefinition

ResolveTools returns the deduplicated union of tools declared via skills, toolsets, and explicit tool names, in that order.