Shared utility functions for memory backend implementations.
This module contains both user-facing string formatters and structured helpers used by backends and the composite router. Structured helpers enable composition without fragile string parsing.
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.
Format file data for read response with line numbers.
Perform string replacement with occurrence validation.
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.
Return structured grep matches from an in-memory files mapping.
Performs literal text search (not regex).
Returns a list of GrepMatch on success, or a string for invalid inputs. 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.
