permissions

Operation type for filesystem permission rules.

• read: covers ls, read_file, glob, grep
• write: covers write_file, edit_file

Format structured grep matches using existing formatting logic.

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.

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.

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
}

Result from backend glob operations.

Result from backend grep operations.

Result from backend ls operations.

A single access rule for filesystem operations.

Rules are evaluated in declaration order. The first matching rule's mode is applied. If no rule matches, the call is allowed (permissive default).