tools

package
v1.8.8 Latest Latest
Warning

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

Go to latest
Published: Oct 18, 2026 License: Apache-2.0 Imports: 34 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func CwdFromContext added in v1.7.3

func CwdFromContext(ctx context.Context) string

CwdFromContext returns the working directory ctx carries, or "".

func Defer added in v1.8.5

func Defer(tools []agentcore.Tool) []agentcore.Tool

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

func ExpandPath(p string) string

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

func FileOps(history []agentcore.Message) string

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

func IsSkipDir(name string) bool

IsSkipDir reports whether a directory name should be excluded from traversal.

func ResolvePath added in v1.5.1

func ResolvePath(workDir, userPath string) string

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

func WithCwd(ctx context.Context, cwd func() string) context.Context

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 DirEntry added in v1.7.2

type DirEntry struct {
	Name  string
	IsDir bool
}

DirEntry is an entry of a directory.

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

type FileReadStamp struct {
	Mtime   time.Time
	Version string
	Partial bool
}

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

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.

func (OSFS) MkdirAll added in v1.8.5

func (OSFS) MkdirAll(_ context.Context, path string, perm fs.FileMode) error

func (OSFS) Open added in v1.8.5

func (OSFS) Open(_ context.Context, path string) (io.ReadCloser, error)

func (OSFS) ReadDir added in v1.8.5

func (OSFS) ReadDir(_ context.Context, path string) ([]DirEntry, error)

func (OSFS) ReadFile added in v1.8.5

func (OSFS) ReadFile(_ context.Context, path string) ([]byte, error)

func (OSFS) Stat added in v1.8.5

func (OSFS) Stat(_ context.Context, path string) (FileInfo, error)

func (OSFS) WriteFile added in v1.8.5

func (OSFS) WriteFile(_ context.Context, path string, data []byte, perm fs.FileMode) error

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

func (w Workspace) Bash() agentcore.Tool

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

func (w Workspace) Edit() agentcore.Tool

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

func (w Workspace) Glob() agentcore.Tool

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

func (w Workspace) Grep() agentcore.Tool

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

func (w Workspace) Ls() agentcore.Tool

Ls returns the ls tool: it lists directory contents as a tree, to a depth.

func (Workspace) Read added in v1.8.5

func (w Workspace) Read() agentcore.Tool

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) Tools added in v1.8.5

func (w Workspace) Tools() []agentcore.Tool

Tools returns read, write, edit, bash, glob, grep and ls.

func (Workspace) Write added in v1.8.5

func (w Workspace) Write() agentcore.Tool

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL