tool

type Previewer ¶

type Previewer interface {
	Preview(args json.RawMessage) (diff.Change, error)
}

Previewer is an optional capability a writer Tool may implement: given the same raw JSON args Execute would receive, compute the file change the call *would* make — without touching disk. A front-end uses it to show an approval card or a changed-files panel before the call runs (the permission gate, not Preview, decides whether it may proceed). Type-assert a Tool to Previewer to discover support; the file-writing built-ins implement it, most tools do not.

type Registry ¶

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

Registry is a per-run set of tools: enabled built-ins plus plugin tools. Safe for concurrent use: reads (Get, Names, Schemas, Len) take RLock; writes (Add, RemovePrefix) take Lock. Supports hierarchical tool groups: when groups are empty (default), all tools are visible. When groups are set via ActivateGroups, only tools in those groups are returned by Schemas/Names/Get — cutting schema token costs.

Group switches are deferred: ActivateGroups sets pendingGroups, which is applied at the start of the next turn via ApplyPendingGroups. This keeps tool schemas byte-stable within a turn so DeepSeek's prefix cache stays warm.

func NewRegistry() *Registry

func (r *Registry) ActivateGroups(groups ...string)

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

func (r *Registry) Add(t Tool)

func (r *Registry) AddToGroup(t Tool, group string)

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

func (r *Registry) ApplyPendingGroups()

func (r *Registry) DeactivateGroups(groups ...string)

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

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

func (r *Registry) Len() int

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

func (r *Registry) RemovePrefix(prefix string) int

func (r *Registry) Schemas() []provider.ToolSchema

func (r *Registry) SetGroup(name, group string)

type RegistrySetGroups ¶

type RegistrySetGroups interface {
	ToolRegistry
	ActivateGroups(groups ...string)
	ApplyPendingGroups()
	AllNames() []string
	ActiveGroupNames() []string
}

RegistrySetGroups is the interface for switching tool groups at runtime. Separated from ToolRegistry so only the boot wiring exposes it.

type Tool ¶

type Tool interface {
	Name() string
	Description() string
	// Schema returns the JSON Schema for the tool's parameters.
	Schema() json.RawMessage
	// Execute parses the model-generated raw JSON args and returns result text
	// to feed back to the model.
	Execute(ctx context.Context, args json.RawMessage) (string, error)
	// ReadOnly reports whether the tool has no observable side effects on the
	// host. The agent parallelises a batch of tool calls only when every call
	// in the batch is ReadOnly; mixed batches stay sequential so write/read
	// ordering is preserved. bash and plugin tools must return false because
	// their effects can't be inferred statically from args.
	ReadOnly() bool
}

Tool is a capability the model can invoke.

func Builtins() []Tool

func LookupBuiltin(name string) (Tool, bool)

type ToolGrouper ¶

type ToolGrouper interface {
	Group() string
}

ToolGrouper is an optional interface a Tool may implement to declare its group membership for hierarchical tool registration. Groups let the agent expose only a subset of tools to the model based on task complexity, saving ~50% schema tokens per turn.

Built-in groups (case-insensitive):

core      — always visible (read/write files, search, task, etc.)
advanced  — git, database, debug, deploy, desktop, etc.
knowledge — rag, semantic-search, code analysis
admin     — repo, make-tool, go-profile, etc.

Tools that don't implement ToolGrouper default to "core".

type ToolRegistry ¶

type ToolRegistry interface {
	Get(name string) (Tool, bool)
	GetAny(name string) (Tool, bool) // lookup regardless of group visibility
	Names() []string
	Schemas() []provider.ToolSchema
	Len() int
}

ToolRegistry is the interface the agent (and anyone who needs to look up or enumerate tools) depends on. A *Registry implements it; tests can satisfy it with a fake rather than importing the concrete implementation.