tools

Documentation

Overview

Package tools provides reusable, zero-key core.Tool constructors built on the stdlib: web fetching (HTTPFetch), sandboxed file access (ReadFile, WriteFile), an opt-in allow-listed shell (Shell), and a vendor-neutral web search adapter (WebSearch) whose backends (e.g. the tavily extension) plug in via the Searcher interface.

Everything composes with the existing core.Func schema machinery; the module adds no dependencies beyond core itself.

Error and retry semantics

Errors returned by these tools follow the core.Func contract: the run converts them to "error: <msg>" strings the model can recover from. The agent loop additionally wraps execution in its retry policy, which by default retries only errors implementing retry.Retryable — plain errors fail fast. If you build your own tools around non-idempotent operations, return plain (non-Retryable) errors so a transient-looking failure is never re-executed.

Index

• func HTTPFetch() core.Tool
• func ReadFile(root string) core.Tool
• func Shell(cfg ShellConfig) core.Tool
• func WebSearch(s Searcher) core.Tool
• func WriteFile(root string) core.Tool
• type Result
• type Searcher
• type ShellConfig

Functions

func HTTPFetch

func HTTPFetch() core.Tool

HTTPFetch returns an "http_fetch" tool that GETs a URL and returns its readable text: HTML is reduced to text (scripts, styles and tags stripped), text and JSON bodies are returned as-is, and other content types are rejected. Responses are capped at 512 KiB with a truncation marker.

Security: the model chooses the URL, so this tool will happily fetch internal endpoints reachable from the host (SSRF). In production, gate it with an core.Approver or front it with an egress proxy.

func ReadFile

func ReadFile(root string) core.Tool

ReadFile returns a "read_file" tool that reads text files strictly inside root. Path traversal and symlinks that escape the root are rejected (the sandbox is enforced by os.Root, not string cleaning). Files are capped at 256 KiB with a truncation marker.

func Shell

func Shell(cfg ShellConfig) core.Tool

Shell returns an opt-in "shell" tool that runs allow-listed programs. Commands execute argv-style via exec.CommandContext — there is no shell interpretation, so pipes, globs and `$(...)` have no effect (and no injection surface). To expose a pipeline, allow-list a script that wraps it.

Combined stdout+stderr is returned, capped at 64 KiB. A non-zero exit is a tool error (recoverable by the model) carrying the output; a timeout is reported as a plain error so it never aborts the enclosing run.

func WebSearch

func WebSearch(s Searcher) core.Tool

WebSearch adapts any Searcher into a "web_search" tool. Results are formatted as a numbered list of title, URL and content snippet — sources the model can cite directly.

func WriteFile

func WriteFile(root string) core.Tool

WriteFile returns a "write_file" tool that writes files strictly inside root, creating parent directories as needed. Path traversal and symlinks that escape the root are rejected (enforced by os.Root).

Types

type Result

type Result struct {
	Title   string
	URL     string
	Content string
}

Result is one web search hit.

type Searcher

type Searcher interface {
	Search(ctx context.Context, query string, max int) ([]Result, error)
}

Searcher is the pluggable backend behind WebSearch: the tool stays vendor-neutral while keyed providers (extensions/tavily, …) implement this interface in their own modules.

type ShellConfig

type ShellConfig struct {
	// Allow lists the exact program names (or absolute paths) the model may
	// run. A requested command must match an entry verbatim — there is no
	// pattern matching.
	Allow []string
	// Dir is the working directory for commands ("" = the process's cwd).
	Dir string
	// Timeout bounds each invocation (default 30s).
	Timeout time.Duration
}

ShellConfig configures the Shell tool. Allow is mandatory in practice: an empty allow-list denies every command.