Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

12.9 KB
Raw Blame
"""Tests for ``check_sandbox_static_readiness`` (app-startup sandbox gate).

Domain discipline under test: ``SANDBOX_VOLUMES`` (host-domain triples,
built with the same ``host_side_sources`` flag the runtime mount-building
path uses) are compared as-is;
external upload dirs are backend-domain paths, folded then mapped through
the same ``SandboxPathMapper`` before the conflict check runs -- entirely
in the post-mapper host domain, over the combined triple set.
"""

from __future__ import annotations

from pathlib import Path
from unittest.mock import patch

import pytest

from xagent.sandbox.base import SandboxRuntimeConflictError
from xagent.web.sandbox_manager import check_sandbox_static_readiness


class _ProbeStub:
    """Minimal stand-in exposing only the attribute readiness consults."""

    def __init__(self, supports_runtime_spec: bool) -> None:
        self._supports = supports_runtime_spec

    async def _resolve_backend_probe(self) -> bool:
        return self._supports

    def validate_host_workspace_access(self) -> None:
        raise AssertionError("non-Docker backends must not run the host access probe")

    def requires_host_workspace_access(self) -> bool:
        return False


@pytest.mark.asyncio
async def test_readiness_skipped_when_backend_does_not_support_reconciliation():
    """Non-reconciling backends have no live spec to protect here."""
    with (
        patch.dict(
            "os.environ",
            {"SANDBOX_VOLUMES": "/foo:/guest1:ro"},
            clear=True,
        ),
    ):
        await check_sandbox_static_readiness(_ProbeStub(False))


@pytest.mark.asyncio
async def test_volume_subpath_readiness_rejects_legacy_backend():
    with patch.dict(
        "os.environ",
        {"XAGENT_SANDBOX_WORKSPACE_MOUNT_MODE": "volume_subpath"},
        clear=True,
    ):
        with pytest.raises(
            SandboxRuntimeConflictError, match="require.*Docker/spec-reconciliation"
        ):
            await check_sandbox_static_readiness(_ProbeStub(False))


@pytest.mark.asyncio
async def test_volume_subpath_readiness_requires_complete_configuration(tmp_path):
    with patch.dict(
        "os.environ",
        {
            "XAGENT_SANDBOX_WORKSPACE_MOUNT_MODE": "volume_subpath",
            "XAGENT_SANDBOX_WORKSPACE_VOLUME_ROOT": str(tmp_path),
        },
        clear=True,
    ):
        with pytest.raises(SandboxRuntimeConflictError, match="requires both"):
            await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_volume_subpath_readiness_rejects_invalid_volume_name(tmp_path):
    with patch.dict(
        "os.environ",
        {
            "XAGENT_SANDBOX_WORKSPACE_MOUNT_MODE": "volume_subpath",
            "XAGENT_SANDBOX_WORKSPACE_VOLUME": "invalid volume!",
            "XAGENT_SANDBOX_WORKSPACE_VOLUME_ROOT": str(tmp_path),
        },
        clear=True,
    ):
        with pytest.raises(SandboxRuntimeConflictError, match="Invalid volume_subpath"):
            await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_volume_subpath_readiness_rejects_missing_root(tmp_path):
    missing_root = tmp_path / "missing"
    with patch.dict(
        "os.environ",
        {
            "XAGENT_SANDBOX_WORKSPACE_MOUNT_MODE": "volume_subpath",
            "XAGENT_SANDBOX_WORKSPACE_VOLUME": "xagent-stage-workspaces",
            "XAGENT_SANDBOX_WORKSPACE_VOLUME_ROOT": str(missing_root),
        },
        clear=True,
    ):
        with pytest.raises(SandboxRuntimeConflictError, match=repr(str(missing_root))):
            await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_volume_subpath_readiness_rejects_external_dir_outside_root(tmp_path):
    volume_root = tmp_path / "workspaces"
    volume_root.mkdir()
    external_dir = tmp_path / "external"
    external_dir.mkdir()
    with patch.dict(
        "os.environ",
        {
            "XAGENT_SANDBOX_WORKSPACE_MOUNT_MODE": "volume_subpath",
            "XAGENT_SANDBOX_WORKSPACE_VOLUME": "xagent-stage-workspaces",
            "XAGENT_SANDBOX_WORKSPACE_VOLUME_ROOT": str(volume_root),
            "XAGENT_EXTERNAL_UPLOAD_DIRS": str(external_dir),
        },
        clear=True,
    ):
        with pytest.raises(SandboxRuntimeConflictError, match=repr(str(external_dir))):
            await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_readiness_skipped_when_no_relevant_env_configured():
    """No custom mounts or external directories is a valid empty topology."""
    with (
        patch.dict("os.environ", {}, clear=True),
    ):
        await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_readiness_raises_on_host_conflict():
    """Two mounts sharing a host path but disagreeing on guest path raise."""
    with (
        patch.dict(
            "os.environ",
            {"SANDBOX_VOLUMES": "/foo:/guest1:ro;/foo:/guest2:ro"},
            clear=True,
        ),
    ):
        with pytest.raises(SandboxRuntimeConflictError):
            await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_readiness_raises_on_guest_crash():
    """Two mounts sharing a guest path but disagreeing on host source raise
    at startup, instead of only when a task's create() reaches the daemon."""
    with (
        patch.dict(
            "os.environ",
            {"SANDBOX_VOLUMES": "/foo:/guest:ro;/bar:/guest:ro"},
            clear=True,
        ),
    ):
        with pytest.raises(SandboxRuntimeConflictError):
            await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_readiness_allows_identical_triple_duplicated_across_sources():
    """The exact same (host, guest, mode) triple showing up from two
    different sources is a legal duplicate, not a conflict."""
    with (
        patch.dict(
            "os.environ",
            {"SANDBOX_VOLUMES": "/foo:/guest:ro;/foo:/guest:ro"},
            clear=True,
        ),
    ):
        await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_readiness_groups_paths_the_backend_would_collapse():
    """``//foo`` and ``/foo`` are one mount point to the backend.

    ``posixpath.normpath`` keeps a leading ``//``, so normalizing with it
    alone would file these under two different host keys and let a real
    duplicate-mount conflict past the startup gate; the shared
    ``canonical_sandbox_path`` owner collapses the leading slash run the
    same way the desired spec does.
    """
    with (
        patch.dict(
            "os.environ",
            {"SANDBOX_VOLUMES": "//foo:/guest1:ro;/foo:/guest2:ro"},
            clear=True,
        ),
    ):
        with pytest.raises(SandboxRuntimeConflictError):
            await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_readiness_checks_folded_external_dirs_against_host_domain(
    tmp_path: Path,
):
    """External upload dirs are folded, then mapped through the same
    ``SandboxPathMapper``/``host_side_sources`` combination the runtime
    mount-building path uses, and checked in that same host domain.

    Here the external dir sits outside the storage root, so the mapper
    leaves its path unchanged (identity mapping); a SANDBOX_VOLUMES entry
    claiming the same host path under a different guest path must still be
    caught as a host conflict once both are in host domain.
    """
    backend_storage_root = tmp_path / "backend" / ".xagent"
    host_storage_root = tmp_path / "host" / ".xagent"
    external_dir = tmp_path / "shared" / "kb"
    external_dir.mkdir(parents=True)

    with (
        patch.dict(
            "os.environ",
            {
                "SANDBOX_VOLUMES": f"{external_dir}:/guest-other:ro",
                "XAGENT_EXTERNAL_UPLOAD_DIRS": str(external_dir),
                "XAGENT_STORAGE_ROOT": str(backend_storage_root),
                "XAGENT_SANDBOX_HOST_STORAGE_ROOT": str(host_storage_root),
            },
            clear=True,
        ),
    ):
        with pytest.raises(SandboxRuntimeConflictError):
            await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_readiness_allows_non_conflicting_external_dir(tmp_path: Path):
    """A well-formed deployment (disjoint external dir, no drift) passes."""
    backend_storage_root = tmp_path / "backend" / ".xagent"
    host_storage_root = tmp_path / "host" / ".xagent"
    external_dir = tmp_path / "shared" / "kb"
    external_dir.mkdir(parents=True)

    with (
        patch.dict(
            "os.environ",
            {
                "XAGENT_EXTERNAL_UPLOAD_DIRS": str(external_dir),
                "XAGENT_STORAGE_ROOT": str(backend_storage_root),
                "XAGENT_SANDBOX_HOST_STORAGE_ROOT": str(host_storage_root),
            },
            clear=True,
        ),
    ):
        await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.parametrize("reverse_order", [False, True])
@pytest.mark.asyncio
async def test_readiness_dedupes_external_aliases_by_physical_identity(
    tmp_path: Path,
    reverse_order: bool,
):
    """Equivalent aliases produce one stable external volume in either order."""
    backend_storage_root = tmp_path / "backend" / ".xagent"
    backend_storage_root.mkdir(parents=True)
    physical_dir = backend_storage_root / "real-kb"
    physical_dir.mkdir()
    alias_a = backend_storage_root / "alias-a"
    alias_b = backend_storage_root / "alias-b"
    alias_a.symlink_to(physical_dir, target_is_directory=True)
    alias_b.symlink_to(physical_dir, target_is_directory=True)
    aliases = [alias_a, alias_b]
    if reverse_order:
        aliases.reverse()

    captured: list[tuple[tuple[str, str, str], ...]] = []
    with (
        patch.dict(
            "os.environ",
            {
                "XAGENT_EXTERNAL_UPLOAD_DIRS": ",".join(str(path) for path in aliases),
                "XAGENT_STORAGE_ROOT": str(backend_storage_root),
                "XAGENT_UPLOADS_DIR": str(backend_storage_root / "uploads"),
                "XAGENT_SANDBOX_HOST_STORAGE_ROOT": "/docker-host/storage",
            },
            clear=True,
        ),
        patch(
            "xagent.web.sandbox_manager._check_no_conflicting_readiness_volumes",
            side_effect=lambda volumes: captured.append(tuple(volumes)),
        ),
    ):
        await check_sandbox_static_readiness(_ProbeStub(True))

    assert captured == [
        (
            (
                "/docker-host/storage/alias-a",
                str(physical_dir),
                "rw",
            ),
        )
    ]


@pytest.mark.asyncio
async def test_readiness_keeps_real_conflict_after_external_alias_dedupe(
    tmp_path: Path,
):
    """Physical dedupe must not hide conflicts with explicit host volumes."""
    backend_storage_root = tmp_path / "backend" / ".xagent"
    backend_storage_root.mkdir(parents=True)
    physical_dir = backend_storage_root / "real-kb"
    physical_dir.mkdir()
    alias_a = backend_storage_root / "alias-a"
    alias_b = backend_storage_root / "alias-b"
    alias_a.symlink_to(physical_dir, target_is_directory=True)
    alias_b.symlink_to(physical_dir, target_is_directory=True)

    with (
        patch.dict(
            "os.environ",
            {
                "SANDBOX_VOLUMES": "/docker-host/storage/alias-a:/different-guest:ro",
                "XAGENT_EXTERNAL_UPLOAD_DIRS": f"{alias_b},{alias_a}",
                "XAGENT_STORAGE_ROOT": str(backend_storage_root),
                "XAGENT_UPLOADS_DIR": str(backend_storage_root / "uploads"),
                "XAGENT_SANDBOX_HOST_STORAGE_ROOT": "/docker-host/storage",
            },
            clear=True,
        ),
    ):
        with pytest.raises(SandboxRuntimeConflictError):
            await check_sandbox_static_readiness(_ProbeStub(True))


@pytest.mark.asyncio
async def test_readiness_absolutizes_relative_external_dir(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
):
    """A relative ``XAGENT_EXTERNAL_UPLOAD_DIRS`` entry is checked as the
    directory it actually names.

    ``get_external_upload_dirs`` accepts any spelling that resolves to an
    existing directory, including one relative to the process cwd, while
    the mount-path contract only compares absolute paths. Absolutizing
    through the same owner the runtime build path uses is what lets the
    startup gate see this entry and the equivalent absolute
    ``SANDBOX_VOLUMES`` spelling as the same host path -- and keeps a legal
    relative configuration from failing startup outright.
    """
    external_dir = tmp_path / "shared-kb"
    external_dir.mkdir()
    monkeypatch.chdir(tmp_path)

    with (
        patch.dict(
            "os.environ",
            {
                "SANDBOX_VOLUMES": f"{Path.cwd() / 'shared-kb'}:/guest-other:ro",
                "XAGENT_EXTERNAL_UPLOAD_DIRS": "shared-kb",
            },
            clear=True,
        ),
    ):
        with pytest.raises(SandboxRuntimeConflictError):
            await check_sandbox_static_readiness(_ProbeStub(True))