Skip to content

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

6.8 KB
Raw Blame
"""AST guard: every production ``Task(...)`` picks its storage version.

New creation sites must choose deliberately: either route through
``new_task_conversation_storage_version`` with a pinned entry name, or be an
allowlisted legacy path fixed at version 1.
"""

from __future__ import annotations

import ast
import sys
from pathlib import Path

import pytest

import xagent.config as _config_module
from xagent.web.models.task import Task

pytestmark = pytest.mark.skipif(
    sys.version_info < (3, 11),
    reason="AST guards require Python >= 3.11 to parse this codebase's syntax",
)

_SRC_ROOT = Path(_config_module.__file__).parent
_TASK_MODULE = "xagent.web.models.task"
_SELECTOR = "new_task_conversation_storage_version"

# (file relative to src/xagent, enclosing function) -> entry names used.
EXPECTED_SELECTOR_SITES: dict[tuple[str, str], frozenset[str]] = {
    ("web/api/chat.py", "create_task"): frozenset({"web_chat", "agent_preview"}),
    ("web/api/public_chat_access.py", "create_public_chat_task"): frozenset({"widget"}),
    ("web/api/public_chat_access.py", "create_share_chat_task"): frozenset(
        {"shared_link"}
    ),
    ("web/services/task_start.py", "_prepare_created_task_isolated"): frozenset(
        {"sdk"}
    ),
    ("web/services/task_start.py", "_prepare_a2a_turn_sync"): frozenset({"a2a"}),
    ("web/services/channel_runtime.py", "prepare_channel_task_no_commit"): frozenset(
        {"channel"}
    ),
    ("web/services/triggers.py", "_attach_task_to_trigger_run"): frozenset({"trigger"}),
    ("web/services/workforce_runs.py", "_create_run_and_task_no_commit"): frozenset(
        {"workforce"}
    ),
}

# Legacy paths fixed at version 1 (never rolled out).
EXPECTED_FIXED_V1_SITES: frozenset[tuple[str, str]] = frozenset(
    {
        ("web/services/task_command_execution.py", "_prepare_task_message_sync"),
        ("web/services/agent_service_manager.py", "_get_agent_for_task_unlocked"),
    }
)


class _Finder(ast.NodeVisitor):
    def __init__(self) -> None:
        self.task_names: set[str] = set()
        self.stack: list[str] = []
        self.sites: list[tuple[str, ast.Call]] = []

    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
        self.stack.append(node.name)
        self.generic_visit(node)
        self.stack.pop()

    visit_AsyncFunctionDef = visit_FunctionDef  # type: ignore[assignment]

    def visit_Call(self, node: ast.Call) -> None:
        func = node.func
        # A bare imported name, or any ``<module>.Task(...)``: ``src/xagent``
        # constructs no other ``Task`` through an attribute (``asyncio.Task``
        # is created via ``create_task``), so this has no false positives.
        if (isinstance(func, ast.Name) and func.id in self.task_names) or (
            isinstance(func, ast.Attribute) and func.attr == "Task"
        ):
            self.sites.append((self.stack[-1] if self.stack else "<module>", node))
        self.generic_visit(node)


def _resolve_task_imports(tree: ast.Module, path: Path) -> set[str]:
    """Names bound to the Task model, resolving relative imports."""
    rel = path.relative_to(_SRC_ROOT.parent).with_suffix("")
    package = list(rel.parts[:-1])
    names: set[str] = set()
    for node in ast.walk(tree):
        if not isinstance(node, ast.ImportFrom):
            continue
        if node.level:
            base = package[: len(package) - (node.level - 1)]
            module = ".".join(base + ([node.module] if node.module else []))
        else:
            module = node.module or ""
        if module == _TASK_MODULE:
            names.update(a.asname or a.name for a in node.names if a.name == "Task")
        elif module == "xagent.web.models":
            names.update(a.asname or a.name for a in node.names if a.name == "Task")
    return names


def _scan() -> list[tuple[str, str, ast.Call]]:
    found: list[tuple[str, str, ast.Call]] = []
    for path in sorted(_SRC_ROOT.rglob("*.py")):
        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
        finder = _Finder()
        finder.task_names = _resolve_task_imports(tree, path)
        finder.visit(tree)
        rel = path.relative_to(_SRC_ROOT).as_posix()
        found.extend((rel, func, call) for func, call in finder.sites)
    return found


def _version_value(call: ast.Call) -> ast.expr | None:
    for keyword in call.keywords:
        if keyword.arg == "conversation_storage_version":
            return keyword.value
    return None


def _selector_calls(expr: ast.expr) -> list[ast.Call]:
    return [
        node
        for node in ast.walk(expr)
        if isinstance(node, ast.Call)
        and isinstance(node.func, ast.Name)
        and node.func.id == _SELECTOR
    ]


def _entry_names(selector_call: ast.Call) -> set[str]:
    entry = next((k.value for k in selector_call.keywords if k.arg == "entry"), None)
    assert entry is not None, "selector call must pass entry= by keyword"
    return _constants(entry)


def _constants(expr: ast.expr) -> set[str]:
    """String constants of a constant or a conditional between constants."""
    if isinstance(expr, ast.Constant) and isinstance(expr.value, str):
        return {expr.value}
    if isinstance(expr, ast.IfExp):
        return _constants(expr.body) | _constants(expr.orelse)
    raise AssertionError("entry= must be a string constant (or a conditional of them)")


def test_every_task_construction_sets_conversation_storage_version() -> None:
    sites = _scan()
    assert sites, "scan found no Task(...) constructions; the guard is broken"
    problems = []
    selector_sites: dict[tuple[str, str], set[str]] = {}
    fixed_v1: set[tuple[str, str]] = set()
    for rel, func, call in sites:
        value = _version_value(call)
        where = f"{rel}:{call.lineno} in {func}"
        if value is None:
            problems.append(f"{where}: missing conversation_storage_version=")
            continue
        selectors = _selector_calls(value)
        if selectors:
            assert len(selectors) == 1, where
            selector_sites.setdefault((rel, func), set()).update(
                _entry_names(selectors[0])
            )
        elif isinstance(value, ast.Constant) and value.value == 1:
            fixed_v1.add((rel, func))
        else:
            problems.append(f"{where}: must call {_SELECTOR} or be the literal 1")
    assert not problems, "\n".join(problems)

    assert {k: frozenset(v) for k, v in selector_sites.items()} == (
        EXPECTED_SELECTOR_SITES
    )
    assert fixed_v1 == EXPECTED_FIXED_V1_SITES
    # Every construction is accounted for: one site per expected (file, function).
    assert len(sites) == len(EXPECTED_SELECTOR_SITES) + len(EXPECTED_FIXED_V1_SITES)


def test_column_default_and_server_default_remain_legacy() -> None:
    column = Task.__table__.c.conversation_storage_version
    assert column.default.arg == 1
    assert str(column.server_default.arg) == "1"