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 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 ConfirmFunc ¶
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) Run ¶
func (d *DelegateTool) Run(ctx context.Context, input json.RawMessage) (string, error)
Run implements Tool.
type FSListTool ¶
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 a UTF-8 text file from disk, capped at MaxBytes. The path is resolved against the agent process's working directory; no sandboxing is performed.
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. Underscore (not dot) keeps the name within the `^[a-zA-Z0-9_-]{1,64}$` regex that Anthropic and OpenAI enforce on tool names sent in their `tools` arrays.
func (*FSReadTool) Run ¶
func (f *FSReadTool) Run(ctx context.Context, input json.RawMessage) (string, error)
Run implements Tool.
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 ¶
GitTool provides structured git operations. Wraps the git CLI rather than using go-git to keep dependencies minimal.
func (*GitTool) Description ¶
func (*GitTool) InputSchema ¶
func (g *GitTool) InputSchema() json.RawMessage
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 ¶
Merge combines registries into a single one. Later registries override earlier ones on name collisions.
func NewRegistry ¶
NewRegistry constructs a registry from the given tools. Later entries override earlier ones if names collide.
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 (*ShellTool) Description ¶
Description implements Tool.
func (*ShellTool) InputSchema ¶
func (s *ShellTool) InputSchema() json.RawMessage
InputSchema implements Tool.
type SpawnFunc ¶
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 ¶
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.
type UndoStack ¶
type UndoStack struct {
// contains filtered or unexported fields
}
UndoStack tracks file states for rollback. Thread-safe.
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