tools

package
v0.8.3 Latest Latest
Warning

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

 Go to latest Published: Jul 5, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package tools defines the Tool interface and a registry for builtins. MCP-backed tools will live alongside builtins in the same registry once M5 lands; the contract is identical.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type A2ACallTool added in v0.2.0 

type A2ACallTool struct{}

A2ACallTool lets an agent delegate a task to a remote A2A agent over HTTP. This is the agent-to-agent counterpart of MCP: instead of calling a tool on a server, the agent sends a natural-language task to another agent and gets its reply back.

func NewA2ACall added in v0.2.0 

func NewA2ACall() *A2ACallTool

NewA2ACall constructs the a2a_call tool.

func (*A2ACallTool) Description added in v0.2.0 

func (t *A2ACallTool) Description() string

func (*A2ACallTool) InputSchema added in v0.2.0 

func (t *A2ACallTool) InputSchema() json.RawMessage

func (*A2ACallTool) Name added in v0.2.0 

func (t *A2ACallTool) Name() string

func (*A2ACallTool) Run added in v0.2.0 

func (t *A2ACallTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type CodeSearchTool added in v0.0.24 

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

CodeSearchTool provides two search modes:

  • text: grep/ripgrep for exact pattern matching
  • symbol: in-memory index of functions, types, classes, imports

The index is built lazily on first symbol search and cached for the session.

func NewCodeSearch added in v0.0.24 

func NewCodeSearch() *CodeSearchTool

func (*CodeSearchTool) Description added in v0.0.24 

func (c *CodeSearchTool) Description() string

func (*CodeSearchTool) InputSchema added in v0.0.24 

func (c *CodeSearchTool) InputSchema() json.RawMessage

func (*CodeSearchTool) Name added in v0.0.24 

func (c *CodeSearchTool) Name() string

func (*CodeSearchTool) Run added in v0.0.24 

func (c *CodeSearchTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type CommandTool added in v0.2.0 

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

CommandTool is a user-defined tool backed by an external command (a tool MD with runtime: shell). The model's JSON input is written to the command's stdin; stdout (and stderr on failure) is returned to the model. This lets users add capabilities — scripts, CLIs, HTTP shims — without touching Go.

func NewCommandTool added in v0.2.0 

func NewCommandTool(name, description string, command []string, env map[string]string, schema json.RawMessage, timeout time.Duration) *CommandTool

NewCommandTool builds a command-backed tool. command[0] is the executable and the rest are fixed args. schema is the JSON-Schema advertised to the model; if nil, an empty object schema is used. timeout <= 0 defaults to 60s.

func (*CommandTool) Description added in v0.2.0 

func (c *CommandTool) Description() string

func (*CommandTool) InputSchema added in v0.2.0 

func (c *CommandTool) InputSchema() json.RawMessage

func (*CommandTool) Name added in v0.2.0 

func (c *CommandTool) Name() string

func (*CommandTool) Run added in v0.2.0 

func (c *CommandTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type ConfirmFunc 

type ConfirmFunc func(ctx context.Context, prompt string) (bool, error)

ConfirmFunc asks the user to approve an action. Returns true if approved.

type DelegateTool 

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

DelegateTool exposes a "delegate" function to the model so it can hand off subtasks to subagents listed in its frontmatter.

func NewDelegate 

func NewDelegate(spawn SpawnFunc, available []string) *DelegateTool

NewDelegate constructs a DelegateTool. available is advertised to the model in the description and as an enum in the input schema; the tool also rejects calls naming a subagent not in the list, as a defense in depth against models hallucinating an out-of-policy delegation.

func (*DelegateTool) Description 

func (d *DelegateTool) Description() string

Description implements Tool.

func (*DelegateTool) InputSchema 

func (d *DelegateTool) InputSchema() json.RawMessage

InputSchema implements Tool.

func (*DelegateTool) Name 

func (d *DelegateTool) Name() string

Name implements Tool.

func (*DelegateTool) Run 

func (d *DelegateTool) Run(ctx context.Context, input json.RawMessage) (string, error)

Run implements Tool.

type FSListTool 

type FSListTool struct {
	MaxEntries int
	MaxDepth   int
}

FSListTool lists directory contents, optionally recursive.

func NewFSList 

func NewFSList() *FSListTool

NewFSList returns an FSListTool with reasonable defaults.

func (*FSListTool) Description 

func (f *FSListTool) Description() string

func (*FSListTool) InputSchema 

func (f *FSListTool) InputSchema() json.RawMessage

func (*FSListTool) Name 

func (f *FSListTool) Name() string

func (*FSListTool) Run 

func (f *FSListTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type FSReadTool 

type FSReadTool struct {
	MaxBytes int64
}

FSReadTool reads text files and PDFs from disk, capped at MaxBytes.

func NewFSRead 

func NewFSRead() *FSReadTool

NewFSRead returns an FSReadTool with reasonable defaults.

func (*FSReadTool) Description 

func (f *FSReadTool) Description() string

Description implements Tool.

func (*FSReadTool) InputSchema 

func (f *FSReadTool) InputSchema() json.RawMessage

InputSchema implements Tool.

func (*FSReadTool) Name 

func (f *FSReadTool) Name() string

Name implements Tool.

func (*FSReadTool) Run 

func (f *FSReadTool) Run(ctx context.Context, input json.RawMessage) (string, error)

Run implements Tool.

type FSWriteMultiTool added in v0.0.34 

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

FSWriteMultiTool applies multiple file writes atomically. If any write fails, all previously applied writes in the batch are rolled back.

func NewFSWriteMulti added in v0.0.34 

func NewFSWriteMulti(confirm ConfirmFunc, undo *UndoStack) *FSWriteMultiTool

func (*FSWriteMultiTool) Description added in v0.0.34 

func (f *FSWriteMultiTool) Description() string

func (*FSWriteMultiTool) InputSchema added in v0.0.34 

func (f *FSWriteMultiTool) InputSchema() json.RawMessage

func (*FSWriteMultiTool) Name added in v0.0.34 

func (f *FSWriteMultiTool) Name() string

func (*FSWriteMultiTool) Run added in v0.0.34 

func (f *FSWriteMultiTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type FSWriteTool 

type FSWriteTool struct {
	Confirm  ConfirmFunc
	Undo     *UndoStack
	MaxBytes int
}

FSWriteTool writes or patches a UTF-8 text file on disk with diff preview, user confirmation, and undo support.

func NewFSWrite 

func NewFSWrite(confirm ConfirmFunc, undo *UndoStack) *FSWriteTool

func (*FSWriteTool) Description 

func (f *FSWriteTool) Description() string

func (*FSWriteTool) InputSchema 

func (f *FSWriteTool) InputSchema() json.RawMessage

func (*FSWriteTool) Name 

func (f *FSWriteTool) Name() string

func (*FSWriteTool) Run 

func (f *FSWriteTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type GitTool 

type GitTool struct {
	Timeout time.Duration
}

GitTool provides structured git operations. Wraps the git CLI rather than using go-git to keep dependencies minimal.

func NewGit 

func NewGit() *GitTool

func (*GitTool) Description 

func (g *GitTool) Description() string

func (*GitTool) InputSchema 

func (g *GitTool) InputSchema() json.RawMessage

func (*GitTool) Name 

func (g *GitTool) Name() string

func (*GitTool) Run 

func (g *GitTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type KMBlastRadiusTool added in v0.2.0 

type KMBlastRadiusTool struct{}

KMBlastRadiusTool reports what depends on a file/function/service.

func NewKMBlastRadius added in v0.2.0 

func NewKMBlastRadius() *KMBlastRadiusTool

func (*KMBlastRadiusTool) Description added in v0.2.0 

func (t *KMBlastRadiusTool) Description() string

func (*KMBlastRadiusTool) InputSchema added in v0.2.0 

func (t *KMBlastRadiusTool) InputSchema() json.RawMessage

func (*KMBlastRadiusTool) Name added in v0.2.0 

func (t *KMBlastRadiusTool) Name() string

func (*KMBlastRadiusTool) Run added in v0.2.0 

func (t *KMBlastRadiusTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type KMIndexTool added in v0.2.0 

type KMIndexTool struct{}

KMIndexTool adds a repo or directory to the knowledge graph.

func NewKMIndex added in v0.2.0 

func NewKMIndex() *KMIndexTool

func (*KMIndexTool) Description added in v0.2.0 

func (t *KMIndexTool) Description() string

func (*KMIndexTool) InputSchema added in v0.2.0 

func (t *KMIndexTool) InputSchema() json.RawMessage

func (*KMIndexTool) Name added in v0.2.0 

func (t *KMIndexTool) Name() string

func (*KMIndexTool) Run added in v0.2.0 

func (t *KMIndexTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type KMSearchTool added in v0.2.0 

type KMSearchTool struct{}

KMSearchTool runs semantic + graph search over the knowledge base.

func NewKMSearch added in v0.2.0 

func NewKMSearch() *KMSearchTool

func (*KMSearchTool) Description added in v0.2.0 

func (t *KMSearchTool) Description() string

func (*KMSearchTool) InputSchema added in v0.2.0 

func (t *KMSearchTool) InputSchema() json.RawMessage

func (*KMSearchTool) Name added in v0.2.0 

func (t *KMSearchTool) Name() string

func (*KMSearchTool) Run added in v0.2.0 

func (t *KMSearchTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type KMStatusTool added in v0.2.0 

type KMStatusTool struct{}

KMStatusTool reports knowledge base statistics.

func NewKMStatus added in v0.2.0 

func NewKMStatus() *KMStatusTool

func (*KMStatusTool) Description added in v0.2.0 

func (t *KMStatusTool) Description() string

func (*KMStatusTool) InputSchema added in v0.2.0 

func (t *KMStatusTool) InputSchema() json.RawMessage

func (*KMStatusTool) Name added in v0.2.0 

func (t *KMStatusTool) Name() string

func (*KMStatusTool) Run added in v0.2.0 

func (t *KMStatusTool) Run(ctx context.Context, _ json.RawMessage) (string, error)

type KnowledgeTool added in v0.2.0 

type KnowledgeTool struct{}

func NewKnowledge added in v0.2.0 

func NewKnowledge() *KnowledgeTool

func (*KnowledgeTool) Description added in v0.2.0 

func (k *KnowledgeTool) Description() string

func (*KnowledgeTool) InputSchema added in v0.2.0 

func (k *KnowledgeTool) InputSchema() json.RawMessage

func (*KnowledgeTool) Name added in v0.2.0 

func (k *KnowledgeTool) Name() string

func (*KnowledgeTool) Run added in v0.2.0 

func (k *KnowledgeTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type PIIFinding added in v0.0.31 

type PIIFinding struct {
	Type  string
	Match string
}

PIIFinding represents a detected PII instance.

type PIIGuard added in v0.0.31 

type PIIGuard struct {
	Mode PIIMode
	// contains filtered or unexported fields
}

PIIGuard scans text for personally identifiable information and redacts or flags it based on the configured mode.

func NewPIIGuard added in v0.0.31 

func NewPIIGuard(mode PIIMode) *PIIGuard

NewPIIGuard creates a guard with the given mode.

func (*PIIGuard) Redact added in v0.0.31 

func (g *PIIGuard) Redact(text string) string

Redact replaces all PII in text with placeholder tokens.

func (*PIIGuard) Scan added in v0.0.31 

func (g *PIIGuard) Scan(text string) []PIIFinding

Scan checks text for PII and returns findings.

func (*PIIGuard) Summary added in v0.0.31 

func (g *PIIGuard) Summary(findings []PIIFinding) string

Summary returns a human-readable summary of findings.

type PIIMode added in v0.0.31 

type PIIMode string

PIIMode controls how PII is handled. 

const (
	PIIModeOff    PIIMode = "off"
	PIIModeRedact PIIMode = "redact"
	PIIModeWarn   PIIMode = "warn"
)

type Registry 

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

Registry holds a set of tools indexed by name.

func Builtins 

func Builtins(confirm ConfirmFunc, undo *UndoStack) *Registry

Builtins returns a registry preloaded with the always-available tools. confirm gates fs_write; pass nil for auto-approve (non-interactive runs).

func Merge 

func Merge(regs ...*Registry) *Registry

Merge combines registries into a single one. Later registries override earlier ones on name collisions.

func NewRegistry 

func NewRegistry(ts ...Tool) *Registry

NewRegistry constructs a registry from the given tools. Later entries override earlier ones if names collide.

func (*Registry) All 

func (r *Registry) All() []Tool

All returns the registered tools. Order is unspecified.

func (*Registry) Filter 

func (r *Registry) Filter(names []string) (*Registry, []string)

Filter returns a new registry containing only the named tools, plus the list of names that were not found. Callers typically use the missing list to warn the user that an agent's allowlist references unknown tools.

func (*Registry) Get 

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

Get returns a tool by name.

func (*Registry) Run 

func (r *Registry) Run(ctx context.Context, name string, input json.RawMessage) (string, error)

Run executes a tool by name.

type ShellTool 

type ShellTool struct {
	Timeout time.Duration
	MaxOut  int
	Shell   string // path to shell; defaults to /bin/sh
}

ShellTool runs commands via /bin/sh -c. Output is combined stdout+stderr, truncated at MaxOut bytes. A non-zero exit is reported as part of the output (not a tool error) so the model can read it and react.

func NewShell 

func NewShell() *ShellTool

NewShell returns a ShellTool with reasonable defaults. On Windows, uses cmd.exe; on Unix, /bin/sh.

func (*ShellTool) Description 

func (s *ShellTool) Description() string

Description implements Tool.

func (*ShellTool) InputSchema 

func (s *ShellTool) InputSchema() json.RawMessage

InputSchema implements Tool.

func (*ShellTool) Name 

func (s *ShellTool) Name() string

Name implements Tool.

func (*ShellTool) Run 

func (s *ShellTool) Run(ctx context.Context, input json.RawMessage) (string, error)

Run implements Tool.

type SpawnFunc 

type SpawnFunc func(ctx context.Context, name, task, model string) (string, error)

SpawnFunc runs a named subagent with a task and returns its final assistant text. The model parameter is optional; if empty, the subagent uses its default model from the agent definition. Implementations are responsible for cycle detection, depth limiting, and resource cleanup.

type TestRunTool 

type TestRunTool struct {
	Timeout time.Duration
	MaxOut  int
}

TestRunTool runs a test command and returns structured output indicating pass/fail with the failure output. The model can use this in a loop: edit → test → read failures → edit → test until green.

func NewTestRun 

func NewTestRun() *TestRunTool

func (*TestRunTool) Description 

func (t *TestRunTool) Description() string

func (*TestRunTool) InputSchema 

func (t *TestRunTool) InputSchema() json.RawMessage

func (*TestRunTool) Name 

func (t *TestRunTool) Name() string

func (*TestRunTool) Run 

func (t *TestRunTool) Run(ctx context.Context, input json.RawMessage) (string, error)

type Tool 

type Tool interface {
	Name() string
	Description() string
	InputSchema() json.RawMessage
	Run(ctx context.Context, input json.RawMessage) (string, error)
}

Tool is something the model can invoke. Run executes the tool with the model-provided JSON input and returns either a text result (passed back to the model verbatim) or an error.

Convention: a tool that wraps a process whose own exit code communicates failure (e.g. shell) should return (output, nil) and let the model see the exit info inside the output. Reserve a non-nil error for failures of the tool itself: bad input, transport errors, timeouts.

func KMTools added in v0.2.0 

func KMTools() []Tool

KMTools returns the knowledge-master tool set. The desktop app merges these into every session so the chat agent can search and grow the graph; the CLI can reference them via an agent's tools allowlist.

func LoadCommandTools added in v0.2.0 

func LoadCommandTools(dir string) ([]Tool, []error)

LoadCommandTools scans dir for tool MD files (type: tool, runtime: shell) and builds an executable CommandTool for each. Non-shell tool specs and non-tool documents are skipped. A missing directory is not an error. Parse/validation failures are collected and returned so callers can surface them without aborting the whole load.

type UndoStack 

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

UndoStack tracks file states for rollback. Thread-safe.

func (*UndoStack) Len 

func (u *UndoStack) Len() int

Len returns the number of undoable operations.

func (*UndoStack) Pop 

func (u *UndoStack) Pop() (string, error)

Pop reverts the most recent file change. Returns a description or error.

func (*UndoStack) Push 

func (u *UndoStack) Push(path string)

Push saves the current state of a file before modification.

type WebFetchTool 

type WebFetchTool struct {
	MaxBytes int
	// contains filtered or unexported fields
}

WebFetchTool fetches a URL and returns the readable text content. HTML is stripped to plain text; non-HTML responses are returned as-is. Output is capped at MaxBytes to avoid blowing the context window.

func NewWebFetch 

func NewWebFetch() *WebFetchTool

NewWebFetch returns a WebFetchTool with reasonable defaults.

func (*WebFetchTool) Description 

func (w *WebFetchTool) Description() string

func (*WebFetchTool) InputSchema 

func (w *WebFetchTool) InputSchema() json.RawMessage

func (*WebFetchTool) Name 

func (w *WebFetchTool) Name() string

func (*WebFetchTool) Run 

func (w *WebFetchTool) Run(ctx context.Context, input json.RawMessage) (string, error)

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.