Documentation
¶
Overview ¶
Package tools holds the coding tools of an agent. A Workspace makes them and holds what they share: read, write and edit work on files through its FS and check writes against what the model read; bash runs commands, in the background as tasks of its task.Runtime; glob, grep and ls find and list files. Defer puts tools behind tool_search, so that their schemas cost no context until the model needs them.
Relative paths resolve against the Workspace's Dir, or the working directory a call's context carries (WithCwd); it is not a sandbox. Results are plain text.
Index ¶
- func CwdFromContext(ctx context.Context) string
- func Defer(tools []agentcore.Tool) []agentcore.Tool
- func ExpandPath(p string) string
- func FileOps(history []agentcore.Message) string
- func IsSkipDir(name string) bool
- func ResolvePath(workDir, userPath string) string
- func WithCwd(ctx context.Context, cwd func() string) context.Context
- type DirEntry
- type FS
- type FileInfo
- type FileReadStamp
- type FileReadState
- type OSFS
- func (OSFS) MkdirAll(_ context.Context, path string, perm fs.FileMode) error
- func (OSFS) Open(_ context.Context, path string) (io.ReadCloser, error)
- func (OSFS) ReadDir(_ context.Context, path string) ([]DirEntry, error)
- func (OSFS) ReadFile(_ context.Context, path string) ([]byte, error)
- func (OSFS) Stat(_ context.Context, path string) (FileInfo, error)
- func (OSFS) WriteFile(_ context.Context, path string, data []byte, perm fs.FileMode) error
- type Workspace
- func (w Workspace) Bash() agentcore.Tool
- func (w Workspace) Edit() agentcore.Tool
- func (w Workspace) Glob() agentcore.Tool
- func (w Workspace) Grep() agentcore.Tool
- func (w Workspace) Ls() agentcore.Tool
- func (w Workspace) Read() agentcore.Tool
- func (w Workspace) Tools() []agentcore.Tool
- func (w Workspace) Write() agentcore.Tool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CwdFromContext ¶ added in v1.7.3
CwdFromContext returns the working directory ctx carries, or "".
func Defer ¶ added in v1.8.5
Defer puts tools behind the tool_search tool: it returns tool_search followed by the tools, marked Deferred. A search returns references to the tools it found, which offer them from then on (see Tool.Deferred).
The definition of tool_search does not depend on the tools, so a tool deferred later leaves the requests made before intact. The model learns the names to search for from the application, such as in a message.
func ExpandPath ¶ added in v1.5.1
ExpandPath normalizes a user-provided path:
- Replaces Unicode special spaces with ASCII space
- Expands ~ to the user's home directory
func FileOps ¶ added in v1.8.5
FileOps lists, as tagged sections, the files the read, write and edit calls in history touched, and those the lists of a summary in it name: those only read, and those modified. It is empty when there were none. A compaction appends it to its summary, so that the files the replaced messages worked on survive it, and every compaction after it.
func IsSkipDir ¶ added in v1.5.1
IsSkipDir reports whether a directory name should be excluded from traversal.
func ResolvePath ¶ added in v1.5.1
ResolvePath resolves a user-provided path against a working directory. If userPath is empty, returns workDir. If absolute, returns as-is. Otherwise joins with workDir.
Path semantics follow the workspace root. FS backends key files with slash-separated absolute paths (editor buffers, remote hosts), so a leading "/" counts as absolute even on Windows — where filepath.IsAbs would demand a drive letter and the fallthrough join would corrupt the virtual path ("/work" + "/work/f.txt" → `\work\work\f.txt`). Likewise a slash-rooted workDir joins with slash separators, never the OS's. OS-rooted paths (drive letters, UNC) keep filepath semantics unchanged, and on Unix the two branches coincide.
func WithCwd ¶ added in v1.7.3
WithCwd returns ctx carrying cwd, the working directory of the tool calls that run with it, which overrides their Workspace's Dir unless it returns "". It is consulted at each use, so that it may change while a run is under way, as when the agent enters a git worktree. The innermost wins.
Types ¶
type FS ¶ added in v1.8.5
type FS interface {
Stat(ctx context.Context, path string) (FileInfo, error)
// Open streams the file, as to read some lines of it or sniff its type.
Open(ctx context.Context, path string) (io.ReadCloser, error)
ReadFile(ctx context.Context, path string) ([]byte, error)
// ReadDir lists a directory, not recursively.
ReadDir(ctx context.Context, path string) ([]DirEntry, error)
// WriteFile writes data to path, replacing what was there.
WriteFile(ctx context.Context, path string, data []byte, perm fs.FileMode) error
MkdirAll(ctx context.Context, path string, perm fs.FileMode) error
}
FS is a file backend: the local filesystem, an editor serving its unsaved buffers, a remote host. Paths are absolute; those of a backend other than the local filesystem are best slash-separated ("/work/file.txt"), which the tools keep on every platform. A backend doing I/O over a transport honors ctx.
type FileInfo ¶ added in v1.7.2
type FileInfo struct {
Name string
Size int64
Mode fs.FileMode
ModTime time.Time
IsDir bool
// Version identifies the content, as a hash or an etag does, for a
// backend whose ModTime does not tell its changes, as unsaved editor
// buffers. When the read and the current FileInfo both have one, write
// and edit compare it instead of ModTime to detect a stale file.
Version string
}
FileInfo describes a file of an FS.
type FileReadStamp ¶ added in v1.6.9
FileReadStamp records the state of a file as the model read it. The write and edit tools consult these stamps in their Check and Run to enforce:
- read-before-write: a file must be read before it is overwritten.
- no-stale-write: the file must not have been modified externally between the last read and the write attempt.
Partial is true when the model did not see all of the file: it read from an offset, or the read stopped at its limit. A partial read is enough to edit, which changes only text the model quotes, but not to overwrite the file, whose rest the model has not seen.
A successful write or edit refreshes the stamp, so the LLM can keep changing a file it just changed without reading it again.
Version is the backend-defined content token recorded at read time (see FileInfo.Version). It is empty for the OS backend; Write/Edit fall back to comparing Mtime when either side's Version is empty.
type FileReadState ¶ added in v1.6.9
type FileReadState struct {
// contains filtered or unexported fields
}
FileReadState records what the model read, by absolute path: see Workspace.Files.
func NewFileReadState ¶ added in v1.6.9
func NewFileReadState() *FileReadState
func (*FileReadState) Forget ¶ added in v1.8.7
func (s *FileReadState) Forget()
Forget makes every read a partial one, as when the history no longer holds what the reads returned, after a compaction or a rewind: the model may still edit a file, quoting the text it changes, but reads it again before it overwrites it.
func (*FileReadState) Forgetting ¶ added in v1.8.7
func (s *FileReadState) Forgetting(c agentcore.Compactor) agentcore.Compactor
Forgetting returns c, which also forgets the reads (see Forget) whenever it compacts a history, before the history is replaced.
func (*FileReadState) Get ¶ added in v1.6.9
func (s *FileReadState) Get(path string) (FileReadStamp, bool)
func (*FileReadState) Set ¶ added in v1.6.9
func (s *FileReadState) Set(path string, stamp FileReadStamp)
type OSFS ¶ added in v1.8.5
type OSFS struct{}
OSFS is the local filesystem, an FS with no Version.
type Workspace ¶ added in v1.8.5
type Workspace struct {
// Dir is the directory relative paths resolve against, unless the
// context of a call carries another; see WithCwd. It is not a sandbox:
// an absolute path reaches any file.
Dir string
// FS is the file backend of read, write and edit; nil is the local
// filesystem. bash, glob, grep and ls work on the local filesystem.
FS FS
// Files records what the model read, so that write and edit refuse a
// file it has not read, or that changed since; nil checks nothing.
Files *FileReadState
// Tasks runs the commands bash runs in the background; nil offers no
// background mode.
Tasks *task.Runtime
// Sandbox, if set, returns the program and arguments that run argv, a
// shell command bash runs, inside a sandbox. bash then offers the model
// "unsandboxed" to run a command the sandbox blocked outside it, which
// whoever approves calls should ask about.
Sandbox func(ctx context.Context, argv []string) []string
// BashMaxTimeout bounds the timeout a model may set on a command bash
// runs in the foreground; zero is ten minutes.
BashMaxTimeout time.Duration
}
Workspace is where the coding tools work, and what they share. Its methods make the tools; the tools of one Workspace share its state.
func (Workspace) Bash ¶ added in v1.8.5
Bash returns the bash tool, which runs shell commands. It reports each line of their output as a string progress, and returns the tail of it, at most 2000 lines or 50KB, with a line for each of a non-zero exit code, a timeout and a cut. A command that fails is not a failed call: its output is what the model needs. With Tasks, the model may run a command in the background, as a task. With Sandbox, commands run inside it unless a call sets unsandboxed.
func (Workspace) Edit ¶ added in v1.8.5
Edit returns the edit tool: it replaces exact strings in a file, taking CRLF for LF and matching fuzzily, and changes no byte outside them. Its result is a line naming the file over the diff of the edit; its Check returns the diff as the call's preview. With Files, its Check and Run refuse a file the model has not read, or that changed since.
func (Workspace) Glob ¶ added in v1.8.5
Glob returns the glob tool: it matches files by glob pattern and returns their relative paths, newest first. It uses rg --files if available, and filepath.WalkDir otherwise; either way, .git is left out.
func (Workspace) Grep ¶ added in v1.8.5
Grep returns the grep tool: it searches file contents by pattern, with ripgrep (rg) if available, and regexp and bufio.Scanner otherwise.
func (Workspace) Ls ¶ added in v1.8.5
Ls returns the ls tool: it lists directory contents as a tree, to a depth.
func (Workspace) Read ¶ added in v1.8.5
Read returns the read tool: it reads a file, from an offset and up to a limit, lists a directory, or reads an image. Text is cut at a line count and a byte size; binary files are refused. What it read goes to Files.
func (Workspace) Write ¶ added in v1.8.5
Write returns the write tool: it writes content to a file, creating directories as needed, and reports what it wrote. Its Check returns the diff of the change, cut to a few lines, as the call's preview. With Files, its Check and Run refuse an existing file the model has not read whole, or that changed since.