Skip to content

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

22.4 KB
Raw Blame
"""Per-team retention period overrides (#2600).

The deployment layer registers a resolver keyed by ``user_id``; the purge
applies it at both the batch scan and each task's locked assessment. Runs on
SQLite and PostgreSQL through the shared ``engine`` fixture, like the purge's
own row-level tests.
"""

from __future__ import annotations

import logging
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.database import Base
from xagent.web.models.task import Task, TaskStatus, TraceEvent
from xagent.web.models.user import User
from xagent.web.services import task_retention_overrides as overrides_module
from xagent.web.services.task_retention_overrides import (
    INHERIT,
    RETENTION_OVERRIDE_MAX_DAYS,
    RetentionOverride,
    RetentionPeriods,
    load_retention_overrides,
    resolve_task_retention_periods,
    set_retention_override_resolver,
)
from xagent.web.services.task_retention_purge import (
    RetentionPurgeAction,
    RetentionPurgeReport,
    purge_task,
    run_retention_purge_batch,
    select_purge_candidates,
)

engine = engine_fixture

NOW = datetime(2026, 9, 28, 12, 0, 0, tzinfo=timezone.utc)
DEFAULTS = RetentionPeriods(conversation_days=365, trace_days=90)


@pytest.fixture(autouse=True)
def _no_resolver_leaks():
    """The resolver is process-wide; never let one test's leak into another."""
    set_retention_override_resolver(None)
    yield
    set_retention_override_resolver(None)


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


def _age(days: int) -> datetime:
    return NOW - timedelta(days=days)


def _seed(db: Session, *, username: str, age_days: int, trace: bool = True) -> int:
    """A terminal task of one fresh user, anchored ``age_days`` ago."""
    user = User(username=username, password_hash="unused")
    db.add(user)
    db.flush()
    task = Task(
        user_id=user.id,
        title="retention override fixture",
        status=TaskStatus.COMPLETED,
        last_activity_at=_age(age_days),
    )
    db.add(task)
    db.flush()
    if trace:
        db.add(
            TraceEvent(
                task_id=task.id,
                event_id=f"evt-{task.id}",
                event_type="agent_execution_checkpoint",
                timestamp=NOW,
                data={},
            )
        )
    db.commit()
    return int(task.id)


def _user_of(sessions: sessionmaker[Session], task_id: int) -> int:
    with sessions() as db:
        return int(
            db.execute(sa.select(Task.user_id).where(Task.id == task_id)).scalar_one()
        )


def _state(sessions: sessionmaker[Session], task_id: int) -> str:
    """``gone``, ``traces_gone`` or ``intact``."""
    with sessions() as db:
        if db.get(Task, task_id) is None:
            return "gone"
        traces = db.execute(
            sa.select(sa.func.count())
            .select_from(TraceEvent)
            .where(TraceEvent.task_id == task_id)
        ).scalar_one()
        return "intact" if traces else "traces_gone"


def _batch(sessions: sessionmaker[Session], **kwargs: object) -> RetentionPurgeReport:
    """A batch on :data:`DEFAULTS`, bypassing the PostgreSQL-only gate.

    The gate is covered in ``test_task_retention_purge.py``; the row semantics
    here must hold on both dialects.
    """
    import xagent.web.services.task_retention_purge as purge_module

    original = purge_module.ensure_retention_purge_supported
    purge_module.ensure_retention_purge_supported = lambda db: None  # type: ignore[assignment]
    try:
        kwargs.setdefault("periods", (DEFAULTS.conversation_days, DEFAULTS.trace_days))
        return run_retention_purge_batch(
            sessions,
            now=NOW,
            limit=100,
            dry_run=False,
            **kwargs,  # type: ignore[arg-type]
        )
    finally:
        purge_module.ensure_retention_purge_supported = original  # type: ignore[assignment]


# ---------------------------------------------------------------------------
# Unregistered: exactly today's behaviour.
# ---------------------------------------------------------------------------


def test_unregistered_resolves_the_configured_periods_without_a_query(sessions) -> None:
    with sessions() as db:
        task_id = _seed(db, username="u0", age_days=1)
    statements: list[str] = []
    with sessions() as db:
        sa.event.listen(
            db.get_bind(),
            "before_cursor_execute",
            lambda *args: statements.append(args[2]),
        )
        assert resolve_task_retention_periods(db, task_id, DEFAULTS) == DEFAULTS
    assert statements == []


def test_unregistered_scan_is_the_global_scan(sessions) -> None:
    """Not just the same rows: the same SQL, so nothing about the plan moves."""
    with sessions() as db:
        snapshot = load_retention_overrides(db, DEFAULTS)
        assert snapshot is not None
        assert snapshot.periods_by_user == {} and snapshot.refused_users == frozenset()

        def due(periods: RetentionPeriods) -> sa.ColumnElement[bool]:
            return Task.id > (periods.conversation_days or 0)

        assert str(snapshot.scan_condition(Task.user_id, due)) == str(due(DEFAULTS))


# ---------------------------------------------------------------------------
# Resolution rules.
# ---------------------------------------------------------------------------


@pytest.mark.parametrize(
    ("override", "expected"),
    [
        (RetentionOverride(conversation_days=30), RetentionPeriods(30, 90)),
        (RetentionOverride(trace_days=7), RetentionPeriods(365, 7)),
        (RetentionOverride(730, 730), RetentionPeriods(730, 730)),
        (RetentionOverride(), DEFAULTS),
    ],
)
def test_an_override_replaces_only_the_legs_it_sets(
    sessions, override, expected
) -> None:
    set_retention_override_resolver(lambda db: {7: override})
    with sessions() as db:
        snapshot = load_retention_overrides(db, DEFAULTS)
    assert snapshot is not None
    assert snapshot.periods_for(7) == expected
    assert snapshot.periods_for(8) == DEFAULTS


@pytest.mark.parametrize(
    "value",
    [None, 0, -1, RETENTION_OVERRIDE_MAX_DAYS + 1, True, 30.0, "30"],
)
def test_an_unusable_value_refuses_that_user_only(sessions, value) -> None:
    """Not clamped, not treated as inherit, not treated as unlimited."""
    set_retention_override_resolver(
        lambda db: {
            7: RetentionOverride(conversation_days=value),  # type: ignore[arg-type]
            8: RetentionOverride(conversation_days=30),
        }
    )
    with sessions() as db:
        snapshot = load_retention_overrides(db, DEFAULTS)
    assert snapshot is not None
    assert snapshot.periods_for(7) is None
    assert snapshot.periods_for(8) == RetentionPeriods(30, 90)


def test_an_unusable_value_refuses_the_user_even_on_a_leg_the_deployment_left_off(
    sessions,
) -> None:
    """``_apply`` must check usability before it checks whether the leg is on.

    The deployment here has no trace period at all (``trace_days=None``); a
    resolver that sets ``trace_days=0`` is unusable regardless. Checking
    ``default is None`` first would treat the off leg as nothing to validate
    and let the unusable ``0`` pass silently as "leg stays off", refusing
    nobody -- exactly the leak "on a leg the deployment left off" exists to
    close.
    """
    defaults = RetentionPeriods(conversation_days=365, trace_days=None)
    set_retention_override_resolver(lambda db: {7: RetentionOverride(trace_days=0)})
    with sessions() as db:
        snapshot = load_retention_overrides(db, defaults)
    assert snapshot is not None
    assert snapshot.periods_for(7) is None


@pytest.mark.parametrize(
    ("defaults", "override", "expected"),
    [
        # Trace unset in the environment: the deployment's trace period *is*
        # its conversation period, so an inherited trace follows the team's.
        (
            RetentionPeriods(365, 365),
            RetentionOverride(730),
            RetentionPeriods(730, 730),
        ),
        (RetentionPeriods(365, 365), RetentionOverride(30), RetentionPeriods(30, 30)),
        # A trace period of its own stays what the deployment configured.
        (RetentionPeriods(365, 90), RetentionOverride(730), RetentionPeriods(730, 90)),
        (
            RetentionPeriods(365, 500),
            RetentionOverride(730),
            RetentionPeriods(730, 500),
        ),
        (RetentionPeriods(None, 90), RetentionOverride(30), RetentionPeriods(None, 90)),
    ],
)
def test_an_inherited_trace_period_follows_a_trace_that_follows_the_conversation(
    sessions, defaults, override, expected
) -> None:
    set_retention_override_resolver(lambda db: {7: override})
    with sessions() as db:
        snapshot = load_retention_overrides(db, defaults)
    assert snapshot is not None and snapshot.periods_for(7) == expected


def test_extending_the_conversation_keeps_a_following_trace_too(sessions) -> None:
    """Deployment sets only the conversation period; a team extends it."""
    with sessions() as db:
        task_id = _seed(db, username="follow", age_days=400)
    user_id = _user_of(sessions, task_id)
    set_retention_override_resolver(lambda db: {user_id: RetentionOverride(730)})

    report = _batch(sessions, periods=(365, 365))

    assert _state(sessions, task_id) == "intact"
    assert report.purged == 0


def test_an_override_never_enables_a_leg_the_deployment_left_off(sessions) -> None:
    trace_only = RetentionPeriods(conversation_days=None, trace_days=90)
    set_retention_override_resolver(lambda db: {7: RetentionOverride(30, 7)})
    with sessions() as db:
        snapshot = load_retention_overrides(db, trace_only)
    assert snapshot is not None
    assert snapshot.periods_for(7) == RetentionPeriods(None, 7)


@pytest.mark.parametrize(
    "result",
    [
        None,
        [(7, RetentionOverride())],
        {"7": RetentionOverride()},
        {True: RetentionOverride()},
    ],
)
def test_a_malformed_result_fails_the_whole_resolution(sessions, result) -> None:
    set_retention_override_resolver(lambda db: result)
    with sessions() as db:
        assert load_retention_overrides(db, DEFAULTS) is None


def test_a_value_of_the_wrong_type_refuses_that_user(sessions) -> None:
    set_retention_override_resolver(lambda db: {7: {"conversation_days": 30}})
    with sessions() as db:
        snapshot = load_retention_overrides(db, DEFAULTS)
    assert snapshot is not None and snapshot.periods_for(7) is None


def test_a_raising_resolver_fails_closed_and_logs(sessions, caplog) -> None:
    def broken(db: Session) -> dict[int, RetentionOverride]:
        raise RuntimeError("settings table unreachable")

    set_retention_override_resolver(broken)
    with caplog.at_level(logging.WARNING, logger=overrides_module.__name__):
        with sessions() as db:
            assert load_retention_overrides(db, DEFAULTS) is None
            assert resolve_task_retention_periods(db, 1, DEFAULTS) is None
    assert "settings table unreachable" in caplog.text


def test_registering_a_non_callable_is_refused() -> None:
    with pytest.raises(TypeError):
        set_retention_override_resolver(30)  # type: ignore[arg-type]


def test_inherit_is_the_default_and_is_not_none() -> None:
    assert RetentionOverride().conversation_days is INHERIT
    assert INHERIT is not None


# ---------------------------------------------------------------------------
# End to end through run_retention_purge_batch.
# ---------------------------------------------------------------------------


def test_a_shorter_and_a_longer_team_period_each_change_only_their_own_tasks(
    sessions,
) -> None:
    with sessions() as db:
        shorter = _seed(db, username="short", age_days=60)
        longer_conversation = _seed(db, username="long-c", age_days=400)
        longer_trace = _seed(db, username="long-t", age_days=120)
        default_conversation = _seed(db, username="default-c", age_days=400)
        default_trace = _seed(db, username="default-t", age_days=120)
        untouched = _seed(db, username="default-young", age_days=60)
    short_user = _user_of(sessions, shorter)
    long_users = {
        _user_of(sessions, longer_conversation),
        _user_of(sessions, longer_trace),
    }
    set_retention_override_resolver(
        lambda db: {
            short_user: RetentionOverride(conversation_days=30, trace_days=30),
            **{user: RetentionOverride(730, 700) for user in long_users},
        }
    )

    report = _batch(sessions)

    assert _state(sessions, shorter) == "gone"
    assert _state(sessions, longer_conversation) == "intact"
    assert _state(sessions, longer_trace) == "intact"
    assert _state(sessions, default_conversation) == "gone"
    assert _state(sessions, default_trace) == "traces_gone"
    assert _state(sessions, untouched) == "intact"
    # The longer team's tasks are not even scanned: a global-period scan would
    # re-admit them on every sweep only for the lock to refuse them.
    assert report.eligible == 3
    assert (report.purged_conversations, report.purged_traces) == (2, 1)
    assert report.skipped_busy == 0 and report.skipped_not_due == 0


def test_the_assessment_uses_the_period_current_when_the_task_is_locked(
    sessions,
) -> None:
    """A team that extends between the scan and the lock keeps its task.

    400 days is past both global periods, so an assessment that fell back to
    the global periods -- or took the shorter of team and global -- would
    purge it. Only the team's current 730 days keeps it.
    """
    with sessions() as db:
        task_id = _seed(db, username="racing", age_days=400)
    user_id = _user_of(sessions, task_id)
    calls = {"n": 0}

    def extends_after_the_scan(db: Session) -> dict[int, RetentionOverride]:
        calls["n"] += 1
        days = 30 if calls["n"] == 1 else 730
        return {user_id: RetentionOverride(days, days)}

    set_retention_override_resolver(extends_after_the_scan)

    report = _batch(sessions)

    assert report.eligible == 1
    assert report.skipped_not_due == 1 and report.skipped_busy == 0
    assert _state(sessions, task_id) == "intact"


def test_a_resolver_failing_at_the_scan_purges_nothing(sessions) -> None:
    with sessions() as db:
        task_id = _seed(db, username="scan-fail", age_days=400)

    def broken(db: Session) -> dict[int, RetentionOverride]:
        raise RuntimeError("down")

    set_retention_override_resolver(broken)

    report = _batch(sessions)

    assert report.eligible == 0 and report.purged == 0
    assert _state(sessions, task_id) == "intact"


def test_a_resolver_failing_at_the_lock_skips_the_task(sessions) -> None:
    with sessions() as db:
        task_id = _seed(db, username="lock-fail", age_days=400)
    calls = {"n": 0}

    def fails_after_the_scan(db: Session) -> dict[int, RetentionOverride]:
        calls["n"] += 1
        if calls["n"] > 1:
            raise RuntimeError("down")
        return {}

    set_retention_override_resolver(fails_after_the_scan)

    report = _batch(sessions)

    assert report.eligible == 1
    assert report.skipped_override_unresolved == 1 and report.purged == 0
    assert _state(sessions, task_id) == "intact"


def test_a_per_task_failure_warns_once_per_batch_not_once_per_task(
    sessions, caplog
) -> None:
    """A resolver that fails only after the scan -- a rate-limited settings
    service that answers the scan and refuses the per-task reads -- must
    still reach WARNING, but once per batch, not once per task. The per-task
    reads log at DEBUG with the traceback; the batch logs one WARNING
    naming the count. The scan succeeds here, so nothing else would warn.
    """
    with sessions() as db:
        for index in range(3):
            _seed(db, username=f"persistent-fail-{index}", age_days=400)
    calls = {"n": 0}

    def fails_after_the_scan(db: Session) -> dict[int, RetentionOverride]:
        calls["n"] += 1
        if calls["n"] > 1:
            raise RuntimeError("down")
        return {}

    set_retention_override_resolver(fails_after_the_scan)

    with caplog.at_level(logging.DEBUG, logger=overrides_module.__name__):
        report = _batch(sessions)

    assert report.skipped_override_unresolved == 3
    warnings = [r for r in caplog.records if r.levelno >= logging.WARNING]
    assert [r.name for r in warnings] == ["xagent.web.services.task_retention_purge"]
    assert "3 task(s)" in warnings[0].getMessage()
    debug_failures = [
        r
        for r in caplog.records
        if r.levelno == logging.DEBUG and "resolver failed" in r.getMessage()
    ]
    assert len(debug_failures) == 3
    assert all(r.exc_info for r in debug_failures)


def test_an_out_of_cap_value_keeps_that_teams_tasks_out_of_the_purge(
    sessions,
) -> None:
    with sessions() as db:
        refused = _seed(db, username="over-cap", age_days=400)
        other = _seed(db, username="default", age_days=400)
    refused_user = _user_of(sessions, refused)
    set_retention_override_resolver(
        lambda db: {refused_user: RetentionOverride(RETENTION_OVERRIDE_MAX_DAYS + 1)}
    )

    report = _batch(sessions)

    assert report.eligible == 1
    assert _state(sessions, refused) == "intact"
    assert _state(sessions, other) == "gone"
    with sessions() as db:
        action = purge_task(db, refused, now=NOW, conversation_days=365, trace_days=90)
    assert action is RetentionPurgeAction.SKIPPED_OVERRIDE_UNRESOLVED
    assert _state(sessions, refused) == "intact"


def test_a_missing_task_is_skipped_busy_not_unresolved(sessions) -> None:
    """A registered resolver with nothing to say about the task must not
    turn a row that vanished before the lock into ``skipped_override_unresolved``.

    ``resolve_task_retention_periods`` looks the task's ``user_id`` up to key
    the resolver's mapping; a task deleted between the scan and this call has
    none, and it must fall back to ``defaults`` rather than refuse (returning
    ``None``) -- the assessment that follows is what correctly reports a
    missing row, as ``skipped_busy``. A regression that returned ``None`` for
    the missing-task branch would instead report
    ``skipped_override_unresolved``, which is what this pins.
    """
    set_retention_override_resolver(lambda db: {})
    with sessions() as db:
        task_id = _seed(db, username="vanished", age_days=1, trace=False)
        db.execute(sa.delete(Task).where(Task.id == task_id))
        db.commit()

    with sessions() as db:
        action = purge_task(db, task_id, now=NOW, conversation_days=365, trace_days=90)
    assert action is RetentionPurgeAction.SKIPPED_BUSY


def test_a_quiescent_task_with_no_anchor_is_skipped_busy(sessions) -> None:
    """A COMPLETED task with no ``last_activity_at``, no ``created_at`` and no
    message has nothing to measure a period against, so it must be skipped as
    busy rather than reported not-due. This pins the ``assessment.anchor is
    not None`` half of the ``NOT_ELIGIBLE`` branch in ``_purge_task``: without
    it, a quiescent task with no anchor would be misreported as
    ``skipped_not_due`` -- "not due yet" implies a period that simply has not
    elapsed, which is false when there is nothing to measure at all.
    """
    with sessions() as db:
        task_id = _seed(db, username="no-anchor", age_days=1, trace=False)
        db.execute(
            sa.update(Task)
            .where(Task.id == task_id)
            .values(created_at=None, last_activity_at=None)
        )
        db.commit()

    with sessions() as db:
        action = purge_task(db, task_id, now=NOW, conversation_days=365, trace_days=90)
    assert action is RetentionPurgeAction.SKIPPED_BUSY


def test_an_override_on_a_leg_the_deployment_left_off_deletes_nothing(
    sessions,
) -> None:
    with sessions() as db:
        young = _seed(db, username="leg-off-young", age_days=60)
        old = _seed(db, username="leg-off-old", age_days=100)
    users = {_user_of(sessions, young), _user_of(sessions, old)}
    set_retention_override_resolver(
        lambda db: {user: RetentionOverride(conversation_days=30) for user in users}
    )

    report = _batch(sessions, periods=(None, 90))

    assert _state(sessions, young) == "intact"
    assert _state(sessions, old) == "traces_gone"
    assert report.purged_conversations == 0


def test_the_scan_honours_a_shorter_period_it_would_otherwise_miss(sessions) -> None:
    with sessions() as db:
        task_id = _seed(db, username="scan-short", age_days=60)
    user_id = _user_of(sessions, task_id)

    with sessions() as db:
        assert (
            select_purge_candidates(
                db, now=NOW, conversation_days=365, trace_days=90, limit=10
            )
            == []
        )
        snapshot_resolver = {user_id: RetentionOverride(30, 30)}
        set_retention_override_resolver(lambda db: snapshot_resolver)
        snapshot = load_retention_overrides(db, DEFAULTS)
        assert select_purge_candidates(
            db,
            now=NOW,
            conversation_days=365,
            trace_days=90,
            limit=10,
            overrides=snapshot,
        ) == [task_id]


def test_a_snapshot_for_other_periods_is_refused_by_the_scan(sessions) -> None:
    with sessions() as db:
        snapshot = load_retention_overrides(db, RetentionPeriods(30, 30))
        with pytest.raises(ValueError):
            select_purge_candidates(
                db,
                now=NOW,
                conversation_days=365,
                trace_days=90,
                limit=10,
                overrides=snapshot,
            )


def test_a_refused_team_is_reported_once_per_batch_not_once_per_task(
    sessions, caplog
) -> None:
    with sessions() as db:
        refused = _seed(db, username="refused", age_days=400)
        for index in range(3):
            _seed(db, username=f"plain-{index}", age_days=400)
    refused_user = _user_of(sessions, refused)
    set_retention_override_resolver(
        lambda db: {refused_user: RetentionOverride(conversation_days=0)}
    )

    with caplog.at_level(logging.WARNING, logger=overrides_module.__name__):
        report = _batch(sessions)

    assert report.purged_conversations == 3
    assert _state(sessions, refused) == "intact"
    assert [r.getMessage() for r in caplog.records if "refused" in r.getMessage()] == [
        f"retention overrides refused for 1 user(s): unusable period "
        f"(must be 1..{RETENTION_OVERRIDE_MAX_DAYS} days or inherit); "
        f"their tasks are kept; user ids (first 20): [{refused_user}]"
    ]