Skip to content

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

11.8 KB
Raw Blame
"""Slice 4 of #757: scope propagation to nested and delegated executions.

Covers the AgentTool construction-time scope snapshot, the workforce
task-config scope persistence (``agent_config`` JSON, no schema migration),
the Task-backed snapshot loader, and the per-task resolution's
resolver/snapshot precedence — including across a simulated process
restart.

With a resolver registered, the
persisted snapshot is a corroborating *candidate* for the resolver's
authoritative answer, not an override of it (a namespace-affecting
disagreement fails the turn instead of the snapshot silently winning). With
no resolver registered — the case that matters for standalone/workforce
restart-and-resume — the snapshot is still the sole answer, byte-identical
to before. See ``TestSnapshotCandidatePrecedence`` below and
``tests/core/test_execution_scope.py::TestSnapshotCandidateAuthority`` for
the full precedence matrix.

The resolver/snapshot-loader globals are reset by the root-level
``isolate_execution_scope_hooks`` autouse fixture in ``tests/conftest.py``,
not by a fixture in this module.
"""

import contextvars
from unittest.mock import MagicMock

import pytest

from tests.shared.execution_scope import register_scope_resolver
from xagent.core.execution_scope import (
    EXECUTION_SCOPE_AGENT_CONFIG_KEY,
    ExecutionScope,
    ExecutionScopeAuthorityError,
    ExecutionScopeContext,
    get_execution_scope,
    resolve_execution_scope,
    set_execution_scope_snapshot_loader,
    turn_execution_scope,
)
from xagent.core.tools.adapters.vibe.agent_tool import AgentTool
from xagent.web.services.workforce_snapshot import build_workforce_task_config

SCOPE = ExecutionScope(
    sandbox_key_suffix="tenant-a",
    workspace_segments=("tenant-a",),
    memory_dimensions={"tenant": "a"},
)


class TestScopeSerialization:
    def test_round_trip(self):
        assert ExecutionScope.from_dict(SCOPE.to_dict()) == SCOPE

    def test_from_dict_revalidates(self):
        data = SCOPE.to_dict()
        data["workspace_segments"] = ["../escape"]
        with pytest.raises(Exception):
            ExecutionScope.from_dict(data)

    def test_to_dict_is_json_serializable(self):
        import json

        assert json.loads(json.dumps(SCOPE.to_dict())) == SCOPE.to_dict()


class TestAgentToolSnapshot:
    def _tool(self, **kwargs) -> AgentTool:
        return AgentTool(
            agent_id=7,
            agent_name="a",
            agent_description="d",
            session_factory=MagicMock(),
            user_id=1,
            **kwargs,
        )

    def test_captures_ambient_scope_at_construction(self):
        with ExecutionScopeContext(SCOPE):
            tool = self._tool()
        assert tool._execution_scope is SCOPE

    def test_explicit_scope_wins_over_ambient(self):
        other = ExecutionScope(sandbox_key_suffix="tenant-b")
        with ExecutionScopeContext(other):
            tool = self._tool(execution_scope=SCOPE)
        assert tool._execution_scope is SCOPE

    def test_unscoped_construction_snapshots_none(self):
        assert self._tool()._execution_scope is None


class TestWorkforceTaskConfigSnapshot:
    def test_scope_persisted_when_active(self):
        with ExecutionScopeContext(SCOPE):
            config = build_workforce_task_config(
                {"workforce": {"id": 3}}, workforce_run_id=9
            )
        assert config[EXECUTION_SCOPE_AGENT_CONFIG_KEY] == SCOPE.to_dict()
        assert config["workforce_run_id"] == 9

    def test_unscoped_config_is_byte_identical(self):
        config = build_workforce_task_config({"workforce": {"id": 3}})
        assert EXECUTION_SCOPE_AGENT_CONFIG_KEY not in config

    def test_persists_the_current_shape_version_not_the_ambient_scopes_version(
        self,
    ):
        """The ambient scope may itself have been decoded from an older
        persisted snapshot (``version`` stamped at 0 or some prior shape).
        Re-persisting it here for a *new* workforce sub-task must stamp the
        current shape version -- the dict is being built now, in the
        current shape -- not propagate the decoded-from scope's stale
        version, which would make this brand-new snapshot look pre-existing
        forever and get permanently ignored as a candidate by
        resolve_execution_scope's stale-version check."""
        from xagent.core.execution_scope import EXECUTION_SCOPE_SHAPE_VERSION

        legacy_data = SCOPE.to_dict()
        legacy_data["version"] = 0
        decoded_legacy_scope = ExecutionScope.from_dict(legacy_data)
        assert decoded_legacy_scope.version == 0

        with ExecutionScopeContext(decoded_legacy_scope):
            config = build_workforce_task_config({"workforce": {"id": 3}})

        assert (
            config[EXECUTION_SCOPE_AGENT_CONFIG_KEY]["version"]
            == EXECUTION_SCOPE_SHAPE_VERSION
        )


class TestSnapshotCandidatePrecedence:
    """Resolver/snapshot precedence for the resolver-registered case.

    A persisted snapshot is a candidate, not an authority. The resolver is
    authoritative and always called; the snapshot is a corroborating
    candidate -- consistent with it wins silently, but a namespace-affecting
    disagreement fails the turn instead of the snapshot winning. See
    ``tests/core/test_execution_scope.py::TestSnapshotCandidateAuthority``
    for the full precedence matrix (defer/None/ExecutionScope resolver
    values x snapshot present/absent/stale-version/corrupt).
    """

    def test_resolver_is_authoritative_and_always_called(self):
        resolver_calls = []

        def resolver(task_id):
            resolver_calls.append(task_id)
            return SCOPE

        register_scope_resolver(resolver)
        set_execution_scope_snapshot_loader(
            lambda task_id: SCOPE if task_id == "42" else None
        )

        # A snapshot equal to the resolver's answer corroborates silently.
        assert resolve_execution_scope(42) == SCOPE
        assert resolver_calls == ["42"]
        # Tasks without a snapshot still resolve through the resolver.
        assert (
            resolve_execution_scope(43).sandbox_key_suffix == SCOPE.sandbox_key_suffix
        )
        assert resolver_calls == ["42", "43"]

    def test_namespace_mismatch_between_resolver_and_snapshot_fails_the_turn(self):
        register_scope_resolver(
            lambda task_id: ExecutionScope(sandbox_key_suffix="from-resolver"),
        )
        set_execution_scope_snapshot_loader(lambda task_id: SCOPE)

        with pytest.raises(ExecutionScopeAuthorityError) as exc_info:
            resolve_execution_scope(42)
        assert exc_info.value.resolver_scope.sandbox_key_suffix == "from-resolver"
        assert exc_info.value.snapshot_scope == SCOPE
        assert "sandbox_key_suffix" in exc_info.value.mismatched_fields

    def test_caller_supplied_agent_config_skips_registered_loader(self):
        """A caller that already read the task row hands over the raw
        ``agent_config``; the snapshot inside it is decoded here rather than by
        the caller, so a malformed one is tolerated or fatal per branch."""
        loader_calls = []
        set_execution_scope_snapshot_loader(
            lambda task_id: loader_calls.append(task_id)
        )

        resolved = resolve_execution_scope(
            42,
            persisted_agent_config={EXECUTION_SCOPE_AGENT_CONFIG_KEY: SCOPE.to_dict()},
        )
        assert resolved == SCOPE
        assert loader_calls == []

    def test_caller_supplied_missing_agent_config_leaves_resolver_authoritative(self):
        loader_calls = []
        resolver_calls = []
        resolved = ExecutionScope(sandbox_key_suffix="from-resolver")
        set_execution_scope_snapshot_loader(
            lambda task_id: loader_calls.append(task_id)
        )
        register_scope_resolver(
            lambda task_id: resolver_calls.append(task_id) or resolved,
        )

        # Explicit ``None`` means "this task carries no agent_config", which
        # leaves the resolver's answer standing rather than forcing unscoped.
        assert resolve_execution_scope(42, persisted_agent_config=None) == resolved
        assert loader_calls == []
        assert resolver_calls == ["42"]

    def test_loader_exception_fails_the_turn_with_no_resolver_registered(self):
        def loader(task_id):
            raise RuntimeError("db down")

        set_execution_scope_snapshot_loader(loader)
        with pytest.raises(RuntimeError, match="db down"):
            resolve_execution_scope(42)

    def test_loader_exception_does_not_veto_resolver_authority(self):
        """A broken snapshot candidate must not veto an already-given
        authoritative resolver answer."""
        resolved = ExecutionScope(sandbox_key_suffix="from-resolver")

        def loader(task_id):
            raise RuntimeError("db down")

        set_execution_scope_snapshot_loader(loader)
        register_scope_resolver(
            lambda task_id: resolved,
        )

        assert resolve_execution_scope(42) == resolved

    def test_delegated_subtask_executes_scoped_after_restart(self):
        """A sub-task of a scoped parent executes fully scoped after a
        process restart: the snapshot persisted at creation is re-loaded
        per turn, with no resolver knowing the internal task id."""
        persisted = {"42": SCOPE.to_dict()}  # the agent_config JSON store

        def run_turn():
            # Fresh process: the loader is registered at startup; no
            # resolver mapping exists for the internally created task id.
            set_execution_scope_snapshot_loader(
                lambda task_id: (
                    ExecutionScope.from_dict(persisted[task_id])
                    if task_id in persisted
                    else None
                )
            )
            with turn_execution_scope("42"):
                return get_execution_scope()

        first = contextvars.copy_context().run(run_turn)
        set_execution_scope_snapshot_loader(None)
        second = contextvars.copy_context().run(run_turn)

        assert first == SCOPE
        assert first == second


class TestTaskBackedSnapshotLoader:
    @pytest.fixture
    def db_session(self, tmp_path):
        from xagent.web.models.database import Base, get_db, get_engine, init_db

        init_db(db_url=f"sqlite:///{tmp_path / 'scope_snapshot.db'}")
        db = next(get_db())
        try:
            yield db
        finally:
            db.close()
            Base.metadata.drop_all(bind=get_engine())

    def _make_task(self, db, agent_config):
        from xagent.web.models.task import Task, TaskStatus
        from xagent.web.models.user import User

        user = User(username="scope-user", password_hash="x")
        db.add(user)
        db.commit()
        task = Task(
            user_id=int(user.id),
            title="t",
            description="d",
            status=TaskStatus.PENDING,
            agent_config=agent_config,
        )
        db.add(task)
        db.commit()
        db.refresh(task)
        return task

    def test_loads_persisted_snapshot(self, db_session):
        from xagent.web.services.execution_scope_snapshot import (
            load_task_execution_scope_snapshot,
        )

        task = self._make_task(
            db_session, {EXECUTION_SCOPE_AGENT_CONFIG_KEY: SCOPE.to_dict()}
        )
        assert load_task_execution_scope_snapshot(str(task.id)) == SCOPE

    def test_task_without_snapshot_returns_none(self, db_session):
        from xagent.web.services.execution_scope_snapshot import (
            load_task_execution_scope_snapshot,
        )

        task = self._make_task(db_session, {"workforce_run_id": 9})
        assert load_task_execution_scope_snapshot(str(task.id)) is None

    def test_non_integer_task_id_returns_none(self, db_session):
        from xagent.web.services.execution_scope_snapshot import (
            load_task_execution_scope_snapshot,
        )

        assert load_task_execution_scope_snapshot("agent_7_ab12cd34") is None