416 lines
13 KiB
Go
416 lines
13 KiB
Go
package builtin
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"io/fs"
|
|
"os"
|
|
"path/filepath"
|
|
"strings"
|
|
"unicode/utf8"
|
|
)
|
|
|
|
// ReadParams are the parameters for the read tool.
|
|
type ReadParams struct {
|
|
Path string `json:"path"`
|
|
File string `json:"file,omitempty"` // compatibility alias used by some providers
|
|
Offset int `json:"offset,omitempty"` // start line (1-based)
|
|
Limit int `json:"limit,omitempty"` // max lines to read
|
|
Full bool `json:"full,omitempty"` // explicitly allow a full-file response
|
|
}
|
|
|
|
// DefaultReadLines is the bounded line count used when no explicit read limit
|
|
// or full-file request is supplied.
|
|
const DefaultReadLines = 400
|
|
|
|
var readSchema = Schema{
|
|
Name: "read",
|
|
Description: fmt.Sprintf("Read file contents; pointed at a directory it returns a listing. Omitted limits return at most %d lines; set full:true only when the complete file is genuinely needed. Output is always capped at %d lines or %s and includes a continuation offset.", DefaultReadLines, DefaultMaxLines, FormatSize(DefaultMaxBytes)),
|
|
// file is an alias for path. No anyOf: the OpenAI Responses API rejects it.
|
|
Parameters: json.RawMessage(`{
|
|
"type": "object",
|
|
"properties": {
|
|
"path": {
|
|
"type": "string",
|
|
"description": "Absolute or relative file path to read"
|
|
},
|
|
"file": {
|
|
"type": "string",
|
|
"description": "Compatibility alias for path. Prefer path."
|
|
},
|
|
"offset": {
|
|
"type": "integer",
|
|
"description": "Start reading from this line number (1-based). Defaults to 1."
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"description": "Maximum number of lines to read. Defaults to 400 unless full is true."
|
|
},
|
|
"full": {
|
|
"type": "boolean",
|
|
"description": "Return the whole file up to the global safety cap, and resend lines you have already been shown. Defaults to false. Lines already read from an unchanged file are skipped unless this is set."
|
|
}
|
|
}
|
|
}`),
|
|
}
|
|
|
|
const (
|
|
// maxPathSuggestions bounds how many alternatives a not-found read offers.
|
|
maxPathSuggestions = 5
|
|
|
|
// maxSuggestionScan bounds the walk behind those suggestions. A miss is
|
|
// already an error path, so it must stay cheap on a large workspace.
|
|
maxSuggestionScan = 20000
|
|
)
|
|
|
|
// suggestPaths lists files sharing the missing path's basename.
|
|
func suggestPaths(cwd, missing string) string {
|
|
if cwd == "" {
|
|
return ""
|
|
}
|
|
want := filepath.Base(missing)
|
|
if want == "" || want == "." || want == string(filepath.Separator) {
|
|
return ""
|
|
}
|
|
|
|
// If the directory exists, its contents are the most useful answer: the
|
|
// model had the location right and only the filename wrong. This is the
|
|
// shape of the real misses (internal/theme/theme.go, where the directory
|
|
// exists but holds colors.go), and it avoids the walk entirely.
|
|
if dir := filepath.Dir(missing); dir != "" {
|
|
if suggestion := dirContentsSuggestion(cwd, dir); suggestion != "" {
|
|
return suggestion
|
|
}
|
|
}
|
|
|
|
var found []string
|
|
scanned := 0
|
|
|
|
_ = filepath.WalkDir(cwd, func(path string, d fs.DirEntry, err error) error {
|
|
if err != nil {
|
|
return nil //nolint:nilerr // an unreadable subtree just yields no suggestions
|
|
}
|
|
if scanned++; scanned > maxSuggestionScan {
|
|
return fs.SkipAll
|
|
}
|
|
if d.IsDir() {
|
|
if skipSuggestionDir(d.Name()) {
|
|
return fs.SkipDir
|
|
}
|
|
return nil
|
|
}
|
|
if d.Name() != want {
|
|
return nil
|
|
}
|
|
if rel, relErr := filepath.Rel(cwd, path); relErr == nil {
|
|
found = append(found, rel)
|
|
}
|
|
if len(found) >= maxPathSuggestions {
|
|
return fs.SkipAll
|
|
}
|
|
return nil
|
|
})
|
|
|
|
if len(found) == 0 {
|
|
return ""
|
|
}
|
|
return "did you mean: " + strings.Join(found, ", ")
|
|
}
|
|
|
|
// dirContentsSuggestion lists the entries in an existing directory as a
|
|
// "did you mean" hint, or returns "" when the directory is unreadable or empty.
|
|
func dirContentsSuggestion(cwd, dir string) string {
|
|
entries, err := os.ReadDir(dir)
|
|
if err != nil {
|
|
return ""
|
|
}
|
|
names := make([]string, 0, maxPathSuggestions)
|
|
for _, e := range entries {
|
|
if len(names) >= maxPathSuggestions {
|
|
names = append(names, "...")
|
|
break
|
|
}
|
|
names = append(names, e.Name())
|
|
}
|
|
if len(names) == 0 {
|
|
return ""
|
|
}
|
|
rel, relErr := filepath.Rel(cwd, dir)
|
|
if relErr != nil {
|
|
rel = dir
|
|
}
|
|
return fmt.Sprintf("%s exists and contains: %s", rel, strings.Join(names, ", "))
|
|
}
|
|
|
|
// skipSuggestionDir keeps the suggestion walk out of directories that are large
|
|
// and never the answer.
|
|
func skipSuggestionDir(name string) bool {
|
|
switch name {
|
|
case ".git", "node_modules", "vendor", "dist", "build", ".cache":
|
|
return true
|
|
}
|
|
return false
|
|
}
|
|
|
|
// maxDirEntries bounds the listing returned when read is pointed at a
|
|
// directory. Large directories are truncated rather than refused.
|
|
const maxDirEntries = 200
|
|
|
|
// listDirResult renders a bounded directory listing. display is the path as
|
|
// the caller wrote it, so the notice echoes their own spelling.
|
|
func listDirResult(path, display string) (Result, error) {
|
|
entries, err := os.ReadDir(path)
|
|
if err != nil {
|
|
return Result{Content: fmt.Sprintf("error reading directory: %v", err), IsError: true}, nil
|
|
}
|
|
|
|
var b strings.Builder
|
|
fmt.Fprintf(&b, "%s is a directory, not a file. Listing:\n", display)
|
|
for i, e := range entries {
|
|
if i >= maxDirEntries {
|
|
fmt.Fprintf(&b, "\n[%d more entries; use find for a filtered search]", len(entries)-maxDirEntries)
|
|
break
|
|
}
|
|
if e.IsDir() {
|
|
fmt.Fprintf(&b, "%s/\n", e.Name())
|
|
continue
|
|
}
|
|
fmt.Fprintf(&b, "%s\n", e.Name())
|
|
}
|
|
|
|
return Result{Content: strings.TrimRight(b.String(), "\n"), Truncated: len(entries) > maxDirEntries}, nil
|
|
}
|
|
|
|
// NewReadTool creates the built-in read tool.
|
|
func NewReadTool(jail Jail, rt *ReadTracker) Tool {
|
|
return Tool{
|
|
Schema: readSchema,
|
|
Source: "builtin",
|
|
Emoji: "📄",
|
|
Execute: makeReadExecutor(jail, rt),
|
|
}
|
|
}
|
|
|
|
func makeReadExecutor(jail Jail, rt *ReadTracker) Executor {
|
|
cwd := jail.Root
|
|
return func(ctx context.Context, params json.RawMessage, _ UIBridge) (Result, error) {
|
|
p, terminal, err := parseReadParams(params)
|
|
if err != nil {
|
|
return Result{}, err
|
|
}
|
|
if terminal != nil {
|
|
return *terminal, nil
|
|
}
|
|
|
|
path := resolvePath(cwd, p.Path)
|
|
if !jail.ReadConfines(path) {
|
|
return Result{Content: "path escapes working directory", IsError: true, ErrorKind: "sandbox_escape"}, nil
|
|
}
|
|
|
|
readCtx, cancel := context.WithTimeout(ctx, DefaultToolTimeout)
|
|
defer cancel()
|
|
|
|
var result Result
|
|
err = runWithContext(readCtx, func() error {
|
|
info, statErr := os.Stat(path)
|
|
if statErr != nil {
|
|
msg := fmt.Sprintf("error stating file: %v", statErr)
|
|
if hint := suggestPaths(cwd, path); hint != "" {
|
|
msg += "\n" + hint
|
|
}
|
|
result = Result{Content: msg, IsError: true, ErrorKind: "not_found"}
|
|
return nil
|
|
}
|
|
|
|
state, terminal := readFileContent(cwd, path, p, info, rt)
|
|
if terminal != nil {
|
|
result = *terminal
|
|
return nil
|
|
}
|
|
result = serveReadContent(cwd, path, p, info, state, rt)
|
|
return nil
|
|
})
|
|
if err != nil {
|
|
if errors.Is(err, context.DeadlineExceeded) {
|
|
return Result{Content: fmt.Sprintf("read timed out after %v", DefaultToolTimeout), IsError: true}, nil
|
|
}
|
|
return Result{Content: fmt.Sprintf("read failed: %v", err), IsError: true}, nil
|
|
}
|
|
|
|
return result, nil
|
|
}
|
|
}
|
|
|
|
// readParams bundles the values that survive parameter parsing and validation
|
|
// into the content-serving phase.
|
|
type readParams struct {
|
|
ReadParams
|
|
RangeRequested bool
|
|
}
|
|
|
|
// parseReadParams decodes and validates a read request, applying the file
|
|
// alias and default limit. terminal is non-nil when the request is rejected
|
|
// before any filesystem work.
|
|
func parseReadParams(params json.RawMessage) (readParams, *Result, error) {
|
|
var p readParams
|
|
if err := json.Unmarshal(params, &p.ReadParams); err != nil {
|
|
return p, &Result{Content: fmt.Sprintf("invalid parameters: %v", err), IsError: true}, nil
|
|
}
|
|
if p.Offset < 0 {
|
|
return p, &Result{Content: "offset must be >= 0", IsError: true}, nil
|
|
}
|
|
if p.Limit < 0 {
|
|
return p, &Result{Content: "limit must be >= 0", IsError: true}, nil
|
|
}
|
|
if strings.TrimSpace(p.Path) == "" {
|
|
p.Path = p.File
|
|
}
|
|
if strings.TrimSpace(p.Path) == "" {
|
|
return p, &Result{Content: "path is required (file is accepted as an alias)", IsError: true, ErrorKind: "invalid_arguments"}, nil
|
|
}
|
|
// Record whether the caller asked for a specific slice before the
|
|
// default is applied. An explicit limit that happens to equal the
|
|
// default is still an explicit content request, so it must not be
|
|
// mistaken for "unspecified" by the outline check below.
|
|
p.RangeRequested = p.Offset > 0 || p.Limit > 0
|
|
if p.Limit == 0 && !p.Full {
|
|
p.Limit = DefaultReadLines
|
|
}
|
|
return p, nil, nil
|
|
}
|
|
|
|
// readFileState carries the loaded file into the content-serving phase.
|
|
type readFileState struct {
|
|
Data []byte
|
|
Lines []string
|
|
}
|
|
|
|
// readFileContent resolves the stat result into either a terminal answer (a
|
|
// directory listing, an oversize refusal, a read error, or a binary
|
|
// detection) or the loaded content plus an outline that may be returned in
|
|
// place of the first page.
|
|
func readFileContent(cwd, path string, p readParams, info os.FileInfo, rt *ReadTracker) (*readFileState, *Result) {
|
|
if info.IsDir() {
|
|
// The intent is unambiguous, so answer it rather than spending a
|
|
// round trip on an error. Deliberately returned before MarkRead:
|
|
// a directory must never satisfy the read-before-write check.
|
|
res, _ := listDirResult(path, p.Path)
|
|
return nil, &res
|
|
}
|
|
if info.Size() > maxReadBytes {
|
|
return nil, &Result{Content: fmt.Sprintf("file too large (%s > %s)", FormatSize(int(info.Size())), FormatSize(maxReadBytes)), IsError: true}
|
|
}
|
|
|
|
data, err := os.ReadFile(path)
|
|
if err != nil {
|
|
return nil, &Result{Content: fmt.Sprintf("error reading file: %v", err), IsError: true}
|
|
}
|
|
|
|
// Record the read so mutation tools can enforce read-before-write.
|
|
// Only record after a successful ReadFile so we don't mark files
|
|
// that couldn't actually be read.
|
|
if rt != nil {
|
|
rt.MarkRead(cwd, p.Path)
|
|
}
|
|
|
|
if !utf8.Valid(data) {
|
|
return nil, &Result{Content: "file appears to be binary", IsError: true}
|
|
}
|
|
|
|
return &readFileState{Data: data, Lines: strings.Split(string(data), "\n")}, nil
|
|
}
|
|
|
|
// serveReadContent applies the outline shortcut, offset/limit window, and
|
|
// read-before-write bookkeeping, then renders the bounded output.
|
|
func serveReadContent(cwd, path string, p readParams, info os.FileInfo, state *readFileState, rt *ReadTracker) Result {
|
|
lines := state.Lines
|
|
totalLines := len(lines)
|
|
|
|
// For a large source file with no explicit range requested, an index of
|
|
// the whole file beats its first page. Returned before the served-range
|
|
// bookkeeping below, because the model has not been shown any of these
|
|
// lines and a later read of them must not be suppressed.
|
|
if !p.RangeRequested && !p.Full {
|
|
if outline := outlineFor(path, lines); outline != "" {
|
|
return Result{Content: outline, Truncated: true, ResultBytes: len(state.Data)}
|
|
}
|
|
}
|
|
|
|
startLine, endLine := readOffsetLimitWindow(p, totalLines)
|
|
if startLine > totalLines {
|
|
return Result{Content: fmt.Sprintf("offset %d exceeds file length (%d lines)", startLine, totalLines), IsError: true}
|
|
}
|
|
|
|
// Skip lines already shown from an unchanged file unless full is set.
|
|
requestedStart := startLine
|
|
if rt != nil && !p.Full {
|
|
novelStart, novelEnd, hasNovel := rt.Novel(cwd, p.Path, FileIdentity(info), startLine, endLine)
|
|
if !hasNovel {
|
|
return Result{Content: fmt.Sprintf(
|
|
"[lines %d-%d of %s are unchanged since you last read them; nothing new to show. Set full:true to have the content resent.]",
|
|
startLine, endLine, p.Path,
|
|
)}
|
|
}
|
|
startLine, endLine = novelStart, novelEnd
|
|
}
|
|
|
|
selected := strings.Join(lines[startLine-1:endLine], "\n")
|
|
tr := TruncateHeadRaw(selected, DefaultMaxLines, DefaultMaxBytes)
|
|
output := tr.Content
|
|
|
|
if startLine > requestedStart {
|
|
output = fmt.Sprintf(
|
|
"[lines %d-%d unchanged since you last read them; showing from line %d.]\n\n",
|
|
requestedStart, startLine-1, startLine,
|
|
) + output
|
|
}
|
|
|
|
output += readTrailingNotice(p, tr, lines, startLine, endLine, totalLines)
|
|
|
|
return Result{Content: output, Truncated: tr.Truncated || endLine < totalLines, ResultBytes: tr.OriginalSize}
|
|
}
|
|
|
|
// readOffsetLimitWindow resolves the requested 1-based [startLine, endLine]
|
|
// window from the offset/limit parameters and the file's total line count.
|
|
func readOffsetLimitWindow(p readParams, totalLines int) (startLine, endLine int) {
|
|
startLine = 1
|
|
if p.Offset > 0 {
|
|
startLine = p.Offset
|
|
}
|
|
|
|
endLine = totalLines
|
|
if p.Limit > 0 && startLine+p.Limit-1 < endLine {
|
|
endLine = startLine + p.Limit - 1
|
|
}
|
|
return startLine, endLine
|
|
}
|
|
|
|
// readTrailingNotice returns the hint appended after served content, or "".
|
|
func readTrailingNotice(p readParams, tr TruncationResult, lines []string, startLine, endLine, totalLines int) string {
|
|
switch {
|
|
case tr.Truncated && tr.OutputLines == 0:
|
|
// The first requested line alone exceeds the byte limit. Point the
|
|
// model at a shell fallback that can slice within the line.
|
|
lineSize := FormatSize(len(lines[startLine-1]))
|
|
return fmt.Sprintf(
|
|
"[line %d is %s, exceeding the %s output limit. Use shell: sed -n '%dp' %s | head -c %d]",
|
|
startLine, lineSize, FormatSize(DefaultMaxBytes), startLine, p.Path, DefaultMaxBytes,
|
|
)
|
|
case tr.Truncated:
|
|
shownEnd := startLine + tr.OutputLines - 1
|
|
return fmt.Sprintf(
|
|
"\n\n[showing lines %d-%d of %d. Use offset=%d to continue.]",
|
|
startLine, shownEnd, totalLines, shownEnd+1,
|
|
)
|
|
case endLine < totalLines:
|
|
// A user-specified limit stopped early, but the file has more content.
|
|
return fmt.Sprintf(
|
|
"\n\n[%d more lines in file. Use offset=%d to continue.]",
|
|
totalLines-endLine, endLine+1,
|
|
)
|
|
}
|
|
return ""
|
|
}
|