filesystem

Documentation

Index

• Constants
• type CreateDirectoryArgs
• type DirectoryTreeArgs
• type DirectoryTreeMeta
• type Edit
• type EditFileArgs
  • func ParseEditFileArgs(data []byte) (EditFileArgs, error)
• type ListDirectoryArgs
• type ListDirectoryMeta
• type Opt
  • func WithAllowList(roots []string) Opt
  • func WithDenyList(roots []string) Opt
  • func WithIgnoreVCS(ignoreVCS bool) Opt
  • func WithPostEditCommands(postEditCommands []PostEditConfig) Opt
• type PostEditConfig
• type ReadFileArgs
• type ReadFileMeta
• type ReadMultipleFilesArgs
• type ReadMultipleFilesMeta
• type RemoveDirectoryArgs
• type SearchFilesContentArgs
• type SearchFilesContentMeta
• type Tool
  • func NewFilesystemTool(workingDir string, opts ...Opt) *Tool
  • func (t *Tool) Close() error
  • func (t *Tool) Instructions() string
  • func (t *Tool) Tools(context.Context) ([]tools.Tool, error)
• type WriteFileArgs

Constants

const (
	ToolNameReadFile           = "read_file"
	ToolNameReadMultipleFiles  = "read_multiple_files"
	ToolNameEditFile           = "edit_file"
	ToolNameWriteFile          = "write_file"
	ToolNameDirectoryTree      = "directory_tree"
	ToolNameListDirectory      = "list_directory"
	ToolNameSearchFilesContent = "search_files_content"
	ToolNameMkdir              = "create_directory"
	ToolNameRmdir              = "remove_directory"
)

Types

type CreateDirectoryArgs

type CreateDirectoryArgs struct {
	Paths []string `json:"paths" jsonschema:"Directories to create"`
}

type DirectoryTreeArgs

type DirectoryTreeArgs struct {
	Path string `json:"path" jsonschema:"Directory to traverse"`
}

type DirectoryTreeMeta

type DirectoryTreeMeta struct {
	FileCount int  `json:"fileCount"`
	DirCount  int  `json:"dirCount"`
	Truncated bool `json:"truncated"`
}

type Edit

type Edit struct {
	OldText string `json:"oldText" jsonschema:"Exact text to replace"`
	NewText string `json:"newText" jsonschema:"Replacement text"`
}

type EditFileArgs

type EditFileArgs struct {
	Path  string `json:"path" jsonschema:"File to edit"`
	Edits []Edit `json:"edits" jsonschema:"Edits to apply"`
}

func ParseEditFileArgs

func ParseEditFileArgs(data []byte) (EditFileArgs, error)

ParseEditFileArgs parses LLM-generated edit_file arguments, handling two common failure modes:

1. The outer JSON itself is malformed — typically extra closing braces/brackets or stray escape sequences caused by the model losing track of nesting depth when the text payload contains structural characters (e.g. YAML, Dockerfiles).
2. The "edits" field is double-serialized (a JSON string instead of an array).

type ListDirectoryArgs

type ListDirectoryArgs struct {
	Path string `json:"path" jsonschema:"Directory to list"`
}

type ListDirectoryMeta

type ListDirectoryMeta struct {
	Files     []string `json:"files"`
	Dirs      []string `json:"dirs"`
	Truncated bool     `json:"truncated"`
}

type Opt

type Opt func(*Tool)

func WithAllowList

func WithAllowList(roots []string) Opt

WithAllowList restricts every filesystem operation to paths that resolve under one of the supplied roots. Each entry may be:

• "." — the agent's working directory
• "~" or "~/..." — the user's home directory
• "$VAR" / "${VAR}" — an environment variable
• any absolute or relative path (relative paths are anchored at the working directory)

Symlinks are resolved before the containment check, so a symlink inside an allowed root cannot be used to escape it. An empty or nil slice disables the allow-list and preserves the default behaviour (any path is allowed).

Invalid entries (e.g. an empty string) are logged and the allow-list is silently dropped, mirroring how WithIgnoreVCS handles construction errors.

func WithDenyList

func WithDenyList(roots []string) Opt

WithDenyList forbids every filesystem operation on paths that resolve under one of the supplied roots. Tokens follow the same expansion rules as WithAllowList. The deny-list takes precedence over the allow-list: a path that matches both is rejected. An empty or nil slice disables the deny-list.

func WithIgnoreVCS

func WithIgnoreVCS(ignoreVCS bool) Opt

func WithPostEditCommands

func WithPostEditCommands(postEditCommands []PostEditConfig) Opt

type PostEditConfig

type PostEditConfig struct {
	Path string // File path pattern (glob-style)
	Cmd  string // Command to execute (with $path placeholder)
}

PostEditConfig represents a post-edit command configuration

type ReadFileArgs

type ReadFileArgs struct {
	Path string `json:"path" jsonschema:"File to read"`
}

type ReadFileMeta

type ReadFileMeta struct {
	Path      string `json:"path"`
	Content   string `json:"content"`
	LineCount int    `json:"lineCount"`
	Error     string `json:"error,omitempty"`
}

type ReadMultipleFilesArgs

type ReadMultipleFilesArgs struct {
	Paths []string `json:"paths" jsonschema:"Files to read"`
	JSON  bool     `json:"json,omitempty" jsonschema:"Return result as JSON"`
}

type ReadMultipleFilesMeta

type ReadMultipleFilesMeta struct {
	Files []ReadFileMeta `json:"files"`
}

type RemoveDirectoryArgs

type RemoveDirectoryArgs struct {
	Paths []string `json:"paths" jsonschema:"Directories to remove"`
}

type SearchFilesContentArgs

type SearchFilesContentArgs struct {
	Path            string   `json:"path" jsonschema:"Starting directory"`
	Query           string   `json:"query" jsonschema:"Text or regex to search"`
	IsRegex         bool     `json:"is_regex,omitempty" jsonschema:"Treat query as regex"`
	ExcludePatterns []string `json:"excludePatterns,omitempty" jsonschema:"Patterns to exclude"`
}

type SearchFilesContentMeta

type SearchFilesContentMeta struct {
	MatchCount int `json:"matchCount"`
	FileCount  int `json:"fileCount"`
}

type Tool

type Tool struct {
	// contains filtered or unexported fields
}

func NewFilesystemTool

func NewFilesystemTool(workingDir string, opts ...Opt) *Tool

func (*Tool) Close

func (t *Tool) Close() error

Close releases any *os.Root file descriptors held by the allow/deny lists. It is safe to call Close multiple times.

func (*Tool) Instructions

func (t *Tool) Instructions() string

func (*Tool) Tools

func (t *Tool) Tools(context.Context) ([]tools.Tool, error)

type WriteFileArgs

type WriteFileArgs struct {
	Path    string `json:"path" jsonschema:"File to write"`
	Content string `json:"content" jsonschema:"File content"`
}