Skip to content

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

13.5 KB
Raw Blame
from pathlib import Path
from types import SimpleNamespace

import pytest

from xagent.core import file_ref
from xagent.core.file_ref import (
    FILE_REF_OUTPUT_INSTRUCTIONS,
    build_file_id_ref,
    build_file_ref,
    build_workspace_file_ref,
    parse_file_id_ref,
    sanitize_file_ref_for_context,
)
from xagent.core.workspace import TaskWorkspace

FINAL_DELIVERABLE_INSTRUCTION_MARKER = "## FINAL DELIVERABLE FILE REFERENCES"


def test_final_deliverable_instruction_scopes_workspace_lookup_by_capability() -> None:
    assert file_ref.WORKSPACE_OUTPUT_FILES_TOOL_NAME == "get_workspace_output_files"
    lookup_instruction = file_ref.final_deliverable_file_reference_instructions(
        can_lookup=True
    )
    forced_instruction = file_ref.final_deliverable_file_reference_instructions(
        can_lookup=False
    )
    inline_instruction = file_ref.final_deliverable_file_reference_instructions(
        can_lookup=False,
        include_heading=False,
    )

    for instruction in (lookup_instruction, forced_instruction, inline_instruction):
        assert "exact markdown_link" in instruction
        assert "tool result produced a file" in instruction
        assert "trusted non-internal FileRef references one" in instruction
        assert "FileRef produced a file" not in instruction
        assert "trusted non-internal FileRef" in instruction
        assert "trusted public FileRef" not in instruction
        assert "file UUID" not in instruction
        assert "inline_markdown for screenshots" in instruction
        assert "inline image Markdown" in instruction
        assert "image intended for inline display" in instruction
        assert "different exact user-facing rendering" in instruction
        assert "verbatim" in instruction
        assert "filename and extension" in instruction
        assert "Preserve every returned file_id exactly" in instruction
        assert "Do not claim that a file was delivered" not in instruction
        assert "Never invent, guess, shorten" not in instruction
        assert "intermediate" in instruction
        assert "Never include internal FileRefs" in instruction

    assert FINAL_DELIVERABLE_INSTRUCTION_MARKER not in inline_instruction
    assert FINAL_DELIVERABLE_INSTRUCTION_MARKER in lookup_instruction
    assert FINAL_DELIVERABLE_INSTRUCTION_MARKER in forced_instruction
    assert "get_workspace_output_files" in lookup_instruction
    assert "once before finalizing" in lookup_instruction
    assert "no trusted file_id remains" in lookup_instruction
    assert "returned non-null file_id" in lookup_instruction
    assert "file_id or markdown_link" not in lookup_instruction
    assert "render [filename](file:file_id)" in lookup_instruction
    assert "matches the markdown_link form" in lookup_instruction
    assert "canonical markdown_link form" not in lookup_instruction
    assert "do not repeat the lookup" in lookup_instruction
    assert "get_workspace_output_files" not in forced_instruction
    assert "lookup is unavailable" in forced_instruction
    assert "do not reconstruct one or claim delivery" in forced_instruction
    assert "deliverable link is unavailable" in forced_instruction
    assert "lookup is unavailable" not in lookup_instruction
    assert forced_instruction not in FILE_REF_OUTPUT_INSTRUCTIONS
    assert FINAL_DELIVERABLE_INSTRUCTION_MARKER not in FILE_REF_OUTPUT_INSTRUCTIONS
    assert "get_workspace_output_files" in FILE_REF_OUTPUT_INSTRUCTIONS
    assert (
        "trusted provenance for rendering a file link." in FILE_REF_OUTPUT_INSTRUCTIONS
    )
    assert "under the final-deliverable rules" not in FILE_REF_OUTPUT_INSTRUCTIONS
    assert "Do not call final_answer claiming" in FILE_REF_OUTPUT_INSTRUCTIONS


@pytest.mark.parametrize(
    ("value", "expected"),
    [
        (None, None),
        ("", None),
        ("file:", None),
        ("file://", None),
        (
            "file:355f1fee-48e4-4cb6-afd3-71654e2f5c7e",
            "355f1fee-48e4-4cb6-afd3-71654e2f5c7e",
        ),
        (
            "file://355f1fee-48e4-4cb6-afd3-71654e2f5c7e",
            "355f1fee-48e4-4cb6-afd3-71654e2f5c7e",
        ),
        ("file://legacy%20id", "legacy id"),
        ("355f1fee-48e4-4cb6-afd3-71654e2f5c7e", None),
        ("file:///Users/example/photo.jpg", None),
        ("file://server/share/photo.jpg", None),
        ("file:output/photo.jpg", None),
        ("file://[invalid", None),
        ("https://example.com/photo.jpg", None),
    ],
)
def test_parse_file_id_ref(value: str | None, expected: str | None) -> None:
    assert parse_file_id_ref(value) == expected


def test_build_file_id_ref_uses_canonical_form() -> None:
    result = build_file_id_ref("legacy id")

    assert result == "file:legacy%20id"
    assert parse_file_id_ref(result) == "legacy id"


def test_build_file_ref_uses_canonical_file_id_ref() -> None:
    result = build_file_ref(file_id="file-id", filename="report.txt")

    assert result["markdown_link"] == "[report.txt](file:file-id)"


def test_internal_file_ref_omits_public_links_after_sanitization() -> None:
    result = sanitize_file_ref_for_context(
        build_file_ref(
            file_id="internal-frame",
            filename="frame.png",
            mime_type="image/png",
            internal=True,
        )
    )

    assert result["internal"] is True
    assert result["preview_url"] is None
    assert result["download_url"] is None
    assert result["markdown_link"] is None


def test_internal_file_ref_omits_relative_path_after_sanitization() -> None:
    result = sanitize_file_ref_for_context(
        {
            **build_file_ref(
                file_id="internal-frame",
                filename="frame.png",
                mime_type="image/png",
                internal=True,
            ),
            "relative_path": (
                "temp/.xagent-internal/computer_observations/session/digest.png"
            ),
        }
    )

    assert "relative_path" not in result


def test_internal_workspace_file_ref_omits_relative_path_at_construction(
    tmp_path: Path,
) -> None:
    workspace = TaskWorkspace("task_file_ref", base_dir=str(tmp_path))
    try:
        screenshot = workspace.temp_dir / "frame.png"
        screenshot.write_bytes(b"image")

        result = build_workspace_file_ref(
            workspace=workspace,
            file_path=screenshot,
            mime_type="image/png",
            internal=True,
        )

        assert "relative_path" not in result
    finally:
        workspace.cleanup()


@pytest.mark.parametrize(
    "file_id",
    [
        "",
        ".",
        "..",
        "nested/file-id",
        "nested\\file-id",
        "nested%2Ffile-id",
        "nested%5Cfile-id",
        "%2E%2E",
    ],
)
def test_build_file_id_ref_rejects_path_like_values(file_id: str) -> None:
    with pytest.raises(ValueError):
        build_file_id_ref(file_id)


@pytest.mark.parametrize(
    "relative_path",
    [
        r"C:\Users\name\file.png",
        r"..\secret.png",
        r"images\..\secret.png",
        r"\\server\share\file.png",
        r"\rooted\file.png",
    ],
)
def test_context_file_ref_rejects_windows_shaped_paths(relative_path: str) -> None:
    result = sanitize_file_ref_for_context(
        {
            "file_id": "image-1",
            "filename": "frame.png",
            "mime_type": "image/png",
            "relative_path": relative_path,
        }
    )

    assert "relative_path" not in result


def test_context_file_ref_normalizes_safe_windows_separators() -> None:
    result = sanitize_file_ref_for_context(
        {
            "file_id": "image-1",
            "filename": "frame.png",
            "mime_type": "image/png",
            "relative_path": r"images\frame.png",
        }
    )

    assert result["relative_path"] == "images/frame.png"


class DurableOnlyWorkspace:
    def __init__(self, root: Path) -> None:
        self.workspace_dir = root
        self.register_calls = 0

    def get_file_id_from_path(self, path: str) -> None:
        return None

    def register_file(self, path: str) -> str:
        self.register_calls += 1
        return "durable-file"


def test_internal_workspace_file_ref_fails_closed(tmp_path: Path) -> None:
    workspace = DurableOnlyWorkspace(tmp_path)
    screenshot = tmp_path / "frame.png"
    screenshot.write_bytes(b"image")

    with pytest.raises(TypeError, match="internal file registration"):
        build_workspace_file_ref(
            workspace=workspace,
            file_path=screenshot,
            mime_type="image/png",
            internal=True,
        )

    assert workspace.register_calls == 0


def test_workspace_issues_scoped_instagram_media_url(
    monkeypatch, tmp_path: Path
) -> None:
    from xagent.core.storage import manager
    from xagent.web.services import external_media

    workspace = TaskWorkspace("web_task_11", str(tmp_path), db_task_id=11)
    workspace.owner_user_id = 7
    captured = {}

    class FakeDB:
        closed = False

        def close(self):
            self.closed = True

    db = FakeDB()

    def issue(db_session, **kwargs):
        captured.update(kwargs)
        assert db_session is db
        return external_media.ExternalMediaURL(
            url="https://api.example.test/media?ticket=short-lived",
            expires_in=600,
            direct_object_url=False,
        )

    monkeypatch.setattr(manager, "create_db_session", lambda: db)
    monkeypatch.setattr(external_media, "issue_external_media_url", issue)

    result = workspace.issue_external_media_url_detached(
        "31218a9f-1497-4216-9f75-1fc8d51368c4",
        "instagram-publish",
    )

    assert result == "https://api.example.test/media?ticket=short-lived"
    assert captured == {
        "file_id": "31218a9f-1497-4216-9f75-1fc8d51368c4",
        "user_id": 7,
        "task_id": 11,
        "purpose": external_media.ExternalMediaPurpose.INSTAGRAM_PUBLISH,
    }
    assert db.closed is True


@pytest.mark.parametrize(
    ("service_error", "expected_error", "message"),
    [
        ("not_found", FileNotFoundError, "Registered image was not found"),
        ("unavailable", ValueError, "Image could not be decoded"),
    ],
)
def test_workspace_maps_external_media_errors(
    monkeypatch,
    tmp_path: Path,
    service_error: str,
    expected_error: type[Exception],
    message: str,
) -> None:
    from xagent.core.storage import manager
    from xagent.web.services import external_media

    workspace = TaskWorkspace("web_task_11", str(tmp_path), db_task_id=11)
    workspace.owner_user_id = 7

    class FakeDB:
        closed = False

        def close(self):
            self.closed = True

    db = FakeDB()

    def issue(*args, **kwargs):
        if service_error == "not_found":
            raise external_media.ExternalMediaNotFound("hidden")
        raise external_media.ExternalMediaUnavailable(message)

    monkeypatch.setattr(manager, "create_db_session", lambda: db)
    monkeypatch.setattr(external_media, "issue_external_media_url", issue)

    with pytest.raises(expected_error, match=message) as raised:
        workspace.issue_external_media_url_detached(
            "31218a9f-1497-4216-9f75-1fc8d51368c4",
            "instagram-publish",
        )

    from xagent.core.workspace import ExternalMediaNotIssuableError

    # Neither is "cannot be issued": not found stays FileNotFoundError, which
    # the adapter handles on its own, and a base ExternalMediaUnavailable (a
    # read, integrity or storage failure) stays a ValueError, which does not
    # fall back.
    assert not isinstance(raised.value, ExternalMediaNotIssuableError)
    assert db.closed is True


@pytest.mark.parametrize(
    "service_error", ["not_configured", "unsupported_image", "out_of_scope"]
)
def test_workspace_marks_external_media_that_cannot_be_issued(
    monkeypatch, tmp_path: Path, service_error: str
) -> None:
    # Why: this error tells the adapter that the file exists in this task but
    # gets no URL, so it falls back to a connector upload. A missing base URL,
    # an unsupported image (wrong type, too large, or bytes that do not
    # decode) and bytes out of external media's scope must all map to it; a
    # base ExternalMediaUnavailable must not (see
    # test_workspace_maps_external_media_errors).
    # The adapter also falls back on FileNotFoundError and on a path that is
    # not a registered file.
    from xagent.core.storage import manager
    from xagent.core.workspace import ExternalMediaNotIssuableError
    from xagent.web.services import external_media

    workspace = TaskWorkspace("web_task_11", str(tmp_path), db_task_id=11)
    workspace.owner_user_id = 7
    error = {
        "not_configured": external_media.ExternalMediaNotConfigured,
        "unsupported_image": external_media.ExternalMediaUnsupportedImage,
        "out_of_scope": external_media.ExternalMediaOutOfScope,
    }[service_error]

    def issue(*args, **kwargs):
        raise error("cannot be issued")

    monkeypatch.setattr(
        manager, "create_db_session", lambda: SimpleNamespace(close=lambda: None)
    )
    monkeypatch.setattr(external_media, "issue_external_media_url", issue)

    with pytest.raises(ExternalMediaNotIssuableError, match="cannot be issued"):
        workspace.issue_external_media_url_detached(
            "31218a9f-1497-4216-9f75-1fc8d51368c4", "facebook-publish"
        )


def test_workspace_external_media_requires_database_scope(tmp_path: Path) -> None:
    workspace = TaskWorkspace("local_task", str(tmp_path))

    with pytest.raises(FileNotFoundError, match="Registered image was not found"):
        workspace.issue_external_media_url_detached(
            "31218a9f-1497-4216-9f75-1fc8d51368c4",
            "instagram-publish",
        )