Skip to content

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

20.5 KB
Raw Blame
from __future__ import annotations

import asyncio
import os
import threading
import time
from io import BytesIO
from pathlib import Path

import pytest
from PIL import Image

from xagent.core.computer.schema import (
    COMPUTER_FRAME_ID_METADATA_KEY,
    COMPUTER_SESSION_ID_METADATA_KEY,
    Viewport,
)
from xagent.core.computer.store import ObservationStore
from xagent.core.context_materializer import WorkspaceContextReferenceResolver
from xagent.core.workspace import TaskWorkspace


class FakeWorkspace:
    def __init__(self, root: Path) -> None:
        self.workspace_dir = root
        self.temp_dir = root / "temp"
        self.temp_dir.mkdir(parents=True)
        self.internal_temp_dir = self.temp_dir / ".fake-internal"
        self._paths: dict[str, Path] = {}
        self.registration_threads: list[int] = []
        self.durable_registration_calls = 0

    def get_file_id_from_path(self, path: str) -> str | None:
        resolved = Path(path).resolve()
        return next(
            (file_id for file_id, value in self._paths.items() if value == resolved),
            None,
        )

    def register_file(self, path: str) -> str:
        self.durable_registration_calls += 1
        return self._register(path)

    def register_internal_file(self, path: str) -> str:
        return self._register(path)

    def _register(self, path: str) -> str:
        self.registration_threads.append(threading.get_ident())
        existing = self.get_file_id_from_path(path)
        if existing is not None:
            return existing
        file_id = f"file-{len(self._paths) + 1}"
        self._paths[file_id] = Path(path).resolve()
        return file_id

    def resolve_file_id_detached(self, file_id: str) -> Path | None:
        return self._paths.get(file_id)

    def unregister_internal_file(self, path: str) -> str | None:
        resolved = Path(path).resolve()
        file_id = next(
            (key for key, value in self._paths.items() if value == resolved),
            None,
        )
        if file_id is not None:
            self._paths.pop(file_id, None)
        return file_id


class DurableOnlyWorkspace:
    def __init__(self, root: Path) -> None:
        self.workspace_dir = root
        self.temp_dir = root / "temp"
        self.temp_dir.mkdir(parents=True)

    def register_file(self, path: str) -> str:
        return "durable-file"


class MissingInternalTempWorkspace(FakeWorkspace):
    def __init__(self, root: Path) -> None:
        super().__init__(root)
        del self.internal_temp_dir


def _png_bytes() -> bytes:
    output = BytesIO()
    Image.new("RGB", (2, 2), color="red").save(output, format="PNG")
    return output.getvalue()


@pytest.mark.asyncio
async def test_observation_store_persists_and_resolves_file_ref(
    tmp_path: Path,
) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    store = ObservationStore(workspace)
    event_loop_thread = threading.get_ident()
    image_bytes = _png_bytes()

    reference = await store.save_screenshot(
        session_id="session/unsafe",
        frame_id="frame-1",
        image_bytes=image_bytes,
        mime_type="image/png",
        viewport=Viewport(width=1280, height=720),
        text_fallback="browser screenshot",
    )

    assert reference.file_ref["file_id"] == "file-1"
    assert reference.file_ref["internal"] is True
    assert reference.file_ref["preview_url"] is None
    assert reference.file_ref["download_url"] is None
    assert reference.file_ref["markdown_link"] is None
    assert "file_path" not in reference.file_ref
    assert "relative_path" not in reference.file_ref
    assert reference.metadata[COMPUTER_SESSION_ID_METADATA_KEY] == "session/unsafe"
    assert reference.metadata[COMPUTER_FRAME_ID_METADATA_KEY] == "frame-1"
    assert reference.metadata["sha256"]
    assert reference.metadata["viewport"]["width"] == 1280
    assert workspace.registration_threads
    assert all(
        thread_id != event_loop_thread for thread_id in workspace.registration_threads
    )
    assert len(list(store.root.rglob("*.png"))) == 1
    assert workspace.durable_registration_calls == 0

    materialized = await WorkspaceContextReferenceResolver(workspace).resolve_image(
        reference
    )
    assert materialized.startswith("data:image/png;base64,")


@pytest.mark.asyncio
async def test_observation_store_is_idempotent_for_same_frame_and_bytes(
    tmp_path: Path,
) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    store = ObservationStore(workspace)

    first, second = await asyncio.gather(
        store.save_screenshot(
            session_id="session-1",
            frame_id="frame-1",
            image_bytes=b"same-image",
            mime_type="image/png",
        ),
        store.save_screenshot(
            session_id="session-1",
            frame_id="frame-1",
            image_bytes=b"same-image",
            mime_type="image/png",
        ),
    )

    assert first.file_id == second.file_id
    assert len(list(store.root.rglob("*.png"))) == 1


@pytest.mark.asyncio
async def test_observation_store_rejects_frame_reuse_with_different_image(
    tmp_path: Path,
) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    store = ObservationStore(workspace)
    await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-1",
        image_bytes=b"first-image",
        mime_type="image/png",
    )

    with pytest.raises(ValueError, match="already bound to different screenshot"):
        await store.save_screenshot(
            session_id="session-1",
            frame_id="frame-1",
            image_bytes=b"second-image",
            mime_type="image/png",
        )

    assert len(list(store.root.rglob("*.png"))) == 1


@pytest.mark.asyncio
async def test_observation_store_prunes_old_frame_bytes(tmp_path: Path) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    store = ObservationStore(workspace, retention=2)

    first = await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-0",
        image_bytes=b"image-0",
        mime_type="image/png",
    )
    first_path = workspace.resolve_file_id_detached(first.file_id)
    assert first_path is not None
    os.utime(first_path, ns=(1, 1))

    second = await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-1",
        image_bytes=b"image-1",
        mime_type="image/png",
    )
    second_path = workspace.resolve_file_id_detached(second.file_id)
    assert second_path is not None
    os.utime(second_path, ns=(2, 2))

    latest = await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-2",
        image_bytes=b"image-2",
        mime_type="image/png",
    )

    assert len(list(store.root.rglob("*.png"))) == 2
    assert workspace.resolve_file_id_detached(first.file_id) is None
    assert workspace.resolve_file_id_detached(second.file_id) is not None
    latest_path = workspace.resolve_file_id_detached(latest.file_id)
    assert latest_path is not None
    assert latest_path.exists()


@pytest.mark.asyncio
async def test_observation_store_prunes_incomplete_temp_files(tmp_path: Path) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    store = ObservationStore(workspace)
    await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-0",
        image_bytes=b"first-image",
        mime_type="image/png",
    )
    session_dir = next(path for path in store.root.iterdir() if path.is_dir())
    incomplete = session_dir / ".computer-frame-crash"
    incomplete.write_bytes(b"partial")
    old_timestamp = time.time() - 3_600
    os.utime(incomplete, (old_timestamp, old_timestamp))

    await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-1",
        image_bytes=b"image",
        mime_type="image/png",
    )

    assert not incomplete.exists()


@pytest.mark.asyncio
async def test_observation_store_preserves_fresh_incomplete_temp_files(
    tmp_path: Path,
) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    store = ObservationStore(workspace)
    await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-0",
        image_bytes=b"first-image",
        mime_type="image/png",
    )
    session_dir = next(path for path in store.root.iterdir() if path.is_dir())
    incomplete = session_dir / ".computer-frame-in-flight"
    incomplete.write_bytes(b"partial")

    await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-1",
        image_bytes=b"image",
        mime_type="image/png",
    )

    assert incomplete.exists()


@pytest.mark.asyncio
async def test_observation_store_unregisters_concurrently_deleted_frame(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    store = ObservationStore(workspace, retention=1)
    first = await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-1",
        image_bytes=b"image-1",
        mime_type="image/png",
    )
    first_path = workspace.resolve_file_id_detached(first.file_id)
    assert first_path is not None

    original_unlink = Path.unlink
    externally_deleted = False

    def unlink_after_external_delete(
        path: Path,
        *args: object,
        **kwargs: object,
    ) -> None:
        nonlocal externally_deleted
        if path == first_path and not externally_deleted:
            original_unlink(path)
            externally_deleted = True
        original_unlink(path, *args, **kwargs)

    monkeypatch.setattr(Path, "unlink", unlink_after_external_delete)

    await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-2",
        image_bytes=b"image-2",
        mime_type="image/png",
    )

    assert externally_deleted is True
    assert workspace.resolve_file_id_detached(first.file_id) is None


@pytest.mark.asyncio
async def test_observation_store_prunes_other_frames_after_stat_race(
    tmp_path: Path,
    monkeypatch: pytest.MonkeyPatch,
) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    store = ObservationStore(workspace, retention=3)
    first = await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-1",
        image_bytes=b"image-1",
        mime_type="image/png",
    )
    second = await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-2",
        image_bytes=b"image-2",
        mime_type="image/png",
    )
    first_path = workspace.resolve_file_id_detached(first.file_id)
    assert first_path is not None

    original_stat = Path.stat
    original_unlink = Path.unlink
    externally_deleted = False

    def stat_after_external_delete(
        path: Path,
        *args: object,
        **kwargs: object,
    ) -> os.stat_result:
        nonlocal externally_deleted
        if path == first_path and not externally_deleted:
            original_unlink(path)
            externally_deleted = True
            raise FileNotFoundError(path)
        return original_stat(path, *args, **kwargs)

    store.retention = 1
    monkeypatch.setattr(Path, "stat", stat_after_external_delete)

    latest = await store.save_screenshot(
        session_id="session-1",
        frame_id="frame-3",
        image_bytes=b"image-3",
        mime_type="image/png",
    )

    assert externally_deleted is True
    assert workspace.resolve_file_id_detached(second.file_id) is None
    assert workspace.resolve_file_id_detached(latest.file_id) is not None


@pytest.mark.asyncio
async def test_observation_store_rejects_invalid_input(tmp_path: Path) -> None:
    store = ObservationStore(
        FakeWorkspace(tmp_path / "workspace"),
        max_image_bytes=5,
    )

    with pytest.raises(ValueError, match="must not be empty"):
        await store.save_screenshot(
            session_id="session-1",
            frame_id="frame-1",
            image_bytes=b"",
            mime_type="image/png",
        )
    with pytest.raises(ValueError, match="unsupported screenshot MIME"):
        await store.save_screenshot(
            session_id="session-1",
            frame_id="frame-1",
            image_bytes=b"image",
            mime_type="image/svg+xml",
        )
    with pytest.raises(ValueError, match="at most 5 bytes"):
        await store.save_screenshot(
            session_id="session-1",
            frame_id="frame-1",
            image_bytes=b"123456",
            mime_type="image/png",
        )


def test_observation_store_requires_internal_registration(tmp_path: Path) -> None:
    with pytest.raises(TypeError, match="internal temp storage and file registration"):
        ObservationStore(DurableOnlyWorkspace(tmp_path / "workspace"))


def test_observation_store_requires_internal_temp_capability(tmp_path: Path) -> None:
    with pytest.raises(TypeError, match="internal temp storage and file registration"):
        ObservationStore(MissingInternalTempWorkspace(tmp_path / "workspace"))


def test_observation_store_rejects_nested_internal_temp_root(tmp_path: Path) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    workspace.internal_temp_dir = workspace.temp_dir / "nested" / ".fake-internal"

    with pytest.raises(ValueError, match="direct child"):
        ObservationStore(workspace)


def test_observation_store_rejects_invalid_limits(tmp_path: Path) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    with pytest.raises(ValueError, match="retention must be positive"):
        ObservationStore(workspace, retention=0)
    with pytest.raises(ValueError, match="max_image_bytes must be positive"):
        ObservationStore(workspace, max_image_bytes=0)


@pytest.mark.asyncio
async def test_observation_store_compensates_failed_reference_validation(
    tmp_path: Path,
) -> None:
    workspace = FakeWorkspace(tmp_path / "workspace")
    store = ObservationStore(workspace)

    with pytest.raises(ValueError, match="must not contain a path"):
        await store.save_screenshot(
            session_id="session-1",
            frame_id="frame-1",
            image_bytes=b"image",
            mime_type="image/png",
            metadata={"path": "/private/secret.png"},
        )

    assert list(store.root.rglob("*.png")) == []
    assert workspace._paths == {}


def test_internal_file_registration_survives_workspace_reconstruction(
    tmp_path: Path,
) -> None:
    first = TaskWorkspace("task_41", base_dir=str(tmp_path))
    reconstructed: TaskWorkspace | None = None
    file_id: str | None = None
    try:
        frame = first.temp_dir / "frame.png"
        frame.write_bytes(b"frame")

        file_id = first.register_internal_file(str(frame))
        assert file_id.startswith("internal-")
        reconstructed = TaskWorkspace("task_41", base_dir=str(tmp_path))

        assert reconstructed.get_file_id_from_path(str(frame)) == file_id
        assert reconstructed.resolve_file_id_detached(file_id) == frame.resolve()
    finally:
        if reconstructed is not None:
            reconstructed.cleanup()
        first.cleanup()

    assert file_id is not None
    assert first._resolve_internal_file_id(file_id) is None


def test_internal_file_registration_rejects_external_paths(tmp_path: Path) -> None:
    workspace = TaskWorkspace("task_42", base_dir=str(tmp_path / "workspaces"))
    try:
        external = tmp_path / "external.png"
        external.write_bytes(b"external")

        with pytest.raises(ValueError, match="regular workspace temp files"):
            workspace.register_internal_file(str(external))
    finally:
        workspace.cleanup()


def test_internal_file_registration_rejects_output_files(tmp_path: Path) -> None:
    workspace = TaskWorkspace("task_46", base_dir=str(tmp_path))
    try:
        output = workspace.output_dir / "report.txt"
        output.write_text("report", encoding="utf-8")

        with pytest.raises(ValueError, match="regular workspace temp files"):
            workspace.register_internal_file(str(output))
    finally:
        workspace.cleanup()


def test_internal_file_registration_is_isolated_by_workspace_root(
    tmp_path: Path,
) -> None:
    first = TaskWorkspace("task_44", base_dir=str(tmp_path / "first"))
    second = TaskWorkspace("task_44", base_dir=str(tmp_path / "second"))
    try:
        frame = first.temp_dir / "frame.png"
        frame.write_bytes(b"frame")
        file_id = first.register_internal_file(str(frame))

        assert first.resolve_file_id_detached(file_id) == frame.resolve()
        assert second.resolve_file_id_detached(file_id) is None
    finally:
        first.cleanup()
        second.cleanup()


def test_internal_files_are_excluded_from_auto_registration_scan(
    tmp_path: Path,
) -> None:
    workspace = TaskWorkspace("task_45", base_dir=str(tmp_path))
    try:
        internal = workspace.temp_dir / "frame.png"
        internal.write_bytes(b"frame")
        visible = workspace.output_dir / "report.txt"
        visible.write_text("report", encoding="utf-8")
        workspace.register_internal_file(str(internal))

        scanned = workspace._scan_all_files()

        assert internal not in scanned
        assert visible in scanned
    finally:
        workspace.cleanup()


def test_internal_files_are_excluded_from_workspace_listing(tmp_path: Path) -> None:
    workspace = TaskWorkspace("task_47", base_dir=str(tmp_path))
    try:
        internal = workspace.temp_dir / "frame.png"
        internal.write_bytes(b"frame")
        workspace.register_internal_file(str(internal))

        files = workspace.get_all_files()

        assert files["temp"] == []
    finally:
        workspace.cleanup()


@pytest.mark.asyncio
async def test_observation_store_is_hidden_from_real_workspace_listing(
    tmp_path: Path,
) -> None:
    workspace = TaskWorkspace("task_48", base_dir=str(tmp_path))
    try:
        reference = await ObservationStore(workspace).save_screenshot(
            session_id="session-1",
            frame_id="frame-1",
            image_bytes=b"frame",
            mime_type="image/png",
        )

        assert workspace.resolve_file_id_detached(reference.file_id) is not None
        assert workspace.get_all_files()["temp"] == []
    finally:
        workspace.cleanup()


def test_unregistered_reserved_internal_temp_is_hidden(tmp_path: Path) -> None:
    workspace = TaskWorkspace("task_51", base_dir=str(tmp_path))
    try:
        frame = (
            workspace.internal_temp_dir
            / "computer_observations"
            / "session"
            / "frame.png"
        )
        frame.parent.mkdir(parents=True)
        frame.write_bytes(b"frame")

        assert workspace._is_internal_workspace_path(frame) is True
        assert workspace.get_all_files()["temp"] == []
    finally:
        workspace.cleanup()


def test_write_immutable_rejects_symlink_destination(tmp_path: Path) -> None:
    target = tmp_path / "target.png"
    target.write_bytes(b"image")
    link = tmp_path / "frame.png"
    link.symlink_to(target)

    with pytest.raises(ValueError, match="must not be a symlink"):
        ObservationStore._write_immutable(link, b"image")


def test_write_immutable_rejects_existing_different_bytes(tmp_path: Path) -> None:
    frame = tmp_path / "frame.png"
    frame.write_bytes(b"old")

    with pytest.raises(RuntimeError, match="contains other bytes"):
        ObservationStore._write_immutable(frame, b"new")


def test_internal_registration_rejects_temp_symlink_to_output(tmp_path: Path) -> None:
    workspace = TaskWorkspace("task_43", base_dir=str(tmp_path))
    try:
        target = workspace.output_dir / "frame.png"
        target.write_bytes(b"frame")
        link = workspace.temp_dir / "frame-link.png"
        link.symlink_to(target)

        with pytest.raises(ValueError, match="regular workspace temp files"):
            workspace.register_internal_file(str(link))
    finally:
        workspace.cleanup()


def test_clean_temp_files_unregisters_internal_files(tmp_path: Path) -> None:
    workspace = TaskWorkspace("task_50", base_dir=str(tmp_path))
    try:
        internal = workspace.temp_dir / "frame.png"
        internal.write_bytes(b"frame")
        file_id = workspace.register_internal_file(str(internal))

        workspace.clean_temp_files()

        assert not internal.exists()
        assert workspace.resolve_file_id_detached(file_id) is None
    finally:
        workspace.cleanup()


def test_internal_file_miss_warns_about_process_local_scope(
    tmp_path: Path,
    caplog: pytest.LogCaptureFixture,
) -> None:
    workspace = TaskWorkspace("task_49", base_dir=str(tmp_path))
    try:
        with caplog.at_level("WARNING"):
            assert workspace.resolve_file_id_detached("internal-missing") is None

        assert "Process-local internal file is unavailable" in caplog.text
    finally:
        workspace.cleanup()