Skip to content

Self-improving AI Employees for everyone

39.0 KB
Raw Blame
"""Native workspace filesystem backend shared by filesystem plugins.

Filesystem operations use virtual POSIX paths rooted at the workflow
workspace. Resolution follows existing symlinks, then verifies that the
resolved target remains below that root. Shell execution retains the
historical host-shell behavior and uses Nushell when it is available.
"""

from __future__ import annotations

import asyncio
import base64
import fnmatch
import os
import posixpath
import re
import shutil
import stat
import subprocess
import tempfile
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path, PurePosixPath, PureWindowsPath
from typing import Any, Callable, Dict, Final, Optional
from uuid import uuid4
from weakref import WeakValueDictionary

from services.process_environment import without_onepassword_environment


EMPTY_CONTENT_WARNING = "System reminder: File exists but has empty contents"


@dataclass
class ExecuteResponse:
    output: str
    exit_code: Optional[int] = None
    truncated: bool = False


@dataclass
class ReadResult:
    error: Optional[str] = None
    file_data: Optional[Dict[str, Any]] = None


_path_locks: WeakValueDictionary[str, asyncio.Lock] = WeakValueDictionary()


def get_path_lock(path: os.PathLike[str] | str) -> asyncio.Lock:
    """Return the process-local lock for one resolved workspace path."""
    key = os.path.normcase(os.path.abspath(os.fspath(path)))
    lock = _path_locks.get(key)
    if lock is None:
        lock = asyncio.Lock()
        _path_locks[key] = lock
    return lock


async def run_sync_until_complete(
    func: Callable[..., Any],
    /,
    *args: Any,
    **kwargs: Any,
) -> Any:
    """Run sync filesystem work without abandoning it on cancellation."""
    worker = asyncio.create_task(asyncio.to_thread(func, *args, **kwargs))
    cancellation: Optional[asyncio.CancelledError] = None

    while not worker.done():
        try:
            await asyncio.shield(worker)
        except asyncio.CancelledError as exc:
            cancellation = cancellation or exc
        except BaseException:
            break

    if cancellation is not None:
        if not worker.cancelled():
            try:
                worker.result()
            except BaseException:
                pass
        raise cancellation
    return worker.result()


def _file_identity(status: os.stat_result) -> tuple[int, int]:
    return int(status.st_dev), int(status.st_ino)


def _is_reparse_point(status: os.stat_result) -> bool:
    attributes = int(getattr(status, "st_file_attributes", 0))
    reparse_flag = int(getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0))
    return stat.S_ISLNK(status.st_mode) or bool(attributes & reparse_flag)


def _anchored_write_supported() -> bool:
    return (
        os.name != "nt"
        and hasattr(os, "O_DIRECTORY")
        and os.open in os.supports_dir_fd
        and os.mkdir in os.supports_dir_fd
        and os.rename in os.supports_dir_fd
        and os.stat in os.supports_dir_fd
        and os.unlink in os.supports_dir_fd
    )


def _open_posix_directory(
    root: Path,
    components: tuple[str, ...],
    *,
    create: bool,
) -> int:
    flags = (
        os.O_RDONLY
        | os.O_DIRECTORY
        | getattr(os, "O_NOFOLLOW", 0)
        | getattr(os, "O_CLOEXEC", 0)
    )
    directory_fd = os.open(root, flags)
    try:
        for component in components:
            try:
                next_fd = os.open(
                    component,
                    flags,
                    dir_fd=directory_fd,
                )
            except FileNotFoundError:
                if not create:
                    raise
                os.mkdir(component, mode=0o777, dir_fd=directory_fd)
                next_fd = os.open(
                    component,
                    flags,
                    dir_fd=directory_fd,
                )
            os.close(directory_fd)
            directory_fd = next_fd
        return directory_fd
    except BaseException:
        os.close(directory_fd)
        raise


def _verify_posix_directory(
    root: Path,
    components: tuple[str, ...],
    expected_fd: int,
) -> None:
    current_fd = _open_posix_directory(root, components, create=False)
    try:
        if _file_identity(os.fstat(current_fd)) != _file_identity(
            os.fstat(expected_fd)
        ):
            raise ValueError(
                "Workspace parent directory changed during atomic write"
            )
    finally:
        os.close(current_fd)


def _write_payload_to_fd(
    file_fd: int,
    payload: str | bytes,
    existing_mode: Optional[int],
) -> None:
    """Write ``payload`` to an already-opened fd, then fsync.

    Accepts ``str`` (UTF-8, newline-preserving) or ``bytes``. The binary
    branch exists so generated media — audio from a TTS provider, an
    uploaded clip — reaches disk through the same anchored-write path that
    refuses to follow a mutable symlink or Windows junction. Those bytes
    are later served over HTTP, so the containment matters more than for
    ordinary text writes.
    """
    if isinstance(payload, bytes):
        mode, kwargs = "wb", {}
    else:
        mode, kwargs = "w", {"encoding": "utf-8", "newline": ""}
    with os.fdopen(file_fd, mode, **kwargs) as handle:
        handle.write(payload)
        handle.flush()
        os.fsync(handle.fileno())
        if existing_mode is not None and hasattr(os, "fchmod"):
            os.fchmod(handle.fileno(), existing_mode)


def _replace_posix_entry(
    temporary_name: str,
    target_name: str,
    parent_fd: int,
) -> None:
    os.rename(
        temporary_name,
        target_name,
        src_dir_fd=parent_fd,
        dst_dir_fd=parent_fd,
    )


def _atomic_write_posix(
    root: Path,
    relative: Path,
    payload: str | bytes,
) -> None:
    parent_components = tuple(relative.parts[:-1])
    target_name = relative.parts[-1]
    parent_fd = _open_posix_directory(
        root,
        parent_components,
        create=True,
    )
    temporary_name: Optional[str] = None
    try:
        existing_mode: Optional[int] = None
        try:
            target_status = os.stat(
                target_name,
                dir_fd=parent_fd,
                follow_symlinks=False,
            )
        except FileNotFoundError:
            pass
        else:
            if _is_reparse_point(target_status):
                raise ValueError(
                    f"Refusing to replace symlink target '{relative.as_posix()}'"
                )
            if stat.S_ISDIR(target_status.st_mode):
                raise IsADirectoryError(
                    f"Cannot write to {relative.as_posix()}: path is a directory"
                )
            if not stat.S_ISREG(target_status.st_mode):
                raise ValueError(
                    f"Refusing to replace non-regular file "
                    f"'{relative.as_posix()}'"
                )
            existing_mode = stat.S_IMODE(target_status.st_mode)

        temporary_fd: Optional[int] = None
        for _ in range(16):
            candidate = f".opencompany-write-{uuid4().hex}"
            try:
                temporary_fd = os.open(
                    candidate,
                    (
                        os.O_WRONLY
                        | os.O_CREAT
                        | os.O_EXCL
                        | getattr(os, "O_NOFOLLOW", 0)
                        | getattr(os, "O_CLOEXEC", 0)
                    ),
                    0o600,
                    dir_fd=parent_fd,
                )
            except FileExistsError:
                continue
            temporary_name = candidate
            break
        if temporary_fd is None or temporary_name is None:
            raise FileExistsError(
                "Could not allocate a unique atomic-write temporary file"
            )

        _write_payload_to_fd(temporary_fd, payload, existing_mode)
        _verify_posix_directory(root, parent_components, parent_fd)
        _replace_posix_entry(
            temporary_name,
            target_name,
            parent_fd,
        )
        temporary_name = None
        try:
            os.fsync(parent_fd)
        except OSError:
            pass
        _verify_posix_directory(root, parent_components, parent_fd)
    finally:
        if temporary_name is not None:
            try:
                os.unlink(temporary_name, dir_fd=parent_fd)
            except OSError:
                pass
        os.close(parent_fd)


def _windows_parent_snapshot(
    root: Path,
    components: tuple[str, ...],
    *,
    create: bool,
) -> tuple[Path, tuple[tuple[int, int], ...]]:
    current = root
    identities: list[tuple[int, int]] = []
    for index, component in enumerate(("", *components)):
        if index:
            current = current / component
            try:
                status = os.stat(current, follow_symlinks=False)
            except FileNotFoundError:
                if not create:
                    raise
                os.mkdir(current)
                status = os.stat(current, follow_symlinks=False)
        else:
            status = os.stat(current, follow_symlinks=False)

        if _is_reparse_point(status):
            raise ValueError(
                f"Workspace path contains a symlink or junction: {current}"
            )
        if not stat.S_ISDIR(status.st_mode):
            raise NotADirectoryError(
                f"Workspace parent component is not a directory: {current}"
            )
        identities.append(_file_identity(status))

    try:
        current.resolve(strict=True).relative_to(root)
    except (OSError, RuntimeError, ValueError) as exc:
        raise ValueError(
            f"Workspace parent resolves outside root: {current}"
        ) from exc
    return current, tuple(identities)


def _verify_windows_temp(
    temporary: Path,
    expected_identity: tuple[int, int],
) -> None:
    status = os.stat(temporary, follow_symlinks=False)
    if _is_reparse_point(status) or _file_identity(status) != expected_identity:
        raise ValueError(
            "Atomic-write temporary file changed before replacement"
        )


def _atomic_write_windows(
    root: Path,
    relative: Path,
    payload: str | bytes,
) -> None:
    """Best-effort contained atomic replacement for Windows.

    Python exposes no Windows equivalent of POSIX ``dir_fd``-relative rename.
    This path rejects every observed reparse component and compares parent and
    temporary-file identities immediately before and after ``os.replace``.
    A hostile process that can swap the parent between a check and a path-based
    ``mkdir``/temporary-file operation can cause an empty directory or
    temporary file to be created outside the workspace; payload bytes are not
    written until the temporary identity is revalidated. A swap in the final
    identity-check-to-``os.replace`` interval can redirect the completed
    replacement; the post-check detects that event but cannot safely roll it
    back. Python's standard library exposes no handle-relative Windows rename
    primitive that closes these intervals.
    """

    components = tuple(relative.parts[:-1])
    parent, parent_snapshot = _windows_parent_snapshot(
        root,
        components,
        create=True,
    )
    target = parent / relative.parts[-1]
    existing_mode: Optional[int] = None
    try:
        target_status = os.stat(target, follow_symlinks=False)
    except FileNotFoundError:
        pass
    else:
        if _is_reparse_point(target_status):
            raise ValueError(
                f"Refusing to replace symlink or junction target "
                f"'{relative.as_posix()}'"
            )
        if stat.S_ISDIR(target_status.st_mode):
            raise IsADirectoryError(
                f"Cannot write to {relative.as_posix()}: path is a directory"
            )
        if not stat.S_ISREG(target_status.st_mode):
            raise ValueError(
                f"Refusing to replace non-regular file "
                f"'{relative.as_posix()}'"
            )
        existing_mode = stat.S_IMODE(target_status.st_mode)

    temporary_fd, temporary_text = tempfile.mkstemp(
        prefix=".opencompany-write-",
        dir=parent,
    )
    temporary = Path(temporary_text)
    temporary_identity = _file_identity(os.fstat(temporary_fd))
    replaced = False
    try:
        current_parent, current_snapshot = _windows_parent_snapshot(
            root,
            components,
            create=False,
        )
        if current_parent != parent or current_snapshot != parent_snapshot:
            raise ValueError(
                "Workspace parent directory changed during atomic write"
            )
        _verify_windows_temp(temporary, temporary_identity)

        write_fd = temporary_fd
        temporary_fd = -1
        _write_payload_to_fd(write_fd, payload, existing_mode)
        if existing_mode is not None:
            # Windows has no ``os.fchmod``. Apply its supported mode bits
            # (notably the read-only flag) to the still-private temporary
            # entry, then revalidate that entry below before replacement.
            os.chmod(temporary, existing_mode)

        current_parent, current_snapshot = _windows_parent_snapshot(
            root,
            components,
            create=False,
        )
        if current_parent != parent or current_snapshot != parent_snapshot:
            raise ValueError(
                "Workspace parent directory changed during atomic write"
            )
        _verify_windows_temp(temporary, temporary_identity)
        try:
            current_target = os.stat(target, follow_symlinks=False)
        except FileNotFoundError:
            current_target = None
        if current_target is not None and _is_reparse_point(current_target):
            raise ValueError(
                "Atomic-write target became a symlink or junction"
            )

        os.replace(temporary, target)
        replaced = True

        current_parent, current_snapshot = _windows_parent_snapshot(
            root,
            components,
            create=False,
        )
        if current_parent != parent or current_snapshot != parent_snapshot:
            raise ValueError(
                "Workspace parent directory changed during atomic replacement"
            )
        replaced_status = os.stat(target, follow_symlinks=False)
        if (
            _is_reparse_point(replaced_status)
            or _file_identity(replaced_status) != temporary_identity
        ):
            raise ValueError(
                "Atomic-write target identity changed during replacement"
            )
    finally:
        if temporary_fd >= 0:
            os.close(temporary_fd)
        if not replaced:
            try:
                current_parent, current_snapshot = _windows_parent_snapshot(
                    root,
                    components,
                    create=False,
                )
                if (
                    current_parent == parent
                    and current_snapshot == parent_snapshot
                ):
                    _verify_windows_temp(temporary, temporary_identity)
                    os.unlink(temporary)
            except (OSError, RuntimeError, ValueError):
                pass


def _atomic_write(
    path: os.PathLike[str] | str,
    payload: str | bytes,
    root_dir: os.PathLike[str] | str | None,
) -> None:
    target = Path(os.path.abspath(os.fspath(path)))
    root = Path(
        os.path.abspath(
            os.fspath(root_dir) if root_dir is not None else target.parent
        )
    )
    try:
        relative = target.relative_to(root)
    except ValueError as exc:
        raise ValueError(
            f"Write target '{target}' is outside workspace root '{root}'"
        ) from exc
    if not relative.parts:
        raise IsADirectoryError(f"Cannot replace workspace root: {target}")

    if _anchored_write_supported():
        _atomic_write_posix(root, relative, payload)
    else:
        _atomic_write_windows(root, relative, payload)


def atomic_write_text(
    path: os.PathLike[str] | str,
    content: str,
    *,
    root_dir: os.PathLike[str] | str | None = None,
) -> None:
    """Atomically replace UTF-8 text without traversing mutable symlinks.

    Production callers pass the workspace root. The optional default keeps
    direct helper callers compatible by treating the existing parent as the
    root, but it does not establish a broader containment boundary.
    """
    _atomic_write(path, content, root_dir)


def atomic_write_bytes(
    path: os.PathLike[str] | str,
    payload: bytes,
    *,
    root_dir: os.PathLike[str] | str | None = None,
) -> None:
    """Atomically replace binary content, with the same containment rules.

    Used by ``services.media`` for generated and uploaded audio. Atomicity
    is load-bearing here rather than merely tidy: the frontend renders an
    ``<audio src>`` the moment it sees a reference, so a half-written file
    is a broken player, and Temporal retries a synthesis activity against
    the *same* target path.
    """
    _atomic_write(path, payload, root_dir)


# Everything except NUL, C0 controls and DEL, bounded to a conventional
# PATH_MAX. Deliberately permissive about the rest -- workspace files are
# named by users, by ``fileDownloader`` and by ``shell``, so spaces,
# parentheses and non-ASCII are all legitimate and must keep working.
#
# The characters it does refuse are worth refusing on their own merits: a NUL
# truncates the path in any C-level filesystem call, and CR/LF or terminal
# escapes embedded in a filename corrupt every log line and console that
# later prints it.
#
# It does NOT satisfy CodeQL's ``py/path-injection``, and that was checked
# rather than assumed: the sink it flags is the ``candidate.resolve()`` call
# below, so nothing placed after it can clear the taint, and a ``fullmatch``
# in this helper is not treated as a barrier for it either. That rule is
# dismissed on this function -- see CLAUDE.md, which used to claim the
# opposite. Keep this check on its own merits, not to move an alert.
# (Rule: https://codeql.github.com/codeql-query-help/python/py-path-injection/)
_SAFE_VIRTUAL_PATH_PATTERN: Final[str] = r"[^\x00-\x1f\x7f]{1,4096}"
_SAFE_VIRTUAL_PATH_RE: Final[re.Pattern[str]] = re.compile(_SAFE_VIRTUAL_PATH_PATTERN)


def _validate_virtual_path(path: str) -> str:
    normalized_input = str(path).replace("\\", "/")
    parts = PurePosixPath(normalized_input).parts
    if ".." in parts or normalized_input.startswith("~"):
        raise ValueError(f"Path traversal not allowed: {path}")
    if re.match(r"^[a-zA-Z]:", normalized_input):
        raise ValueError(f"Windows absolute paths are not supported: {path}")
    normalized = posixpath.normpath(normalized_input)
    if not normalized.startswith("/"):
        normalized = f"/{normalized}"
    if ".." in normalized.split("/"):
        raise ValueError(f"Path traversal detected after normalization: {path}")
    if not _SAFE_VIRTUAL_PATH_RE.fullmatch(normalized):
        raise ValueError(f"Path contains unsupported characters: {path!r}")
    return normalized


def resolve_within(root: os.PathLike[str] | str, key: str) -> Path:
    """Resolve ``key`` under ``root``, refusing anything that escapes it.

    Two layers: reject ``..`` / ``~`` / drive-prefixed inputs *before*
    touching the filesystem, then resolve and re-check containment so a
    symlink or Windows junction cannot redirect the result outside the
    root.

    Module-level rather than a ``WorkspaceBackend`` method because
    ``services.media`` and the workspace HTTP route both need it without
    paying for a backend instance (whose ``__init__`` mkdirs, copies the
    environment, and mints a sandbox id).

    **The root is resolved, not merely made absolute.** Comparing a fully
    resolved candidate against an unresolved root is not like-for-like: if
    any component of the root is itself a symlink (a macOS ``/tmp``, a
    symlinked home or data directory), every legitimate path under it
    resolves to a prefix the root does not have and is refused. That failed
    closed rather than open, so it was never a hole -- but it rejected valid
    files. ``WorkspaceBackend`` already resolves its own root, so this makes
    the two entry points agree.
    """
    root_path = Path(os.path.abspath(os.fspath(root))).resolve(strict=False)
    virtual = _validate_virtual_path(key)
    candidate = root_path / virtual.lstrip("/")
    try:
        resolved = candidate.resolve(strict=False)
    except (OSError, RuntimeError) as exc:
        # A symlink loop or an unreadable component. Indistinguishable from
        # an escape as far as the caller is concerned, so it translates the
        # same way.
        raise ValueError(f"Path '{key}' could not be resolved") from exc

    # An explicit conditional rather than leaning on ``relative_to`` raising:
    # containment is the point of this function, so it should read as a
    # check, and a check that controls a branch is one a static analyser can
    # actually see.
    if not resolved.is_relative_to(root_path):
        raise ValueError(f"Path '{key}' resolves outside workspace root")
    return resolved


def resolve_entry_within(root: os.PathLike[str] | str, key: str) -> Path:
    """Contained path that names the entry itself, not a symlink's target.

    :func:`resolve_within` fully resolves the path, which is correct for
    reads and wrong for mutations: a symlink inside the workspace pointing
    at another file inside the workspace resolves *inside* (so containment
    passes), and unlinking or renaming the resolved path then acts on the
    target instead of the link.

    Containment is instead proved on the **parent**, which is fully
    resolved -- so no component along the way can redirect outside the root
    -- and the basename is appended unresolved. ``unlink`` / ``rename`` then
    act on the entry the caller named.

    Refuses the root itself: no mutation may delete or rename the workspace.

    Raises ``ValueError`` on escape or on a refused target, matching
    :func:`resolve_within` so callers translate the same way.
    """
    root_path = Path(os.path.abspath(os.fspath(root)))
    virtual = _validate_virtual_path(key).strip("/")
    if not virtual:
        raise ValueError("Refusing to operate on the workspace root itself")

    parent_virtual, _, basename = virtual.rpartition("/")
    if basename in ("", ".", ".."):
        raise ValueError(f"Path '{key}' does not name an entry")

    parent = resolve_within(root_path, parent_virtual or "/")
    return parent / basename


def normalize_virtual_path(path: str) -> str:
    """Normalize user paths to canonical workspace-relative virtual paths."""
    from services.plugin import NodeUserError

    if not path:
        return path
    windows_path = PureWindowsPath(path)
    if windows_path.drive or windows_path.root:
        relative = (
            "/" + "/".join(windows_path.parts[1:])
            if len(windows_path.parts) > 1
            else "/"
        )
    else:
        relative = path.replace("\\", "/")
    try:
        return _validate_virtual_path(relative)
    except ValueError as exc:
        raise NodeUserError(
            f"{exc}. The filesystem is sandboxed to the per-workflow workspace "
            "root — use a path relative to the workspace (e.g. "
            "'reports/data.csv'); '..' and '~' segments are rejected. To see "
            "what exists, use fs_search with mode='ls'."
        ) from exc


def perform_string_replacement(
    content: str,
    old_string: str,
    new_string: str,
    replace_all: bool = False,
) -> tuple[str, int] | str:
    """Perform exact replacement with ambiguity and EOF-newline diagnostics."""
    occurrences = content.count(old_string)
    if occurrences == 0:
        if (
            old_string.endswith("\n")
            and len(old_string) > 1
            and content.endswith(old_string.removesuffix("\n"))
        ):
            stripped = old_string.removesuffix("\n")
            stripped_count = content.count(stripped)
            if stripped_count == 1:
                return (
                    "Error: old_string ends with a newline, but the file does "
                    "not end with a newline. Retry with the trailing newline "
                    "removed from old_string (and from new_string if it also "
                    "ends with a newline)."
                )
            return (
                "Error: old_string ends with a newline, but the file does "
                "not end with a newline. With the trailing newline removed, "
                f"old_string would appear {stripped_count} times in the file. "
                "Retry with the trailing newline removed and add surrounding "
                "context so the match is unique."
            )
        return f"Error: String not found in file: '{old_string}'"
    if occurrences > 1 and not replace_all:
        return (
            f"Error: String '{old_string}' appears {occurrences} times in file. "
            "Use replace_all=True to replace all instances, or provide a more "
            "specific string with surrounding context."
        )
    return content.replace(old_string, new_string), occurrences


def _find_nu() -> Optional[str]:
    if not hasattr(_find_nu, "_cached"):
        _find_nu._cached = shutil.which("nu")
    return _find_nu._cached


class WorkspaceBackend:
    """Workspace-rooted filesystem operations plus bounded shell execution."""

    def __init__(
        self,
        root_dir: os.PathLike[str] | str,
        *,
        timeout: int = 120,
        max_output_bytes: int = 100_000,
        env: Optional[Dict[str, str]] = None,
        inherit_env: bool = False,
        max_file_size_mb: int = 10,
        **_: Any,
    ) -> None:
        if timeout <= 0:
            raise ValueError(f"timeout must be positive, got {timeout}")
        self.cwd = Path(root_dir).resolve()
        self.cwd.mkdir(parents=True, exist_ok=True)
        self._default_timeout = timeout
        self._max_output_bytes = max_output_bytes
        self._max_file_size_bytes = max_file_size_mb * 1024 * 1024
        self._env = os.environ.copy() if inherit_env else {}
        if env:
            self._env.update(env)
        self._sandbox_id = f"workspace-{uuid4().hex[:8]}"

    @property
    def id(self) -> str:
        return self._sandbox_id

    def _resolve_path(self, key: str) -> Path:
        return resolve_within(self.cwd, key)

    def _to_virtual_path(self, path: Path) -> str:
        resolved = path.resolve(strict=False)
        relative = resolved.relative_to(self.cwd)
        return "/" + relative.as_posix()

    def _safe_child(self, path: Path) -> Optional[Path]:
        try:
            resolved = path.resolve(strict=False)
            resolved.relative_to(self.cwd)
            return resolved
        except (OSError, RuntimeError, ValueError):
            return None

    def _open_read_fd(self, path: Path) -> int:
        """Open a contained regular file without following mutable symlinks.

        POSIX walks from an already-open workspace directory descriptor and
        applies ``O_NOFOLLOW`` to every component. Windows lacks ``dir_fd``
        traversal, so its fallback verifies the opened file identity against
        a no-follow stat and re-checks containment after opening.
        """
        try:
            relative = path.relative_to(self.cwd)
        except ValueError as exc:
            raise ValueError(
                f"Path '{path}' is outside workspace root"
            ) from exc
        if not relative.parts:
            raise IsADirectoryError(f"Cannot read workspace directory: {path}")

        supports_anchored_open = (
            os.name != "nt"
            and hasattr(os, "O_DIRECTORY")
            and os.open in os.supports_dir_fd
        )
        no_follow = getattr(os, "O_NOFOLLOW", 0)

        if supports_anchored_open:
            directory_flags = os.O_RDONLY | os.O_DIRECTORY | no_follow
            directory_fd = os.open(self.cwd, directory_flags)
            try:
                for component in relative.parts[:-1]:
                    next_fd = os.open(
                        component,
                        directory_flags,
                        dir_fd=directory_fd,
                    )
                    os.close(directory_fd)
                    directory_fd = next_fd
                file_fd = os.open(
                    relative.parts[-1],
                    os.O_RDONLY | no_follow,
                    dir_fd=directory_fd,
                )
            finally:
                os.close(directory_fd)
        else:
            file_fd = os.open(path, os.O_RDONLY | no_follow)
            try:
                opened = os.fstat(file_fd)
                current = os.stat(path, follow_symlinks=False)
                if stat.S_ISLNK(current.st_mode) or (
                    opened.st_dev,
                    opened.st_ino,
                ) != (current.st_dev, current.st_ino):
                    raise ValueError(
                        f"Path '{path}' changed while it was being opened"
                    )
                path.resolve(strict=True).relative_to(self.cwd)
            except BaseException:
                os.close(file_fd)
                raise

        try:
            if not stat.S_ISREG(os.fstat(file_fd).st_mode):
                raise IsADirectoryError(f"Path is not a regular file: {path}")
        except BaseException:
            os.close(file_fd)
            raise
        return file_fd

    def read_text_secure(self, path: os.PathLike[str] | str) -> str:
        """Read UTF-8 text from a pre-resolved contained path safely."""
        fd = self._open_read_fd(Path(path))
        with os.fdopen(fd, "r", encoding="utf-8") as handle:
            return handle.read()

    def atomic_write_text(
        self,
        path: os.PathLike[str] | str,
        content: str,
    ) -> None:
        """Atomically write a pre-resolved path within this workspace."""
        atomic_write_text(path, content, root_dir=self.cwd)

    @staticmethod
    def _file_info(path: Path, virtual_path: str, *, is_dir: bool) -> Dict[str, Any]:
        info: Dict[str, Any] = {
            "path": virtual_path + ("/" if is_dir else ""),
            "is_dir": is_dir,
        }
        try:
            status = path.stat()
            info["size"] = 0 if is_dir else int(status.st_size)
            info["modified_at"] = datetime.fromtimestamp(
                status.st_mtime
            ).isoformat()
        except OSError:
            pass
        return info

    def read(self, file_path: str, offset: int = 0, limit: int = 2000) -> ReadResult:
        try:
            resolved = self._resolve_path(file_path)
            if not resolved.exists() or not resolved.is_file():
                return ReadResult(error=f"File '{file_path}' not found")
            fd = self._open_read_fd(resolved)
            with os.fdopen(fd, "rb") as handle:
                raw = handle.read()
            try:
                content = raw.decode("utf-8")
                encoding = "utf-8"
            except UnicodeDecodeError:
                content = base64.standard_b64encode(raw).decode("ascii")
                encoding = "base64"
            if encoding == "utf-8":
                if not content or not content.strip():
                    content = EMPTY_CONTENT_WARNING
                else:
                    content = content.replace("\r\n", "\n").replace("\r", "\n")
                    lines = content.splitlines(keepends=True)
                    if offset >= len(lines):
                        return ReadResult(
                            error=(
                                f"Line offset {offset} exceeds file length "
                                f"({len(lines)} lines)"
                            )
                        )
                    content = "".join(lines[offset : offset + limit])
            return ReadResult(
                file_data={"content": content, "encoding": encoding}
            )
        except (OSError, RuntimeError, ValueError) as exc:
            return ReadResult(error=f"Error reading file '{file_path}': {exc}")

    def ls_info(self, path: str) -> list[Dict[str, Any]]:
        directory = self._resolve_path(path)
        if not directory.exists() or not directory.is_dir():
            return []
        entries: list[Dict[str, Any]] = []
        for child in directory.iterdir():
            safe = self._safe_child(child)
            if safe is None:
                continue
            try:
                is_dir = safe.is_dir()
                is_file = safe.is_file()
            except OSError:
                continue
            if not is_dir and not is_file:
                continue
            entries.append(
                self._file_info(
                    safe,
                    self._to_virtual_path(safe),
                    is_dir=is_dir,
                )
            )
        entries.sort(key=lambda item: item["path"])
        return entries

    def glob_info(
        self,
        pattern: str,
        path: str = "/",
    ) -> list[Dict[str, Any]]:
        pattern_parts = PurePosixPath(pattern.replace("\\", "/")).parts
        if ".." in pattern_parts or pattern.startswith("~"):
            raise ValueError("Path traversal not allowed in glob pattern")
        directory = self._resolve_path(path)
        if not directory.exists() or not directory.is_dir():
            return []
        matches: list[Dict[str, Any]] = []
        for candidate in directory.rglob(pattern.lstrip("/")):
            safe = self._safe_child(candidate)
            if safe is None:
                continue
            try:
                if not safe.is_file():
                    continue
            except OSError:
                continue
            matches.append(
                self._file_info(
                    safe,
                    self._to_virtual_path(safe),
                    is_dir=False,
                )
            )
        matches.sort(key=lambda item: item["path"])
        return matches

    def grep_raw(
        self,
        pattern: str,
        path: Optional[str] = None,
        glob: Optional[str] = None,
    ) -> list[Dict[str, Any]] | str:
        try:
            base = self._resolve_path(path or ".")
        except (OSError, RuntimeError, ValueError) as exc:
            return f"Error searching path '{path or '.'}': {exc}"
        if not base.exists():
            return []
        candidates = [base] if base.is_file() else base.rglob("*")
        matches: list[Dict[str, Any]] = []
        for candidate in candidates:
            safe = self._safe_child(candidate)
            if safe is None:
                continue
            try:
                if not safe.is_file() or safe.stat().st_size > self._max_file_size_bytes:
                    continue
                relative = safe.relative_to(base if base.is_dir() else base.parent)
                if glob and not (
                    fnmatch.fnmatch(relative.as_posix(), glob)
                    or fnmatch.fnmatch(safe.name, glob)
                ):
                    continue
                content = self.read_text_secure(safe)
            except (OSError, RuntimeError, UnicodeDecodeError, ValueError):
                continue
            virtual = self._to_virtual_path(safe)
            for line_number, line in enumerate(content.splitlines(), 1):
                if pattern in line:
                    matches.append(
                        {
                            "path": virtual,
                            "line": line_number,
                            "text": line,
                        }
                    )
        return matches

    def _shape_process_result(
        self,
        *,
        stdout: str,
        stderr: str,
        returncode: int,
    ) -> ExecuteResponse:
        parts = [stdout] if stdout else []
        if stderr:
            parts.extend(
                f"[stderr] {line}" for line in stderr.strip().split("\n")
            )
        output = "\n".join(parts) if parts else "<no output>"
        truncated = False
        if len(output) > self._max_output_bytes:
            output = output[: self._max_output_bytes]
            output += (
                f"\n\n... Output truncated at {self._max_output_bytes} bytes."
            )
            truncated = True
        if returncode != 0:
            output = f"{output.rstrip()}\n\nExit code: {returncode}"
        return ExecuteResponse(
            output=output,
            exit_code=returncode,
            truncated=truncated,
        )

    def execute(
        self,
        command: str,
        *,
        timeout: Optional[int] = None,
    ) -> ExecuteResponse:
        if not command or not isinstance(command, str):
            return ExecuteResponse(
                output="Error: Command must be a non-empty string.",
                exit_code=1,
            )
        effective_timeout = (
            timeout if timeout is not None else self._default_timeout
        )
        if effective_timeout <= 0:
            raise ValueError(
                f"timeout must be positive, got {effective_timeout}"
            )
        nu = _find_nu()
        argv: str | list[str]
        shell = nu is None
        if nu is None:
            argv = command
        else:
            argv = [nu, "-n", "--no-history", "-c", command]
        try:
            result = subprocess.run(
                argv,
                check=False,
                shell=shell,
                capture_output=True,
                stdin=subprocess.DEVNULL,
                text=True,
                timeout=effective_timeout,
                env=without_onepassword_environment(self._env),
                cwd=str(self.cwd),
            )
            return self._shape_process_result(
                stdout=result.stdout or "",
                stderr=result.stderr or "",
                returncode=result.returncode,
            )
        except subprocess.TimeoutExpired:
            suffix = (
                " (custom timeout)" if timeout is not None else ""
            )
            return ExecuteResponse(
                output=(
                    f"Error: Command timed out after {effective_timeout} "
                    f"seconds{suffix}. The command may be stuck or require "
                    "more time."
                ),
                exit_code=124,
            )
        except Exception as exc:  # noqa: BLE001
            runner = "nu" if nu else "the host shell"
            return ExecuteResponse(
                output=(
                    f"Error executing command via {runner} "
                    f"({type(exc).__name__}): {exc}"
                ),
                exit_code=1,
            )


# Compatibility name retained for integrations that imported the old class.
NushellBackend = WorkspaceBackend


def get_backend(
    parameters: Dict[str, Any],
    context: Optional[Dict[str, Any]] = None,
) -> WorkspaceBackend:
    """Return a native backend rooted at the per-workflow workspace."""
    from core.config import Settings
    from core.logging import get_logger

    parameter_directory = parameters.get("working_directory")
    context_directory = context.get("workspace_dir") if context else None
    root = (
        parameter_directory
        or context_directory
        or os.path.join(Settings().workspace_base_resolved, "default")
    )
    os.makedirs(root, exist_ok=True)
    get_logger(__name__).info("[Filesystem] root=%s", root)
    return WorkspaceBackend(root_dir=root, inherit_env=True)