chore: import upstream snapshot with attribution

python/mirage/core/ssh/__init__.py

@@ -0,0 +1,13 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========

python/mirage/core/ssh/_client.py

@@ -0,0 +1,64 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from pathlib import Path
+
+import asyncssh
+
+from mirage.types import PathSpec
+
+
+def _resolve_path(path: PathSpec) -> str:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    if isinstance(path, PathSpec):
+        return path.mount_path
+    return path
+
+
+def _key(path: str) -> str:
+    return path.lstrip("/")
+
+
+def _abs(config, path: PathSpec) -> str:
+    path = _resolve_path(path)
+    root = config.root.rstrip("/")
+    rel = _key(path)
+    if not rel:
+        return root or "/"
+    return f"{root}/{rel}"
+
+
+def _connect_kwargs(config) -> dict:
+    kwargs: dict = {"host": config.host}
+    if config.hostname:
+        kwargs["host"] = config.hostname
+    if config.port:
+        kwargs["port"] = config.port
+    if config.username:
+        kwargs["username"] = config.username
+    if config.identity_file:
+        kwargs["client_keys"] = [str(Path(config.identity_file).expanduser())]
+    if config.known_hosts is not None:
+        kwargs["known_hosts"] = config.known_hosts
+    else:
+        kwargs["known_hosts"] = None
+    kwargs["login_timeout"] = config.timeout
+    return kwargs
+
+
+async def connect(config) -> asyncssh.SSHClientConnection:
+    return await asyncssh.connect(**_connect_kwargs(config))

python/mirage/core/ssh/append.py

@@ -0,0 +1,27 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import invalidate_after_write
+from mirage.core.ssh._client import _abs
+from mirage.types import PathSpec
+
+
+async def append_bytes(accessor: SSHAccessor, path: PathSpec,
+                       data: bytes) -> None:
+    config = accessor.config
+    sftp = await accessor.sftp()
+    async with sftp.open(_abs(config, path), "ab") as f:
+        await f.write(data)
+    await invalidate_after_write(path)

python/mirage/core/ssh/constants.py

@@ -0,0 +1,16 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+SCOPE_WARN = 500
+SCOPE_ERROR = 5000

python/mirage/core/ssh/copy.py

@@ -0,0 +1,35 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import invalidate_after_write
+from mirage.core.ssh._client import _abs, _resolve_path
+from mirage.types import PathSpec
+
+
+async def copy(accessor: SSHAccessor, src: PathSpec, dst: PathSpec) -> None:
+    src = _resolve_path(src)
+    dst = _resolve_path(dst)
+    config = accessor.config
+    sftp = await accessor.sftp()
+    try:
+        async with sftp.open(_abs(config, src), "rb") as f:
+            content = await f.read()
+        async with sftp.open(_abs(config, dst), "wb") as f:
+            await f.write(content)
+    except asyncssh.SFTPNoSuchFile:
+        raise FileNotFoundError(src)
+    await invalidate_after_write(dst)

python/mirage/core/ssh/create.py

@@ -0,0 +1,26 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import invalidate_after_write
+from mirage.core.ssh._client import _abs
+from mirage.types import PathSpec
+
+
+async def create(accessor: SSHAccessor, path: PathSpec) -> None:
+    config = accessor.config
+    sftp = await accessor.sftp()
+    async with sftp.open(_abs(config, path), "wb"):
+        pass
+    await invalidate_after_write(path)

python/mirage/core/ssh/du.py

@@ -0,0 +1,97 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.core.ssh._client import _abs
+from mirage.core.ssh.stat import stat
+from mirage.types import FileType, PathSpec
+
+
+async def du(accessor: SSHAccessor, path: PathSpec) -> int:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    try:
+        info = await stat(accessor, path)
+    except FileNotFoundError:
+        info = None
+    if info is not None and info.type != FileType.DIRECTORY:
+        return info.size or 0
+    target = path.mount_path if isinstance(path, PathSpec) else path
+    config = accessor.config
+    sftp = await accessor.sftp()
+    return await _du_walk(sftp, _abs(config, target))
+
+
+async def du_all(
+    accessor: SSHAccessor,
+    path: PathSpec,
+) -> tuple[list[tuple[str, int]], int]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    try:
+        info = await stat(accessor, path)
+    except FileNotFoundError:
+        info = None
+    if info is not None and info.type != FileType.DIRECTORY:
+        return [], info.size or 0
+    target = path.mount_path if isinstance(path, PathSpec) else path
+    config = accessor.config
+    sftp = await accessor.sftp()
+    entries: list[tuple[str, int]] = []
+    total = await _du_walk_all(sftp, config, target, entries)
+    entries.sort()
+    return entries, total
+
+
+async def _du_walk(sftp, remote_path):
+    total = 0
+    try:
+        entries = await sftp.readdir(remote_path)
+    except asyncssh.SFTPNoSuchFile:
+        raise FileNotFoundError(remote_path)
+    for entry in entries:
+        if entry.filename in (".", ".."):
+            continue
+        child = f"{remote_path.rstrip('/')}/{entry.filename}"
+        if entry.attrs.type == asyncssh.FILEXFER_TYPE_DIRECTORY:
+            total += await _du_walk(sftp, child)
+        else:
+            total += entry.attrs.size or 0
+    return total
+
+
+async def _du_walk_all(sftp, config, path, results):
+    remote = _abs(config, path)
+    total = 0
+    try:
+        entries = await sftp.readdir(remote)
+    except asyncssh.SFTPNoSuchFile:
+        raise FileNotFoundError(path)
+    for entry in entries:
+        if entry.filename in (".", ".."):
+            continue
+        child = f"{path.rstrip('/')}/{entry.filename}"
+        if entry.attrs.type == asyncssh.FILEXFER_TYPE_DIRECTORY:
+            total += await _du_walk_all(sftp, config, child, results)
+        else:
+            size = entry.attrs.size or 0
+            results.append((child, size))
+            total += size
+    return total

python/mirage/core/ssh/exists.py

@@ -0,0 +1,29 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.core.ssh._client import _abs
+from mirage.types import PathSpec
+
+
+async def exists(accessor: SSHAccessor, path: PathSpec) -> bool:
+    config = accessor.config
+    sftp = await accessor.sftp()
+    try:
+        await sftp.stat(_abs(config, path))
+        return True
+    except asyncssh.SFTPNoSuchFile:
+        return False

python/mirage/core/ssh/find.py

@@ -0,0 +1,133 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.commands.builtin.find_eval import (FindEntry, PredNode, build_tree,
+                                               emit_start_path, keep,
+                                               start_basename)
+from mirage.core.ssh._client import _abs
+from mirage.types import PathSpec
+
+
+async def find(
+    accessor: SSHAccessor,
+    path: PathSpec,
+    name: str | None = None,
+    type: str | None = None,
+    min_size: int | None = None,
+    max_size: int | None = None,
+    maxdepth: int | None = None,
+    name_exclude: str | None = None,
+    or_names: list[str] | None = None,
+    mtime_min: float | None = None,
+    mtime_max: float | None = None,
+    iname: str | None = None,
+    mindepth: int | None = None,
+    path_pattern: str | None = None,
+    empty: bool = False,
+    tree: PredNode | None = None,
+) -> list[str]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    start_name = start_basename(path)
+    if isinstance(path, PathSpec):
+        path = path.mount_path
+    config = accessor.config
+    sftp = await accessor.sftp()
+    results: list[str] = []
+    tree = tree if tree is not None else build_tree(name=name,
+                                                    iname=iname,
+                                                    path_pattern=path_pattern,
+                                                    type=type,
+                                                    name_exclude=name_exclude,
+                                                    or_names=or_names)
+    if maxdepth is None or maxdepth >= 0:
+        try:
+            root_attrs = await sftp.stat(_abs(config, path))
+        except (asyncssh.SFTPError, OSError):
+            root_attrs = None
+        if root_attrs is not None:
+            is_dir = root_attrs.type == asyncssh.FILEXFER_TYPE_DIRECTORY
+            emit_start_path(results,
+                            path,
+                            start_name,
+                            kind="d" if is_dir else "f",
+                            is_empty=False if is_dir else
+                            (root_attrs.size or 0) == 0,
+                            exists=True,
+                            tree=tree,
+                            maxdepth=maxdepth,
+                            mindepth=mindepth,
+                            size=None if is_dir else (root_attrs.size or 0),
+                            min_size=min_size,
+                            max_size=max_size)
+    await _walk(sftp, config, path, results, 0, maxdepth, mindepth, tree,
+                min_size, max_size, mtime_min, mtime_max)
+    return sorted(results)
+
+
+async def _walk(sftp, config, path, results, depth, maxdepth, mindepth, tree,
+                min_size, max_size, mtime_min, mtime_max):
+    if maxdepth is not None and depth > maxdepth:
+        return
+    remote = _abs(config, path)
+    try:
+        entries = await sftp.readdir(remote)
+    except asyncssh.SFTPNoSuchFile:
+        return
+    for entry in entries:
+        if entry.filename in (".", ".."):
+            continue
+        child = f"{path.rstrip('/')}/{entry.filename}"
+        is_dir = entry.attrs.type == asyncssh.FILEXFER_TYPE_DIRECTORY
+        if _matches(entry, child, is_dir, depth + 1, maxdepth, mindepth, tree,
+                    min_size, max_size, mtime_min, mtime_max):
+            results.append(child)
+        if is_dir:
+            await _walk(sftp, config, child, results, depth + 1, maxdepth,
+                        mindepth, tree, min_size, max_size, mtime_min,
+                        mtime_max)
+
+
+def _matches(entry, path, is_dir, depth, maxdepth, mindepth, tree, min_size,
+             max_size, mtime_min, mtime_max):
+    if maxdepth is not None and depth > maxdepth:
+        return False
+    find_entry = FindEntry(key=path,
+                           name=path.rsplit("/", 1)[-1],
+                           kind="d" if is_dir else "f",
+                           depth=depth,
+                           is_empty=False if is_dir else
+                           (entry.attrs.size or 0) == 0)
+    if not keep(find_entry, tree, mindepth):
+        return False
+    if min_size is not None or max_size is not None:
+        # Directories count as size 0 for -size (deliberate GNU divergence).
+        size = 0 if is_dir else (entry.attrs.size or 0)
+        if min_size is not None and size < min_size:
+            return False
+        if max_size is not None and size > max_size:
+            return False
+    if mtime_min is not None or mtime_max is not None:
+        mtime = entry.attrs.mtime
+        if mtime is not None:
+            if mtime_min is not None and mtime < mtime_min:
+                return False
+            if mtime_max is not None and mtime > mtime_max:
+                return False
+    return True

python/mirage/core/ssh/glob.py

@@ -0,0 +1,29 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.ssh.constants import SCOPE_ERROR
+from mirage.core.ssh.readdir import readdir
+from mirage.types import PathSpec
+from mirage.utils.glob_walk import resolve_glob_with
+
+
+async def resolve_glob(
+    accessor: SSHAccessor,
+    paths: list[PathSpec],
+    index: IndexCacheStore,
+) -> list[PathSpec]:
+    return await resolve_glob_with(readdir, accessor, paths, index,
+                                   SCOPE_ERROR)

python/mirage/core/ssh/mkdir.py

@@ -0,0 +1,30 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import invalidate_after_write
+from mirage.core.ssh._client import _abs
+from mirage.types import PathSpec
+
+
+async def mkdir(accessor: SSHAccessor,
+                path: PathSpec,
+                parents: bool = False) -> None:
+    config = accessor.config
+    sftp = await accessor.sftp()
+    if parents:
+        await sftp.makedirs(_abs(config, path), exist_ok=True)
+    else:
+        await sftp.mkdir(_abs(config, path))
+    await invalidate_after_write(path)

python/mirage/core/ssh/read.py

@@ -0,0 +1,51 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import time
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.ssh._client import _abs
+from mirage.observe.context import record
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+
+
+async def read_bytes(accessor: SSHAccessor,
+                     path: PathSpec,
+                     index: IndexCacheStore = None,
+                     offset: int = 0,
+                     size: int | None = None) -> bytes:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    if isinstance(path, PathSpec):
+        path = path.mount_path
+    config = accessor.config
+    sftp = await accessor.sftp()
+    start_ms = int(time.monotonic() * 1000)
+    try:
+        remote_path = _abs(config, path)
+        async with sftp.open(remote_path, "rb") as f:
+            if offset:
+                await f.seek(offset)
+            data = await f.read(size if size is not None else -1)
+        record("read", path, "ssh", len(data), start_ms)
+        return data
+    except asyncssh.SFTPNoSuchFile:
+        raise enoent(virtual)

python/mirage/core/ssh/readdir.py

@@ -0,0 +1,79 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import logging
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.index import IndexCacheStore, IndexEntry
+from mirage.core.ssh._client import _abs
+from mirage.core.ssh.constants import SCOPE_ERROR
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.key_prefix import mount_prefix_of
+
+logger = logging.getLogger(__name__)
+
+
+async def readdir(accessor: SSHAccessor, path: PathSpec,
+                  index: IndexCacheStore) -> list[str]:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    if isinstance(path, PathSpec):
+        prefix = mount_prefix_of(path.virtual, path.resource_path)
+        path = path.directory if path.pattern else path.virtual
+    if prefix and path.startswith(prefix):
+        rest = path[len(prefix):]
+        if prefix.endswith("/") or rest == "" or rest.startswith("/"):
+            path = rest or "/"
+    config = accessor.config
+    # Canonical key: no trailing slash (except root), or the same dir
+    # indexes under two keys and cache hits return doubled-slash entries.
+    virtual_key = prefix + path if prefix else path
+    virtual_key = virtual_key.rstrip("/") or "/"
+    listing = await index.list_dir(virtual_key)
+    if listing.entries is not None:
+        return listing.entries
+    sftp = await accessor.sftp()
+    try:
+        remote_path = _abs(config, path)
+        entries = await sftp.readdir(remote_path)
+        base = "/" + path.strip("/")
+        names: list[str] = []
+        for entry in entries:
+            if entry.filename in (".", ".."):
+                continue
+            child = base.rstrip("/") + "/" + entry.filename
+            names.append(child)
+        names = sorted(names)
+        if len(names) > SCOPE_ERROR:
+            logger.warning(
+                "ssh readdir: %s returned %d entries (limit %d)",
+                virtual_key,
+                len(names),
+                SCOPE_ERROR,
+            )
+        virtual_entries = sorted((prefix + e if prefix else e) for e in names)
+        index_entries = [(e.rsplit("/", 1)[-1],
+                          IndexEntry(id=e,
+                                     name=e.rsplit("/", 1)[-1],
+                                     resource_type="file")) for e in names]
+        await index.set_dir(virtual_key, index_entries)
+        return virtual_entries
+    except asyncssh.SFTPNoSuchFile:
+        raise enoent(virtual)

python/mirage/core/ssh/rename.py

@@ -0,0 +1,34 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import (invalidate_after_unlink,
+                                  invalidate_after_write)
+from mirage.core.ssh._client import _abs, _resolve_path
+from mirage.types import PathSpec
+
+
+async def rename(accessor: SSHAccessor, src: PathSpec, dst: PathSpec) -> None:
+    src = _resolve_path(src)
+    dst = _resolve_path(dst)
+    config = accessor.config
+    sftp = await accessor.sftp()
+    try:
+        await sftp.rename(_abs(config, src), _abs(config, dst))
+    except asyncssh.SFTPNoSuchFile:
+        raise FileNotFoundError(src)
+    await invalidate_after_write(dst)
+    await invalidate_after_unlink(src)

python/mirage/core/ssh/rm.py

@@ -0,0 +1,46 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import invalidate_after_unlink
+from mirage.core.ssh._client import _abs, _resolve_path
+from mirage.types import PathSpec
+
+
+async def rm_r(accessor: SSHAccessor, path: PathSpec) -> None:
+    path = _resolve_path(path)
+    config = accessor.config
+    sftp = await accessor.sftp()
+    try:
+        await _rm_r_inner(sftp, config, path)
+    except asyncssh.SFTPNoSuchFile:
+        raise FileNotFoundError(path)
+    await invalidate_after_unlink(path)
+
+
+async def _rm_r_inner(sftp, config, path: PathSpec) -> None:
+    remote = _abs(config, path)
+    attrs = await sftp.stat(remote)
+    if attrs.type == asyncssh.FILEXFER_TYPE_DIRECTORY:
+        entries = await sftp.readdir(remote)
+        for entry in entries:
+            if entry.filename in (".", ".."):
+                continue
+            child = f"{path.rstrip('/')}/{entry.filename}"
+            await _rm_r_inner(sftp, config, child)
+        await sftp.rmdir(remote)
+    else:
+        await sftp.remove(remote)

python/mirage/core/ssh/rmdir.py

@@ -0,0 +1,30 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import invalidate_after_unlink
+from mirage.core.ssh._client import _abs
+from mirage.types import PathSpec
+
+
+async def rmdir(accessor: SSHAccessor, path: PathSpec) -> None:
+    config = accessor.config
+    sftp = await accessor.sftp()
+    try:
+        await sftp.rmdir(_abs(config, path))
+    except asyncssh.SFTPNoSuchFile:
+        raise FileNotFoundError(path)
+    await invalidate_after_unlink(path)

python/mirage/core/ssh/stat.py

@@ -0,0 +1,54 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.index import IndexCacheStore
+from mirage.core.ssh._client import _abs
+from mirage.core.timeutil import epoch_to_iso
+from mirage.types import FileStat, FileType, PathSpec
+from mirage.utils.errors import enoent
+from mirage.utils.filetype import guess_type
+
+
+async def stat(accessor: SSHAccessor,
+               path: PathSpec,
+               index: IndexCacheStore = None) -> FileStat:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    if isinstance(path, PathSpec):
+        path = path.mount_path
+    config = accessor.config
+    sftp = await accessor.sftp()
+    try:
+        remote_path = _abs(config, path)
+        attrs = await sftp.stat(remote_path)
+        is_dir = attrs.type == asyncssh.FILEXFER_TYPE_DIRECTORY
+        name = path.rstrip("/").rsplit("/", 1)[-1] or "/"
+        mod_str = ""
+        if attrs.mtime is not None:
+            mod_str = epoch_to_iso(attrs.mtime)
+        return FileStat(
+            name=name,
+            size=attrs.size or 0,
+            modified=mod_str,
+            fingerprint=mod_str or None,
+            type=FileType.DIRECTORY if is_dir else guess_type(path),
+        )
+    except asyncssh.SFTPNoSuchFile:
+        raise enoent(virtual)

python/mirage/core/ssh/stream.py

@@ -0,0 +1,58 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.core.ssh._client import _abs
+from mirage.types import PathSpec
+from mirage.utils.errors import enoent
+
+
+async def read_stream(accessor: SSHAccessor,
+                      path: PathSpec,
+                      index=None,
+                      chunk_size: int = 8192):
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    virtual = path.virtual
+    if isinstance(path, PathSpec):
+        path = path.mount_path
+    config = accessor.config
+    sftp = await accessor.sftp()
+    try:
+        remote_path = _abs(config, path)
+        async with sftp.open(remote_path, "rb") as f:
+            while True:
+                chunk = await f.read(chunk_size)
+                if not chunk:
+                    break
+                yield chunk
+    except asyncssh.SFTPNoSuchFile:
+        raise enoent(virtual)
+
+
+async def range_read(accessor: SSHAccessor, path: PathSpec, start: int,
+                     end: int) -> bytes:
+    config = accessor.config
+    sftp = await accessor.sftp()
+    try:
+        remote_path = _abs(config, path)
+        async with sftp.open(remote_path, "rb") as f:
+            await f.seek(start)
+            return await f.read(end - start)
+    except asyncssh.SFTPNoSuchFile:
+        raise enoent(path)

python/mirage/core/ssh/truncate.py

@@ -0,0 +1,27 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import invalidate_after_write
+from mirage.core.ssh._client import _abs
+from mirage.types import PathSpec
+
+
+async def truncate(accessor: SSHAccessor,
+                   path: PathSpec,
+                   length: int = 0) -> None:
+    config = accessor.config
+    sftp = await accessor.sftp()
+    await sftp.truncate(_abs(config, path), length)
+    await invalidate_after_write(path)

python/mirage/core/ssh/unlink.py

@@ -0,0 +1,30 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import asyncssh
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import invalidate_after_unlink
+from mirage.core.ssh._client import _abs
+from mirage.types import PathSpec
+
+
+async def unlink(accessor: SSHAccessor, path: PathSpec) -> None:
+    config = accessor.config
+    sftp = await accessor.sftp()
+    try:
+        await sftp.remove(_abs(config, path))
+    except asyncssh.SFTPNoSuchFile:
+        raise FileNotFoundError(path)
+    await invalidate_after_unlink(path)

python/mirage/core/ssh/write.py

@@ -0,0 +1,39 @@
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import time
+
+from mirage.accessor.ssh import SSHAccessor
+from mirage.cache.context import invalidate_after_write
+from mirage.core.ssh._client import _abs
+from mirage.observe.context import record
+from mirage.types import PathSpec
+
+
+async def write_bytes(accessor: SSHAccessor, path: PathSpec,
+                      data: bytes) -> None:
+    if isinstance(path, str):
+        path = PathSpec(virtual=path,
+                        directory=path,
+                        resource_path=path.strip("/"))
+    if isinstance(path, PathSpec):
+        path = path.mount_path
+    config = accessor.config
+    sftp = await accessor.sftp()
+    start_ms = int(time.monotonic() * 1000)
+    remote_path = _abs(config, path)
+    async with sftp.open(remote_path, "wb") as f:
+        await f.write(data)
+    record("write", path, "ssh", len(data), start_ms)
+    await invalidate_after_write(path)