AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""Alert lifecycle: time-to-live, the "live" read view, and the expiry sweep.
An alert used to leave the ``unread`` queue only when a human acked or
dismissed it, so the briefing's "Needs you" list grew without bound and the
daily briefs re-listed the same rows every day. This module gives every alert
a deterministic lifetime and one read helper every surface shares:
- :func:`ttl_days_for` — per-category TTL (monitoring vs action), from
settings; ``None`` for sources that own their own lifecycle (artifacts
persist in the gallery, decision-backed alerts end via approve/reject).
- :func:`is_expired` — pure predicate over an ``Alert`` + ``now``.
- :func:`list_live_alerts` — ``unread`` rows that are neither past their TTL
nor snoozed. ``/today``, the chat ``<briefing>`` block, the briefs and the
reflection all read through this, so the page is correct even before the
sweep has run.
- :func:`expire_stale_alerts` — the sweep the scheduler runs every 15 minutes
(and once at startup): flips past-TTL ``unread`` rows to ``expired`` and
audits the batch. ``expired`` is just "not unread": the activity feed and
the artifacts gallery keep showing the rows, and ``POST /alerts/{id}/reopen``
brings one back.
Kept free of briefing/route imports at module level (only lazy imports inside
functions) so ``alerts.store`` stays a leaf and this module can be imported by
the scheduler, the routes and the workflows alike.
"""
from __future__ import annotations
import logging
from datetime import UTC, datetime, timedelta
from pathlib import Path
from openexecutive.alerts.models import Alert, visible_alert
logger = logging.getLogger(__name__)
EXPIRED_STATUS = "expired"
RESOLVED_STATUS = "resolved"
# Rows one sweep examines. Larger than any realistic unread backlog so a
# single pass converges; a bigger one just takes a second tick.
_SWEEP_PAGE = 5000
# Sources whose rows have their own lifecycle and must never be expired,
# closed or routed by the automatic machinery: artifacts persist in the
# gallery until archived; decision-backed alerts end via /decisions; a roster
# request's card ends when the request is answered or expires
# (people.roster_requests).
TTL_EXEMPT_SOURCES: frozenset[str] = frozenset(
{"artifact", "decision_scheduling", "roster_request"}
)
def parse_aware(iso: str | None) -> datetime | None:
"""Parse an ISO timestamp to an aware UTC datetime, or ``None``.
Naive timestamps (a bare ``.isoformat()``) are assumed UTC, mirroring
``api/routes/today._parse_aware`` so comparisons against
``datetime.now(UTC)`` never raise.
"""
if not iso:
return None
try:
dt = datetime.fromisoformat(iso)
except (ValueError, TypeError):
return None
if dt.tzinfo is None:
dt = dt.replace(tzinfo=UTC)
return dt.astimezone(UTC)
def _ttl_settings() -> tuple[int, int]:
"""Return ``(monitoring_days, action_days)`` from settings.
Falls back to the documented defaults when settings cannot be built (a
bare test DB with no env), so a lifecycle read never raises.
"""
try:
from openexecutive.config import get_settings
s = get_settings()
return int(s.alert_ttl_days_monitoring), int(s.alert_ttl_days_action)
except Exception:
return 3, 14
def ttl_days_for(alert: Alert, *, monitoring_days: int, action_days: int) -> int | None:
"""Days an alert may sit ``unread`` before it expires; ``None`` = never.
``0`` (or a negative value) for a category disables expiry for it — the
knob an operator uses to keep an old backlog when upgrading.
"""
if alert.source in TTL_EXEMPT_SOURCES:
return None
from openexecutive.briefing.ranking import categorize
category = categorize(
source=alert.source,
severity=alert.severity,
routed_to_person_id=alert.routed_to_person_id,
topic_tags=alert.topic_tags or [],
)
days = monitoring_days if category == "monitoring" else action_days
return days if days > 0 else None
def is_expired(
alert: Alert,
now: datetime | None = None,
*,
monitoring_days: int | None = None,
action_days: int | None = None,
) -> bool:
"""True when ``alert`` is older than its category TTL."""
if monitoring_days is None or action_days is None:
m, a = _ttl_settings()
monitoring_days = m if monitoring_days is None else monitoring_days
action_days = a if action_days is None else action_days
days = ttl_days_for(alert, monitoring_days=monitoring_days, action_days=action_days)
if days is None:
return False
# A situation that keeps re-firing stays live: the age anchor is the
# latest of created_at and last_seen_at (coalescing bumps the latter).
# A snooze counts too, so a card snoozed past its TTL comes back when
# the snooze ends instead of expiring unseen.
anchor = parse_aware(alert.created_at)
for later in (getattr(alert, "last_seen_at", None), getattr(alert, "snoozed_until", None)):
stamp = parse_aware(later)
if stamp is not None and (anchor is None or stamp > anchor):
anchor = stamp
if anchor is None:
return False
now = now or datetime.now(UTC)
return anchor + timedelta(days=days) <= now
def _is_snoozed(alert: Alert, now: datetime) -> bool:
until = parse_aware(getattr(alert, "snoozed_until", None))
return until is not None and until > now
def is_live(alert: Alert, now: datetime | None = None) -> bool:
"""Would this row show in the live queue right now? (unread, inside its
TTL, not snoozed.) The single predicate every surface and the sweep share."""
now = now or datetime.now(UTC)
return alert.status == "unread" and not is_expired(alert, now) and not _is_snoozed(alert, now)
# How many live alerts every board-shaped surface takes. `/today` renders this
# many cards, and `briefing.context` trusts this many ids for `ack_alert` —
# those two MUST agree, or a card the principal can see and discuss is one the
# Executive is refused permission to clear. Shared here, with `list_live_alerts`,
# rather than duplicated as a literal at each call site.
BOARD_LIMIT = 100
def list_live_alerts(
limit: int = 100,
db_path: Path | None = None,
*,
now: datetime | None = None,
viewer: object | None = None,
) -> list[Alert]:
"""``unread`` alerts that are still live: not past TTL, not snoozed.
A drafted artifact is its owner's alone (``models.visible_alert``): it is
kept only for the ``viewer`` it belongs to, and left out with no viewer —
the board the review, the reflection and the shared digests read.
Newest first, like ``store.list_alerts``. This is the read every
user-facing surface shares; the sweep merely persists what this view
already hides, so the two can never disagree.
"""
from openexecutive.alerts.store import list_alerts
now = now or datetime.now(UTC)
monitoring_days, action_days = _ttl_settings()
# Over-fetch: the page is newest-first, but snoozed rows and (between
# sweeps) freshly-expired rows are interleaved with live ones, so a
# `limit`-sized page could come back short.
rows = list_alerts(status="unread", limit=max(limit * 3, limit + 50), db_path=db_path)
live = [
a for a in rows
if not is_expired(a, now, monitoring_days=monitoring_days, action_days=action_days)
and not _is_snoozed(a, now)
and visible_alert(a, viewer)
]
return live[:limit]
def expire_stale_alerts(
now: datetime | None = None,
db_path: Path | None = None,
) -> int:
"""Flip every past-TTL ``unread`` alert to ``expired``. Returns the count.
Audited as ``alert_sweep`` (actor ``scheduler``) whenever at least one row
changed, with the ids so the reopen path is one click away. Never raises:
a sweep failure is logged and reported as ``0`` so the scheduler tick
continues.
"""
from openexecutive.alerts.store import bulk_set_status, list_alerts
now = now or datetime.now(UTC)
try:
monitoring_days, action_days = _ttl_settings()
rows = list_alerts(status="unread", limit=_SWEEP_PAGE, db_path=db_path)
expired_ids = [
a.id for a in rows
if a.id is not None
and is_expired(a, now, monitoring_days=monitoring_days, action_days=action_days)
]
if not expired_ids:
return 0
changed = bulk_set_status(
EXPIRED_STATUS, alert_ids=expired_ids, only_status="unread", db_path=db_path
)
count = len(changed)
except Exception:
logger.exception("alerts.lifecycle: expiry sweep failed")
return 0
# An alert nobody acted on before its TTL didn't matter: void the review's
# DMs about it rather than leave them counted as ignored.
for alert_id in expired_ids:
resolve_alert_outreach(_AlertRef(alert_id), EXPIRED_STATUS)
if count:
try:
from openexecutive.audit import log_event as audit_log
audit_log(
"alert_sweep",
f"Expired {count} stale alert(s) past TTL",
actor="scheduler",
details={
"count": count,
"alert_ids": expired_ids[:50],
"ttl_days_monitoring": monitoring_days,
"ttl_days_action": action_days,
},
)
except Exception:
logger.exception("alerts.lifecycle: audit log failed")
return count
def mute_pattern_for(alert: Alert) -> str | None:
"""The topic pattern "mute this topic" should add for an alert.
Prefers the watch slug (``external:<slug>``), then a ``department:``
tag, then the first topic tag. ``None`` when the alert carries no tags.
"""
from openexecutive.briefing.ranking import watch_slug_from_tags
tags = list(alert.topic_tags or [])
slug = watch_slug_from_tags(tags)
if slug is not None:
return f"external:{slug}"
for tag in tags:
if tag.startswith("department:"):
return tag
return tags[0] if tags else None
class _AlertRef:
"""Just enough of an Alert for :func:`resolve_alert_outreach` to void it."""
def __init__(self, alert_id: int) -> None:
self.id: int | None = alert_id
self.routed_to_person_id: int | None = None
def resolve_alert_outreach(alert: Alert | _AlertRef, status: str) -> None:
"""Resolve the Attunement outcome rows for review DMs about ``alert``.
Acknowledged or resolved: the DMs to the person it is routed to (and to
the principal, who is escalated to) landed. Dismissed or stale: the alert
didn't matter, so those DMs are voided — counted neither way. Never
attributes an outcome to anyone else the alert was once DM'd to, and a
dismissal can never lower anyone's rate. Never raises."""
if alert.id is None:
return
try:
from openexecutive.attunement.outcomes import OUTCOME_ACTED, OUTCOME_VOID, resolve_by_ref
from openexecutive.people.store import find_principal_person
ref = f"alert:{alert.id}"
if status in ("ack", "resolved"):
owners = {pid for pid in (getattr(alert, "routed_to_person_id", None),) if pid}
principal = find_principal_person()
if principal is not None and principal.id is not None:
owners.add(principal.id)
resolve_by_ref(ref, OUTCOME_ACTED, person_ids=owners)
elif status in ("dismissed", "stale", "expired"):
resolve_by_ref(ref, OUTCOME_VOID)
except Exception:
logger.debug("resolve_alert_outreach failed", exc_info=True)
def record_ack_feedback(alert: Alert, status: str) -> None:
"""Teach the source of an alert from the principal's verdict.
``dismissed`` on a watch-sourced alert lowers that watch's trust score
(and bumps its dismiss_count); ``ack`` recovers it a little. Other
sources have no feedback sink yet. Never raises.
"""
from openexecutive.briefing.ranking import watch_slug_from_tags
resolve_alert_outreach(alert, status)
slug = watch_slug_from_tags(list(alert.topic_tags or []))
if slug is None:
return
try:
from openexecutive.monitoring import store as monitoring_store
if status == "dismissed":
monitoring_store.record_dismissal(slug)
elif status == "ack":
monitoring_store.record_confirmation(slug)
except Exception:
logger.debug("alerts.lifecycle: ack feedback failed for %s", slug, exc_info=True)
_MUTE_MIN_CHARS = 4
def mute_pattern_allowed(alert: Alert, pattern: str) -> bool:
"""A mute added from a card must be specific: one of that alert's own
tags, or an ``external:`` / ``department:`` scoped pattern of at least
``_MUTE_MIN_CHARS`` characters. Mutes are substring matches over every
future alert's tags, so ``"e"`` would silence the company."""
p = pattern.strip().lower()
if len(p) < _MUTE_MIN_CHARS:
return False
tags = {t.lower() for t in (alert.topic_tags or [])}
if p in tags:
return True
return p.startswith(("external:", "department:")) and len(p.split(":", 1)[1]) >= 2
def apply_mute_request(alert: Alert, mute_topic: str | bool | None) -> str | None:
"""Handle the optional ``mute_topic`` on a dismiss: an explicit pattern,
or ``True`` to derive one from the alert's tags. Returns the pattern
added, or ``None`` (also when the pattern is too broad to allow)."""
if not mute_topic:
return None
pattern = mute_topic if isinstance(mute_topic, str) else mute_pattern_for(alert)
if not pattern or not mute_pattern_allowed(alert, pattern):
return None
from openexecutive.alerts.store import add_mute
try:
add_mute(pattern)
except Exception:
logger.exception("alerts.lifecycle: add_mute failed for %r", pattern)
return None
return pattern
__all__ = [
"EXPIRED_STATUS",
"apply_mute_request",
"mute_pattern_allowed",
"mute_pattern_for",
"record_ack_feedback",
"RESOLVED_STATUS",
"TTL_EXEMPT_SOURCES",
"expire_stale_alerts",
"is_expired",
"is_live",
"list_live_alerts",
"parse_aware",
"ttl_days_for",
]