filesystem

Emit a deprecation warning with caller-controlled stack attribution.

langchain_core.warn_deprecated formats a standard message but hardcodes stacklevel=4 in its internal warnings.warn call. That value targets a decorator-wrapped frame layout; when called directly from a deprecated method's body the warning is attributed one frame too high (above the user's call site). This wrapper captures the formatted upstream warning and re-emits it with an explicit stacklevel, so the warning points at the user's call site.

Check whether a backend class's execute accepts a timeout kwarg.

Older backend packages didn't lower-bound their SDK dependency, so they may not accept the timeout keyword added to SandboxBackendProtocol.

Results are cached per class to avoid repeated introspection overhead.

Check if content is empty and return warning message.

Format file content with line numbers (cat -n style).

Chunks lines longer than MAX_LINE_LENGTH with continuation markers (e.g., 5.1, 5.2).

Format structured grep matches using existing formatting logic.

Sanitize tool_call_id to prevent path traversal and separator issues.

Replaces dangerous characters (., /, ) with underscores.

Truncate list or string result if it exceeds token limit (rough estimate: 4 chars/token).

Validate and normalize file path for security.

Ensures paths are safe to use by preventing directory traversal attacks and enforcing consistent formatting. All paths are normalized to use forward slashes and start with a leading slash.

This function is designed for virtual filesystem paths and rejects Windows absolute paths (e.g., C:/..., F:/...) to maintain consistency and prevent path format ambiguity.

Append text to a system message.

Check if a backend supports command execution.

For CompositeBackend, checks if the default backend supports execution. For other backends, checks if they implement SandboxBackendProtocol.

Routes file operations to different backends by path prefix.

Matches paths against route prefixes (longest first) and delegates to the corresponding backend. Unmatched paths use the default backend.

Backend that stores files in agent state (ephemeral).

Uses LangGraph's state management and checkpointing. Files persist within a conversation thread but not across threads. State is automatically checkpointed after each agent step.

Reads and writes go through LangGraph's CONFIG_KEY_READ / CONFIG_KEY_SEND so that state updates are queued as proper channel writes rather than returned as files_update dicts.

Result from backend edit operations.

Data structure for storing file contents with metadata.

Structured file listing info.

Minimal contract used across backends. Only path is required. Other fields are best-effort and may be absent depending on backend.

A single match from a grep search.

Result from backend read operations.

Extension of BackendProtocol that adds shell command execution.

Designed for backends running in isolated environments (containers, VMs, remote hosts).

Adds execute()/aexecute() for shell commands and an id property.

See BaseSandbox for a base class that implements all inherited file operations by delegating to execute().

Result from backend write operations.

A single access rule for filesystem operations.

State for the filesystem middleware.

Input schema for the ls tool.

Input schema for the read_file tool.

Input schema for the write_file tool.

Input schema for the edit_file tool.

Input schema for the glob tool.

Input schema for the grep tool.

Input schema for the execute tool.

Middleware for providing filesystem and optional execution tools to an agent.

This middleware adds filesystem tools to the agent: ls, read_file, write_file, edit_file, glob, and grep.

Files can be stored using any backend that implements the BackendProtocol.

If the backend implements SandboxBackendProtocol, an execute tool is also added for running shell commands.

This middleware also automatically evicts large tool results to the file system when they exceed a token threshold, preventing context window saturation.

Protocol for pluggable memory backends (single, unified).

Backends can store files in different locations (state, filesystem, database, etc.) and provide a uniform interface for file operations.

All file data is represented as dicts with the following structure:

{
    "content": str,  # Text content (utf-8) or base64-encoded binary
    "encoding": str,  # "utf-8" for text, "base64" for binary data
    "created_at": str,  # ISO format timestamp
    "modified_at": str,  # ISO format timestamp
}