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