Enterprise agent platform for building, deploying, and operating AI teammates.
"""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))