"""Filesystem helpers for Agent Flows Builder.

DeepAgents' FilesystemMiddleware now supplies the `read_file` tool using the configured backend.
Our hybrid backend routes scratchpad files to the in-state `StateBackend` and documentation files
under `/docs/` to the real filesystem via `FilesystemBackend`. The shim here keeps the legacy
`read_file` name available and documents the behavior, but delegates directly to the workspace
filesystem; the middleware-managed `read_file` should be used in practice.
"""

from pathlib import Path

from deepagents.backends import CompositeBackend, FilesystemBackend, StateBackend


def create_composite_backend(root_workspace: Path, runtime) -> CompositeBackend:
    """Create hybrid backend routing scratchpad to state and docs to real filesystem.

    The `/docs/` route roots the filesystem backend at `<workspace>/docs` so agent paths like
    `/docs/foo.md` resolve to the bundled documentation directory only.
    """
    return CompositeBackend(
        default=StateBackend(runtime),
        routes={
            "/docs/": FilesystemBackend(
                root_dir=root_workspace / "docs",
                virtual_mode=True,
            ),
        },
    )
