Skip to content

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

24.5 KB
Raw Blame
"""What the retention purge leaves behind for readers (#2565).

Runs on SQLite and PostgreSQL through the shared ``engine`` fixture, like the
other purge tests: the ``ON DELETE SET NULL`` the tombstone must read ahead of,
the account-deletion cascade and the pinned ``onupdate`` columns are all
behaviours worth seeing on both.
"""

from __future__ import annotations

import itertools
from datetime import datetime, timedelta, timezone

import pytest
import sqlalchemy as sa
from sqlalchemy.orm import Session, sessionmaker

from tests.web.services.task_database_shared import engine as engine_fixture
from xagent.web.models.agent import Agent
from xagent.web.models.database import Base
from xagent.web.models.expired_task import ExpiredTaskTombstone
from xagent.web.models.task import Task, TaskStatus, TraceEvent
from xagent.web.models.trigger import AgentTrigger, TriggerRun, TriggerType
from xagent.web.models.user import User
from xagent.web.models.workforce import Workforce, WorkforceRun
from xagent.web.services.expired_tasks import find_expired_task
from xagent.web.services.task_deletion import purge_task_rows
from xagent.web.services.task_retention_purge import (
    RetentionPurgeAction,
    purge_task,
)
from xagent.web.services.task_runtime import (
    MCP_RUNTIME_AUTHORIZATION_POLICY_REQUIRED_KEY,
    mcp_runtime_authorization_policy_required_clause,
)

engine = engine_fixture

NOW = datetime(2026, 9, 26, 12, 0, 0, tzinfo=timezone.utc)
CONVERSATION_DAYS = 365
TRACE_DAYS = 90
#: A fixed clock for the rows' own ``onupdate`` columns, far from :data:`NOW`,
#: so a write that let them fire is visible as a changed value.
EARLIER = datetime(2025, 1, 1, 0, 0, 0, tzinfo=timezone.utc)


@pytest.fixture(autouse=True)
def _no_inherited_retention_env(monkeypatch):
    from xagent import config as _config

    for name in _config.RETENTION_ENV_VARS:
        monkeypatch.delenv(name, raising=False)


@pytest.fixture
def sessions(engine) -> sessionmaker[Session]:
    Base.metadata.create_all(engine)
    return sa.orm.sessionmaker(bind=engine, autoflush=False)


def _as_utc(value: datetime | None) -> datetime | None:
    """SQLite drops the offset on the way back; PostgreSQL keeps it."""
    if value is None or value.tzinfo is not None:
        return value
    return value.replace(tzinfo=timezone.utc)


def _make_user(db: Session, username: str = "owner") -> int:
    user = User(username=username, password_hash="unused")
    db.add(user)
    db.flush()
    return int(user.id)


#: ``agents.(user_id, name)`` is unique; a test that makes more than one agent
#: for the same user needs distinct names.
_agent_name_seq = itertools.count()


def _make_agent(db: Session, user_id: int) -> int:
    agent = Agent(user_id=user_id, name=f"agent-{user_id}-{next(_agent_name_seq)}")
    db.add(agent)
    db.flush()
    return int(agent.id)


def _make_task(
    db: Session,
    *,
    user_id: int,
    days_old: int,
    agent_id: int | None = None,
    source: str = "sdk",
    is_visible: bool = True,
    agent_config: dict | None = None,
) -> int:
    task = Task(
        user_id=user_id,
        title="expired-task fixture",
        status=TaskStatus.COMPLETED,
        last_activity_at=NOW - timedelta(days=days_old),
        created_at=NOW - timedelta(days=days_old + 1),
        agent_id=agent_id,
        source=source,
        is_visible=is_visible,
        agent_config=agent_config,
    )
    db.add(task)
    db.flush()
    return int(task.id)


def _make_trace(db: Session, task_id: int, suffix: str = "1") -> None:
    db.add(
        TraceEvent(
            task_id=task_id,
            event_id=f"evt-{task_id}-{suffix}",
            event_type="task_start",
            timestamp=NOW,
            data={},
        )
    )
    db.flush()


def _make_workforce_run(db: Session, *, user_id: int, task_id: int) -> tuple[int, int]:
    manager_id = _make_agent(db, user_id)
    workforce = Workforce(
        owner_user_id=user_id,
        scope_type="user",
        scope_id=str(user_id),
        name="expiry workforce",
        manager_agent_id=manager_id,
        status="active",
    )
    db.add(workforce)
    db.flush()
    run = WorkforceRun(
        workforce_id=workforce.id,
        task_id=task_id,
        user_id=user_id,
        status="completed",
        snapshot={"version": 1},
        last_activity_at=EARLIER,
    )
    db.add(run)
    db.flush()
    return int(workforce.id), int(run.id)


def _make_trigger_run(
    db: Session,
    *,
    user_id: int,
    agent_id: int,
    task_id: int,
    key: str = "run-1",
    trigger_type: str = TriggerType.SCHEDULED.value,
) -> int:
    trigger = AgentTrigger(
        user_id=user_id,
        agent_id=agent_id,
        type=trigger_type,
        name="expiry trigger",
        config={"interval_seconds": 60},
    )
    db.add(trigger)
    db.flush()
    run = TriggerRun(
        trigger_id=trigger.id,
        task_id=task_id,
        status="completed",
        idempotency_key=key,
        updated_at=EARLIER,
    )
    db.add(run)
    db.flush()
    return int(run.id)


def _purge(db: Session, task_id: int, *, dry_run: bool = False) -> RetentionPurgeAction:
    return purge_task(
        db,
        task_id,
        now=NOW,
        conversation_days=CONVERSATION_DAYS,
        trace_days=TRACE_DAYS,
        dry_run=dry_run,
    )


# --- conversation expiry -------------------------------------------------------


def test_conversation_expiry_leaves_a_content_free_tombstone(sessions) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        task_id = _make_task(
            db, user_id=user_id, days_old=400, agent_id=agent_id, is_visible=False
        )
        created_at = db.get(Task, task_id).created_at
        db.commit()

        assert _purge(db, task_id) is RetentionPurgeAction.PURGED_CONVERSATION

    with sessions() as db:
        assert db.get(Task, task_id) is None
        tombstone = db.get(ExpiredTaskTombstone, task_id)
        assert tombstone is not None
        assert tombstone.user_id == user_id
        assert tombstone.agent_id == agent_id
        assert tombstone.workforce_id is None
        assert tombstone.source == "sdk"
        assert tombstone.trigger_type is None
        assert tombstone.is_visible is False
        assert tombstone.is_channel_plumbing is False
        assert _as_utc(tombstone.task_created_at) == _as_utc(created_at)
        assert _as_utc(tombstone.expired_at) == NOW
        # Nothing but predicate inputs and timestamps: no title, description,
        # input or config can be carried across.
        assert set(ExpiredTaskTombstone.__table__.columns.keys()) == {
            "task_id",
            "user_id",
            "agent_id",
            "workforce_id",
            "source",
            "sdk_credential_kind",
            "trigger_type",
            "is_visible",
            "is_channel_plumbing",
            "task_created_at",
            "expired_at",
        }


@pytest.mark.parametrize("marker", [True, False, "true", 1, None])
def test_only_a_literal_true_marker_is_channel_plumbing(sessions, marker) -> None:
    """The stored flag equals whatever the live Conversation Logs predicate says.

    ``True``, ``False`` and a missing key have a known answer -- only a
    literal ``True`` counts -- so those are pinned directly. ``"true"`` and
    ``1`` are not literal booleans, and ``as_boolean()``'s reading of a
    non-boolean JSON value is dialect-specific; asserting a hardcoded answer
    for those would pin one dialect's behaviour rather than the invariant
    that actually matters: the tombstone's flag and the live predicate must
    agree, whatever a given dialect makes of the value.
    """
    config = (
        {}
        if marker is None
        else {MCP_RUNTIME_AUTHORIZATION_POLICY_REQUIRED_KEY: marker}
    )
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=400, agent_config=config)
        db.commit()
        live_predicate = db.execute(
            sa.select(mcp_runtime_authorization_policy_required_clause().is_(True))
            .select_from(Task)
            .where(Task.id == task_id)
        ).scalar_one()
        if marker is True or marker is False or marker is None:
            assert live_predicate is (marker is True)
        _purge(db, task_id)

    with sessions() as db:
        tombstone = db.get(ExpiredTaskTombstone, task_id)
        assert tombstone.is_channel_plumbing is live_predicate


def test_the_workforce_is_read_before_the_delete_clears_the_run_pointer(
    sessions,
) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=400)
        workforce_id, run_id = _make_workforce_run(db, user_id=user_id, task_id=task_id)
        db.commit()

        _purge(db, task_id)

    with sessions() as db:
        assert db.get(ExpiredTaskTombstone, task_id).workforce_id == workforce_id
        run = db.get(WorkforceRun, run_id)
        assert run.task_id is None
        assert _as_utc(run.task_expired_at) == NOW
        # The outcome of the run is not the expiry's to change.
        assert run.status == "completed"
        # The preview-run reaper reads this; an expiry must not freshen it.
        assert _as_utc(run.last_activity_at) == EARLIER


def test_trigger_runs_are_marked_without_touching_their_status_or_clock(
    sessions,
) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        task_id = _make_task(db, user_id=user_id, days_old=400, agent_id=agent_id)
        run_id = _make_trigger_run(
            db, user_id=user_id, agent_id=agent_id, task_id=task_id
        )
        db.commit()

        _purge(db, task_id)

    with sessions() as db:
        run = db.get(TriggerRun, run_id)
        assert run.task_id is None
        assert _as_utc(run.task_expired_at) == NOW
        assert run.status == "completed"
        assert _as_utc(run.updated_at) == EARLIER


def test_runs_of_other_tasks_are_not_marked(sessions) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        expired = _make_task(db, user_id=user_id, days_old=400, agent_id=agent_id)
        kept = _make_task(db, user_id=user_id, days_old=10, agent_id=agent_id)
        kept_run = _make_trigger_run(
            db, user_id=user_id, agent_id=agent_id, task_id=kept, key="kept"
        )
        db.commit()

        _purge(db, expired)

    with sessions() as db:
        run = db.get(TriggerRun, kept_run)
        assert run.task_id == kept
        assert run.task_expired_at is None


# --- trigger_type ---------------------------------------------------------------


def test_trigger_type_reads_the_agent_config_key_first(sessions) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        task_id = _make_task(
            db,
            user_id=user_id,
            days_old=400,
            agent_id=agent_id,
            source="trigger",
            agent_config={"trigger_type": "webhook"},
        )
        # A run of a different type is also present; the config key wins.
        _make_trigger_run(
            db,
            user_id=user_id,
            agent_id=agent_id,
            task_id=task_id,
            trigger_type=TriggerType.SCHEDULED.value,
        )
        db.commit()
        _purge(db, task_id)

    with sessions() as db:
        assert db.get(ExpiredTaskTombstone, task_id).trigger_type == "webhook"


def test_trigger_type_falls_back_to_the_trigger_run(sessions) -> None:
    """No ``agent_config`` key: the run's own trigger supplies the type."""
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        task_id = _make_task(
            db, user_id=user_id, days_old=400, agent_id=agent_id, source="trigger"
        )
        _make_trigger_run(
            db,
            user_id=user_id,
            agent_id=agent_id,
            task_id=task_id,
            trigger_type=TriggerType.GMAIL.value,
        )
        db.commit()
        _purge(db, task_id)

    with sessions() as db:
        assert db.get(ExpiredTaskTombstone, task_id).trigger_type == "gmail"


def test_trigger_type_uses_the_highest_id_run_when_two_point_at_the_task(
    sessions,
) -> None:
    """``trigger_runs.task_id`` is not unique; the newest run's trigger wins."""
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        task_id = _make_task(
            db, user_id=user_id, days_old=400, agent_id=agent_id, source="trigger"
        )
        _make_trigger_run(
            db,
            user_id=user_id,
            agent_id=agent_id,
            task_id=task_id,
            key="first",
            trigger_type=TriggerType.SCHEDULED.value,
        )
        _make_trigger_run(
            db,
            user_id=user_id,
            agent_id=agent_id,
            task_id=task_id,
            key="second",
            trigger_type=TriggerType.WEBHOOK.value,
        )
        db.commit()
        _purge(db, task_id)

    with sessions() as db:
        assert db.get(ExpiredTaskTombstone, task_id).trigger_type == "webhook"


def test_trigger_type_is_null_for_a_non_trigger_task(sessions) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=400)
        db.commit()
        _purge(db, task_id)

    with sessions() as db:
        assert db.get(ExpiredTaskTombstone, task_id).trigger_type is None


def test_a_dry_run_records_nothing(sessions) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        task_id = _make_task(db, user_id=user_id, days_old=400, agent_id=agent_id)
        run_id = _make_trigger_run(
            db, user_id=user_id, agent_id=agent_id, task_id=task_id
        )
        _workforce_id, workforce_run_id = _make_workforce_run(
            db, user_id=user_id, task_id=task_id
        )
        db.commit()

        assert (
            _purge(db, task_id, dry_run=True)
            is RetentionPurgeAction.PURGED_CONVERSATION
        )

    with sessions() as db:
        assert db.get(Task, task_id) is not None
        assert db.get(ExpiredTaskTombstone, task_id) is None
        assert db.get(TriggerRun, run_id).task_expired_at is None
        assert db.get(WorkforceRun, workforce_run_id).task_expired_at is None


def test_a_refused_task_records_nothing(sessions) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=400)
        db.get(Task, task_id).status = TaskStatus.RUNNING
        db.commit()

        assert _purge(db, task_id) is RetentionPurgeAction.SKIPPED_BUSY

    with sessions() as db:
        assert db.get(ExpiredTaskTombstone, task_id) is None


def test_a_failed_purge_rolls_the_records_back_with_the_delete(
    sessions, monkeypatch
) -> None:
    """Records and delete commit together, or a reader is told a lie."""
    import xagent.web.services.task_retention_purge as purge_module

    def fail(*_args, **_kwargs):
        raise RuntimeError("delete failed")

    monkeypatch.setattr(purge_module, "purge_task_rows", fail)
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        task_id = _make_task(db, user_id=user_id, days_old=400, agent_id=agent_id)
        run_id = _make_trigger_run(
            db, user_id=user_id, agent_id=agent_id, task_id=task_id
        )
        db.commit()

        with pytest.raises(RuntimeError, match="delete failed"):
            _purge(db, task_id)

    with sessions() as db:
        assert db.get(Task, task_id) is not None
        assert db.get(ExpiredTaskTombstone, task_id) is None
        assert db.get(TriggerRun, run_id).task_expired_at is None


def test_user_initiated_deletion_records_nothing(sessions) -> None:
    """An owner's delete keeps answering not-found: no tombstone, no marker."""
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        task_id = _make_task(db, user_id=user_id, days_old=400, agent_id=agent_id)
        run_id = _make_trigger_run(
            db, user_id=user_id, agent_id=agent_id, task_id=task_id
        )
        db.commit()

        purge_task_rows(db, task_id=task_id, detached_reason="task_deleted")
        db.commit()

    with sessions() as db:
        assert db.get(ExpiredTaskTombstone, task_id) is None
        run = db.get(TriggerRun, run_id)
        assert run.task_id is None
        assert run.task_expired_at is None


# --- tombstone lifecycle -------------------------------------------------------


def _expire_one(sessions) -> tuple[int, int, int]:
    with sessions() as db:
        user_id = _make_user(db)
        agent_id = _make_agent(db, user_id)
        task_id = _make_task(db, user_id=user_id, days_old=400, agent_id=agent_id)
        db.commit()
        _purge(db, task_id)
    return user_id, agent_id, task_id


def test_account_deletion_removes_the_tombstone(sessions) -> None:
    user_id, agent_id, task_id = _expire_one(sessions)
    with sessions() as db:
        db.execute(sa.delete(Agent).where(Agent.id == agent_id))
        db.execute(sa.delete(User).where(User.id == user_id))
        db.commit()

    with sessions() as db:
        assert db.get(ExpiredTaskTombstone, task_id) is None


def test_the_account_deletion_path_removes_the_tombstone(
    sessions, monkeypatch, tmp_path
) -> None:
    """Through ``admin_users``, which deletes the user via the ORM.

    The tombstone has no ORM relationship to ``User``, so it goes only by the
    database cascade; this pins that the real deletion path reaches it.
    """
    from xagent.web.api import admin_users

    monkeypatch.setenv("XAGENT_STORAGE_ROOT", str(tmp_path))
    monkeypatch.setattr(admin_users, "get_session_local", lambda: sessions)
    # No agent: this helper deletes the user without deleting its agents,
    # which is outside what is being pinned here.
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=400)
        db.commit()
        _purge(db, task_id)
    assert _find_expired_task_exists(sessions, task_id)

    assert admin_users._delete_user_rows_sync(user_id=user_id) is not None

    with sessions() as db:
        assert db.get(User, user_id) is None
        assert db.get(ExpiredTaskTombstone, task_id) is None


def _find_expired_task_exists(sessions, task_id: int) -> bool:
    with sessions() as db:
        return find_expired_task(db, task_id) is not None


def test_workforce_deletion_clears_the_tombstone_workforce(sessions) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=400)
        workforce_id, _run_id = _make_workforce_run(
            db, user_id=user_id, task_id=task_id
        )
        db.commit()
        _purge(db, task_id)

    with sessions() as db:
        db.execute(sa.delete(Workforce).where(Workforce.id == workforce_id))
        db.commit()

    with sessions() as db:
        tombstone = db.get(ExpiredTaskTombstone, task_id)
        assert tombstone is not None
        assert tombstone.workforce_id is None


def test_agent_deletion_clears_the_tombstone_agent(sessions) -> None:
    _user_id, agent_id, task_id = _expire_one(sessions)
    with sessions() as db:
        db.execute(sa.delete(Agent).where(Agent.id == agent_id))
        db.commit()

    with sessions() as db:
        tombstone = db.get(ExpiredTaskTombstone, task_id)
        assert tombstone is not None
        assert tombstone.agent_id is None


def test_find_expired_task_returns_the_tombstone(sessions) -> None:
    _user_id, _agent_id, task_id = _expire_one(sessions)
    with sessions() as db:
        tombstone = find_expired_task(db, task_id)
        assert tombstone is not None
        assert tombstone.task_id == task_id


def test_find_expired_task_never_shadows_a_live_task(sessions) -> None:
    """SQLite reuses the highest deleted id; the live task must win."""
    user_id, _agent_id, task_id = _expire_one(sessions)
    with sessions() as db:
        db.add(Task(id=task_id, user_id=user_id, title="reused id"))
        db.commit()

    with sessions() as db:
        assert find_expired_task(db, task_id) is None


def test_find_expired_task_is_none_for_an_unknown_id(sessions) -> None:
    with sessions() as db:
        assert find_expired_task(db, 424242) is None


def test_a_reused_id_is_expired_again_without_colliding(sessions) -> None:
    """SQLite reuses a deleted id; the writer must replace, not conflict.

    Only SQLite reuses the highest deleted id -- PostgreSQL never does -- but
    this writer runs on both, and any SQLite caller of it, this test suite
    included, can expire a task, insert a new one at the same id, and expire
    that one too. Without the replace, that second expiry would hit the
    tombstone's own primary key.
    """
    user_id, _agent_id, task_id = _expire_one(sessions)
    with sessions() as db:
        second_agent_id = _make_agent(db, user_id)
        db.add(
            Task(
                id=task_id,
                user_id=user_id,
                title="second task at the reused id",
                status=TaskStatus.COMPLETED,
                agent_id=second_agent_id,
                last_activity_at=NOW - timedelta(days=400),
                created_at=NOW - timedelta(days=401),
            )
        )
        db.commit()

        assert _purge(db, task_id) is RetentionPurgeAction.PURGED_CONVERSATION

    with sessions() as db:
        assert (
            db.execute(
                sa.select(sa.func.count())
                .select_from(ExpiredTaskTombstone)
                .where(ExpiredTaskTombstone.task_id == task_id)
            ).scalar_one()
            == 1
        )
        tombstone = db.get(ExpiredTaskTombstone, task_id)
        # Describes the task that just expired, not the first one.
        assert tombstone.agent_id == second_agent_id


# --- trace expiry --------------------------------------------------------------


def test_trace_expiry_stamps_traces_expired_at(sessions) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=100)
        _make_trace(db, task_id)
        # Explicitly old, the same way ``_seed_full_task`` pins it in
        # ``test_task_retention_purge.py``: this UPDATE fires ``onupdate``,
        # so leaving it at "now" would make the pin below pass whether or not
        # the purge actually left the column alone.
        db.execute(sa.update(Task).where(Task.id == task_id).values(updated_at=EARLIER))
        db.commit()

        assert _purge(db, task_id) is RetentionPurgeAction.PURGED_TRACES

    with sessions() as db:
        task = db.get(Task, task_id)
        assert _as_utc(task.traces_expired_at) == NOW
        assert _as_utc(task.updated_at) == EARLIER
        # Trace expiry keeps the task, so it leaves no tombstone.
        assert db.get(ExpiredTaskTombstone, task_id) is None


def test_a_later_trace_expiry_restamps(sessions) -> None:
    """New turns write new trace rows, which can expire in their turn."""
    later = NOW + timedelta(days=1)
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=100)
        _make_trace(db, task_id, "1")
        db.commit()
        _purge(db, task_id)

        _make_trace(db, task_id, "2")
        db.commit()
        assert (
            purge_task(
                db,
                task_id,
                now=later,
                conversation_days=CONVERSATION_DAYS,
                trace_days=TRACE_DAYS,
            )
            is RetentionPurgeAction.PURGED_TRACES
        )

    with sessions() as db:
        assert _as_utc(db.get(Task, task_id).traces_expired_at) == later


def test_nothing_to_purge_does_not_write_the_task_row(sessions) -> None:
    """No trace and no pointer: no stamp, and no dead tuple per sweep."""
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=100)
        db.commit()

        assert _purge(db, task_id) is RetentionPurgeAction.NOTHING_TO_PURGE

    with sessions() as db:
        assert db.get(Task, task_id).traces_expired_at is None


def test_trace_dry_run_does_not_stamp(sessions) -> None:
    with sessions() as db:
        user_id = _make_user(db)
        task_id = _make_task(db, user_id=user_id, days_old=100)
        _make_trace(db, task_id)
        db.commit()

        _purge(db, task_id, dry_run=True)

    with sessions() as db:
        assert db.get(Task, task_id).traces_expired_at is None