Documentation
¶
Index ¶
- Variables
- func AgentEffectiveCwdFromContext(ctx context.Context) string
- func CreateTempFile(dir, pattern string) (*os.File, error)
- func EnsureDir(dir string) error
- func FileExists(filename string) bool
- func FilesExist(filenames ...string) (bool, error)
- func IsHomeDir(path string) bool
- func IsSensitiveSystemPath(path string) bool
- func IsSkipDir(name string) bool
- func IsUnderTmpPath(path string) bool
- func ReadFile(filename string) (string, error)
- func ReadFileBytes(path string) ([]byte, error)
- func SafeResolvePath(filePath string) (string, error)
- func SafeResolvePathForWrite(filePath string) (string, error)
- func SafeResolvePathForWriteWithBypass(ctx context.Context, filePath string) (string, error)
- func SafeResolvePathWithBypass(ctx context.Context, filePath string) (string, error)
- func SaveFile(filename, content string) error
- func SecurityBypassEnabled(ctx context.Context) bool
- func SessionAllowedFoldersFromContext(ctx context.Context) []string
- func WithAgentContext(ctx context.Context, effectiveCwd string, sessionFolders []string) context.Context
- func WithAuditLogger(ctx context.Context, logger AuditLogger) context.Context
- func WithEffectiveCwd(ctx context.Context, effectiveCwd string) context.Context
- func WithSecurityBypass(ctx context.Context) context.Context
- func WithSessionAllowedFolders(ctx context.Context, folders []string) context.Context
- func WithWorkspaceRoot(ctx context.Context, workspaceRoot string) context.Context
- func WorkspaceRootFromContext(ctx context.Context) string
- func WriteFileWithDir(path string, data []byte, perm os.FileMode) error
- type AuditEntry
- type AuditLogger
Constants ¶
This section is empty.
Variables ¶
var ErrOutsideWorkingDirectory = errors.New("file access outside working directory")
ErrOutsideWorkingDirectory is returned when a path is outside the working directory This should be caught by tool handlers to prompt the user for confirmation
var ErrWriteOutsideWorkingDirectory = errors.New("file write outside working directory")
ErrWriteOutsideWorkingDirectory is returned when a write path is outside the working directory
var SkipDirs = map[string]bool{ "node_modules": true, "vendor": true, "Pods": true, "Carthage": true, "bower_components": true, ".git": true, ".hg": true, ".svn": true, ".npm": true, ".yarn": true, ".pnp": true, "__pycache__": true, ".tox": true, ".venv": true, "venv": true, "env": true, ".env": true, ".direnv": true, "eggs": true, ".eggs": true, ".next": true, ".nuxt": true, ".turbo": true, "coverage": true, ".nyc_output": true, ".cache": true, ".parcel-cache": true, ".expo": true, "test-results": true, ".gradle": true, ".mvn": true, ".kotlin": true, ".cxx": true, "DerivedData": true, "dist": true, "build": true, "out": true, "target": true, ".build": true, "storybook-static": true, ".storybook": true, ".idea": true, ".vscode": true, ".vs": true, ".fleet": true, ".terraform": true, ".cargo": true, ".agent-i": true, ".sprout": true, }
SkipDirs is the canonical list of directory names that should be excluded from directory walks across all tools — embedding index builds, codegraph indexing, repo_map generation, and search_files.
Every package that walks a directory tree MUST consult this list so the exclusion behavior is consistent. Keeping it in one place prevents the three-way drift that previously caused codegraph and repo_map to walk 245K files (mostly node_modules/.cxx/Pods) on large repos.
Categories:
- Package managers: node_modules, vendor, Pods, Carthage, bower_components
- Version control: .git, .hg, .svn, .npm, .yarn, .pnp
- Python: __pycache__, .tox, .venv, venv, env, .env, .direnv
- JS/Node build: .next, .nuxt, .turbo, coverage, .cache, .parcel-cache
- Java/Kotlin: .gradle, .mvn, .kotlin
- iOS/Android native: .cxx, DerivedData
- Build artifacts: dist, build, out, target, .build, storybook-static
- IDE: .idea, .vscode, .vs, .fleet
- Terraform: .terraform
- Sprout: .agent-i, .sprout
Functions ¶
func AgentEffectiveCwdFromContext ¶ added in v0.17.7
AgentEffectiveCwdFromContext returns the agent's effective working directory carried on ctx, if any.
func CreateTempFile ¶
CreateTempFile creates a temporary file
func FileExists ¶
FileExists checks if a file exists at the given path
func FilesExist ¶
FilesExist checks if all the given files exist
func IsHomeDir ¶ added in v0.16.25
IsHomeDir reports whether path is the current user's home directory. Both paths are resolved through symlinks so that, e.g., /var/folders/... and /Users/alanp compare correctly on macOS.
Symlink resolution is bounded by symlinkTimeout so a hanging network mount (NFS, SMB) cannot stall index builds indefinitely.
func IsSensitiveSystemPath ¶ added in v0.17.7
IsSensitiveSystemPath reports whether path targets a known sensitive system location that should always prompt the user rather than auto-allowing. Covers: /etc/* passwd/shadow/sudoers, SSH private keys and config, AWS credentials, GPG keyrings, Kubernetes, Docker, GCP, and Azure configs.
func IsSkipDir ¶ added in v0.17.10
IsSkipDir reports whether the given directory name should be excluded from directory walks. This is the single function all walkers should call.
func IsUnderTmpPath ¶ added in v0.17.7
IsUnderTmpPath is the exported wrapper around isInTmpPath. It reports whether path is within the OS temp directory. SP-127 M1: used by the Gate 1 path-tier classifier to allow /tmp unconditionally.
func ReadFileBytes ¶
ReadFileBytes reads file as bytes
func SafeResolvePath ¶
SafeResolvePath validates and resolves a file path, checking for path traversal while allowing symlinks that stay within the working directory.
Returns the resolved absolute path if it's safe to access, or an error otherwise.
func SafeResolvePathForWrite ¶
SafeResolvePathForWrite validates a file path for writing, checking that the parent directory is safe to access. This allows writing to new files that don't exist yet while still preventing path traversal attacks.
Returns the absolute path if it's safe to write, or an error otherwise.
func SafeResolvePathForWriteWithBypass ¶
SafeResolvePathForWriteWithBypass validates a file path for writing with optional bypass. This allows writing to new files that don't exist yet while still preventing path traversal attacks. When security bypass is enabled via context, writes outside the working directory are allowed.
Returns the absolute path if it's safe to write, or an error otherwise.
func SafeResolvePathWithBypass ¶
SafeResolvePathWithBypass validates a file path for reading, checking that it's within the working directory and handling symlinks properly. Optional bypass can be enabled via context when user has explicitly approved the operation.
func SaveFile ¶
SaveFile saves or removes a file with the given content. If content is empty, the file is removed.
func SecurityBypassEnabled ¶
SecurityBypassEnabled reports whether the context carries an explicit filesystem security bypass approval.
func SessionAllowedFoldersFromContext ¶ added in v0.17.7
SessionAllowedFoldersFromContext returns the session-allowlisted folders carried on ctx, if any.
func WithAgentContext ¶ added in v0.17.7
func WithAgentContext(ctx context.Context, effectiveCwd string, sessionFolders []string) context.Context
WithAgentContext is a convenience helper that stores both the agent's effective working directory and session-allowlisted folders on the context. This combines WithEffectiveCwd and WithSessionAllowedFolders in one call.
func WithAuditLogger ¶ added in v0.17.7
func WithAuditLogger(ctx context.Context, logger AuditLogger) context.Context
WithAuditLogger stores an audit logger on the context for filesystem gate decision logging. This is used by SP-127 Phase 2.6 to emit audit entries for filesystem path resolution decisions.
func WithEffectiveCwd ¶ added in v0.17.7
WithEffectiveCwd stores the agent's effective working directory (shell cwd) on the context for filesystem path resolution.
func WithSecurityBypass ¶
WithSecurityBypass marks a context as having explicit user approval for file access outside the workspace root.
func WithSessionAllowedFolders ¶ added in v0.17.7
WithSessionAllowedFolders stores the session-allowlisted folders on the context for filesystem path resolution. These are workflow-declared allowed_paths plus folders the user approved mid-session.
func WithWorkspaceRoot ¶
WithWorkspaceRoot stores an explicit workspace root on the context so file and process operations do not depend on the process-global cwd.
func WorkspaceRootFromContext ¶
WorkspaceRootFromContext returns the explicit workspace root carried on ctx, if any.
Types ¶
type AuditEntry ¶ added in v0.17.7
type AuditEntry struct {
Timestamp time.Time `json:"timestamp"`
Tool string `json:"tool"`
Args string `json:"args,omitempty"`
RiskLevel string `json:"risk_level"`
Category string `json:"category"`
Action string `json:"action"`
Reasoning string `json:"reasoning,omitempty"`
Source string `json:"source,omitempty"`
SessionID string `json:"session_id,omitempty"`
Workspace string `json:"workspace,omitempty"`
}
AuditEntry represents a single filesystem gate audit log entry. This is a local definition to avoid import cycles - the fields must match pkg/agent_tools.AuditEntry for compatibility.
type AuditLogger ¶ added in v0.17.7
AuditLogger is an interface for security audit logging. This allows the filesystem package to accept any audit logger implementation (e.g., *tools.AuditLogger from pkg/agent_tools) without importing that package, avoiding import cycles with packages that depend on filesystem.
func AuditLoggerFromContext ¶ added in v0.17.7
func AuditLoggerFromContext(ctx context.Context) AuditLogger
AuditLoggerFromContext returns the audit logger carried on ctx, if any.
Source Files