Documentation
¶
Overview ¶
Package tools implements the agent's file and shell tools, sandboxed to a root directory.
Index ¶
- Constants
- func Bash(ctx context.Context, root, command string, timeout time.Duration) (string, error)
- func BashStream(ctx context.Context, root, command string, timeout time.Duration, ...) (string, error)
- func EditFile(root, path, oldStr, newStr string, replaceAll bool) (int, error)
- func Grep(root, pattern, path, include string, ignoreCase, fixedStrings bool) (string, error)
- func GrepWithContext(root, pattern, path, include string, ignoreCase, fixedStrings bool, ...) (string, error)
- func ListFiles(root, path, pattern string) (string, error)
- func ReadFile(root, path string, offset, limit int) (string, error)
- func Resolve(root, path string) (string, error)
- func Specs(readOnly ...bool) []model.ToolSpec
- func WriteFile(root, path, content string) error
- type Executor
- func (e *Executor) Catalog() []model.ToolSpec
- func (e *Executor) Close() string
- func (e *Executor) ReadProcess(ctx context.Context, id string, waitMs, tail int) (string, error)
- func (e *Executor) Run(ctx context.Context, call model.ToolCall) string
- func (e *Executor) RunWithError(ctx context.Context, call model.ToolCall) (string, bool)
- func (e *Executor) StartProcess(command string) (string, error)
- func (e *Executor) StopProcess(id string, tail int) (string, error)
Constants ¶
const ( // DefaultMaxProcesses bounds concurrent background processes when // Executor.MaxProcesses is 0. DefaultMaxProcesses = 4 // DefaultProcessBufferBytes caps each background process's retained // output when Executor.ProcessBufferBytes is 0. DefaultProcessBufferBytes = 1 << 20 )
Variables ¶
This section is empty.
Functions ¶
func Bash ¶
Bash runs command in a fresh `bash -c` process in root. On timeout the whole process group is killed so background children do not linger.
func BashStream ¶ added in v0.4.0
func BashStream(ctx context.Context, root, command string, timeout time.Duration, live io.Writer) (string, error)
BashStream is Bash that also copies output to live, if non-nil, as it is produced. The returned result is the same as Bash's.
func EditFile ¶
EditFile replaces the single occurrence of oldStr with newStr, or every occurrence if replaceAll is set, and returns the number of replacements.
func Grep ¶
Grep returns lines matching pattern as "file:line: content". Binary and very large files are skipped. A non-empty include glob limits the search to matching files, using the same rules as ListFiles: a glob without "/" matches base names, a glob with "/" matches paths relative to the searched directory. When path is a single file, include is ignored. ignoreCase enables case-insensitive matching of file contents only. fixedStrings treats pattern as literal text instead of a Go regular expression.
func GrepWithContext ¶ added in v0.4.0
func GrepWithContext(root, pattern, path, include string, ignoreCase, fixedStrings bool, contextLines int) (string, error)
GrepWithContext returns matches with up to contextLines surrounding lines.
func ListFiles ¶
ListFiles lists the entries of a directory, or, with a pattern, walks it recursively and returns matching files. A pattern without "/" matches base names; a pattern with "/" matches paths relative to the listed directory.
func ReadFile ¶
ReadFile returns a file's contents. A positive offset (1-based start line) or limit (max lines) returns just that range, ending in a "[lines A-B of N]" note when the range isn't the whole file.
func Resolve ¶
Resolve maps a path relative to root (or absolute inside root) to an absolute path, rejecting anything that escapes root. The check is lexical; symlinks inside root that point outside it are followed.
Types ¶
type Executor ¶
type Executor struct {
Root string // absolute working directory
ReadOnly bool // permits only read_file, list_files, and grep
BashTimeout time.Duration
MaxOutputChars int // 0 = unlimited
// MaxProcesses bounds concurrently running background processes
// (0 = DefaultMaxProcesses).
MaxProcesses int
// ProcessBufferBytes caps the output kept per background process
// (0 = DefaultProcessBufferBytes); older output is dropped.
ProcessBufferBytes int
// Stream receives bash output as it is produced when a call sets
// stream: true. nil discards it (the result is unchanged either way).
Stream io.Writer
ExternalSpecs []model.ToolSpec
ExternalCall func(context.Context, string, string) (string, bool)
// contains filtered or unexported fields
}
Executor runs tool calls against files under Root.
func (*Executor) Catalog ¶ added in v0.4.0
Catalog returns the fixed built-in and explicitly configured external tools. In read-only mode it returns only the read-only built-ins: external MCP tools must never be offered (or dispatched, see Run) when only read_file, list_files, and grep are available.
func (*Executor) Close ¶ added in v0.4.0
Close kills every background process still registered and returns a summary of each (status and output tail), or "" if there were none. Call it when the run ends so nothing is left running.
func (*Executor) ReadProcess ¶ added in v0.4.0
ReadProcess returns output produced since the last read. With waitMs > 0 it blocks up to that long for new output; with tail > 0 it returns only the last tail lines.
func (*Executor) Run ¶
Run executes one tool call and returns text for the model. Tool failures are reported as text so the model can recover; Run never returns an error.
func (*Executor) RunWithError ¶ added in v0.4.0
RunWithError executes a tool call and reports whether execution failed. The returned text is still suitable for passing back to the model.
func (*Executor) StartProcess ¶ added in v0.4.0
StartProcess launches command with bash -c in the background and returns its id with any output produced in the first moment.
Source Files