utils

Maximum raw video payload size accepted by read_file frame extraction.

Classification of a file by extension.

Compile a grep include-glob into a matcher with ripgrep-like semantics.

Provides one shared include-glob behavior for every backend so the same grep(..., glob=...) call closely mirrors ripgrep for common include patterns, whether or not ripgrep is installed:

• Patterns without a / match the basename at any depth.

  Example: *.py matches src/app/main.py.

• Patterns containing a / match the path relative to the grep search root, with ** support.

  Example: src/**/*.py matches src/app/main.py.

• A leading / anchors the pattern to the search root; it narrows the match rather than widening it.

  Example: /*.py matches top.py but not src/app/main.py.

Exclusion/negation patterns (a leading !) are not supported: the ! is treated literally rather than inverting the match, so results for such patterns can diverge from rg --glob '!...'.

Compile a glob pattern into a per-entry matcher for a recursive walk.

Path.rglob(pattern) is equivalent to Path.glob("**/" + pattern), so the pattern matches at any depth (e.g. *.py matches src/app/main.py). Prefix the pattern with **/ and compile it with globstar support so a matcher can be applied to each visited entry while walking the tree, letting the caller enforce a deadline on every entry instead of only on matched paths.

Depth (GLOBSTAR) and dotfile matching (DOTMATCH) mirror Path.rglob: DOTMATCH is required because wcmatch excludes dotfiles by default whereas stdlib rglob includes them. Brace expansion (BRACE) is an intentional divergence from rglob — {a,b}.py expands here but Path.rglob treats the braces literally — chosen so glob matches the include-glob semantics of compile_grep_include_glob.

Sanitize tool_call_id to prevent path traversal and separator issues.

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

Format file content with line numbers.

Chunks lines longer than MAX_LINE_LENGTH with continuation markers (e.g., 5.1, 5.2). Line markers are separated from source content with two spaces so source tabs cannot be confused with a gutter separator.

Check if content is empty and return warning message.

Convert current or legacy persisted file content to a string.

Create a FileData object with timestamps.

Update FileData with new content, preserving creation timestamp.

Floor a requested read window at a zero offset and zero lines.

Models occasionally emit degenerate read_file arguments (offset=-1, limit=0). Clamping offset keeps backends from reporting a line range that starts before line 1, which ReadResult rejects.

Clamping limit is not sufficient on its own: flooring a negative limit at 0 produces a zero-length window, which still has no valid start_line/end_line pair. Callers must additionally treat a returned limit of 0 as an empty read — see slice_read_response below, or the equivalent short-circuits in the sandbox and LangSmith backends, which flag the result with ReadResult.no_lines_requested.

The int() coercion is deliberate and load-bearing, not redundant with the annotations: offset and limit originate from model-supplied tool arguments, and the sandbox backend interpolates them into the source of a script it executes (_READ_COMMAND_TEMPLATE). Do not remove it.

Slice file data to the requested line range without formatting.

The returned ReadResult carries the raw (unformatted) window in file_data; 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. When max_count is set, at most that many matches are returned; if more exist the scan stops and the result is flagged truncated=True. Exactly max_count matches with none dropped is reported complete (truncated=False).

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.

Return a hint when a pattern looks like an (unsupported) regex.

grep matches literal text, so regex metacharacters are searched verbatim and silently miss. Callers gate this on a no-match result; the function itself only inspects the pattern.

Data structure for storing file contents with metadata.

Result from backend grep operations.

Result from backend read operations.