utils

Classification of a file by extension.

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.

Sanitize tool_call_id to prevent path traversal and separator issues.

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

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).

Check if content is empty and return warning message.

Convert FileData to plain string content.

Create a FileData object with timestamps.

Update FileData with new content, preserving creation timestamp.

Slice file data to the requested line range without formatting.

Returns raw text for the requested window. Line-number formatting is applied downstream by the middleware layer.

Perform string replacement with occurrence validation.

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

Normalize backslash separators to forward slashes for PurePosixPath use.

Backends running on Windows return OS-native paths using backslashes. PurePosixPath treats backslashes as literal filename characters, so PurePosixPath(r"C:\a\b").name yields the full string instead of "b". Normalize before constructing a PurePosixPath.

This is best-effort: a POSIX directory literally named with a backslash will also be rewritten. That trade-off is accepted because such filenames are vanishingly rare in practice and the alternative (gating on os.sep) fails when a Windows-style path is handed to a non-Windows process.

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.

Return structured grep matches from an in-memory files mapping.

Performs literal text search (not regex).

Returns a GrepResult with matches on success.

We deliberately do not raise here to keep backends non-throwing in tool contexts and preserve user-facing error messages.

Group structured matches into the legacy dict form used by formatters.

Format structured grep matches using existing formatting logic.

Data structure for storing file contents with metadata.

Result from backend grep operations.

Result from backend read operations.