AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""Delivered-brief state: what the last morning/EoD brief covered.
The principal briefs used to re-list the whole unread queue every day and
call the "activity" block "since last brief" when it was really just the
latest N rows. This module gives each recurring brief kind a memory of what
was last *delivered* so the workflow can:
- bound "what changed" to the window since the previous delivery (`since`),
- split proposals into NEW (created inside that window) vs CARRIED OVER,
- list what the Executive's alert review handled inside the window, and
- skip the model call entirely when the fingerprint of the inputs is
unchanged, sending a one-line "nothing new" instead.
Storage reuses the ``briefing_narrative`` table (``briefing/narrative_cache``)
under a ``brief:<kind>`` scope: ``input_hash`` holds the fingerprint,
``narrative_text`` the delivered artifact and ``generated_at`` the delivery
time. Scopes are only ever read by exact key, so the namespace cannot
collide with the per-viewer header cache. Only the scheduler records a
delivery (after a successful send), so manual workflow runs never advance
the window.
Each run's outcome, sent or not, goes under ``brief_delivery:<kind>``
(``record_delivery_outcome``): the reason in ``input_hash`` and, in
``narrative_text``, the channel that sent it — a channel name, never an
address — and, for a failure, what happened in a line (the tool's own error,
or why no channel could be tried; ``detail``). The Briefing's "not sent"
notice and the Setup status page read it back through ``current_problem``
and ``describe_problem``.
"""
from __future__ import annotations
import hashlib
import json
import logging
import re
from dataclasses import dataclass
from datetime import UTC, datetime, timedelta
from typing import Any, Literal, cast, get_args
from openexecutive.alerts.lifecycle import parse_aware
from openexecutive.briefing import narrative_cache
logger = logging.getLogger(__name__)
SCOPE_PREFIX = "brief:"
DEFAULT_WINDOW = timedelta(hours=24)
SUPPRESSED_TEMPLATE = (
"Nothing new since yesterday's brief — {n} item{s} still waiting on you."
)
# Audit event types the alert review job emits for autonomous moves. The
# brief's "handled overnight" block is built from these (see handled_since).
REVIEW_EVENT_TYPES: tuple[str, ...] = (
"alert_review_closed",
"alert_review_routed",
"alert_review_nudged",
"alert_review_escalated",
"alert_review_drafted",
"alert_review_merged",
"alert_review_suggested_workflow",
"alert_review_changed",
)
# Review events that are bookkeeping on a still-open alert, not a completed
# move. A `changed` verdict rewrites the card's text in place — the alert
# stays in "Needs you" and the card itself shows the note — so listing it
# under "handled" double-reports it and mislabels it as done. It renders in
# the brief's REWRITTEN block instead (see rewritten_since).
_NOT_HANDLED_EVENT_TYPES: frozenset[str] = frozenset({"alert_review_changed"})
# Every audit event type the handled block reads, mapped to the short kind
# the brief and the /today rail render. The research watch policy's
# autonomous moves ride alongside the alert review's.
HANDLED_EVENT_KINDS: dict[str, str] = {
**{
t: t.removeprefix("alert_review_")
for t in REVIEW_EVENT_TYPES
if t not in _NOT_HANDLED_EVENT_TYPES
},
"watchlist_research_added": "watching",
"watchlist_auto_disabled": "stopped_watching",
}
# The nudge audit summary opens with "[alert N] " so `alerts.review` can count
# delivered nudges per alert with a text query; it is bookkeeping, not prose.
_ALERT_MARKER_RE = re.compile(r"^\[alert \d+\]\s*")
def scope_for(kind: str) -> str:
return f"{SCOPE_PREFIX}{kind}"
def last_delivered(kind: str) -> narrative_cache.BriefingNarrative | None:
"""The last delivered brief of this kind, or None on a cold store."""
try:
return narrative_cache.get(scope_for(kind))
except Exception:
logger.exception("brief_state: read failed for %s", kind)
return None
def since_for(kind: str, now: datetime | None = None) -> datetime:
"""Start of the "what changed" window: the previous delivery, else 24 h ago.
Bounded to at most 7 days back so a brief that stopped firing for a while
does not replay a month of history when it resumes.
"""
now = now or datetime.now(UTC)
prev = last_delivered(kind)
delivered_at = parse_aware(prev.generated_at) if prev else None
if delivered_at is None:
return now - DEFAULT_WINDOW
# Never in the future (clock skew / a scheduler `now` earlier than the
# recorded delivery would otherwise empty the window and suppress).
return min(now, max(delivered_at, now - timedelta(days=7)))
def record_delivered(kind: str, fingerprint: str, text: str) -> None:
"""Persist the delivered brief so the next run can diff against it."""
try:
narrative_cache.put(narrative_cache.BriefingNarrative(
scope=scope_for(kind),
input_hash=fingerprint,
narrative_text=text,
generated_at=narrative_cache.utc_now_iso(),
))
except Exception:
logger.exception("brief_state: write failed for %s", kind)
# How a brief's latest run ended: sent, or why not (``not_written`` — the run
# failed or produced nothing; the others are scheduler.runner.
# PrincipalDelivery.reason). ``gateway_down`` is email set up but the MCP
# gateway that sends it not running, which used to read as ``no_channel``
# and so blamed the owner's setup for the Executive's own fault.
DeliveryReason = Literal[
"delivered", "no_owner", "no_channel", "gateway_down", "send_failed", "not_written"
]
_DELIVERY_REASONS: frozenset[str] = frozenset(get_args(DeliveryReason))
DELIVERY_SCOPE_PREFIX = "brief_delivery:"
# The daily briefs (their send times show on the Setup status page).
BRIEF_KINDS: tuple[str, ...] = ("principal_brief_morning", "principal_brief_eod")
# Every recurring message to the owner whose runs are recorded: the daily
# briefs, and solo mode's weekly review.
DELIVERY_KINDS: tuple[str, ...] = (*BRIEF_KINDS, "principal_weekly_review")
# Delivery channels (scheduler.runner.delivery_order) as the app names them.
CHANNEL_NAMES: dict[str, str] = {
"email": "email",
"slack_dm": "Slack",
"discord_dm": "Discord",
"telegram": "Telegram",
}
# Why a brief didn't reach the owner, and what to do about it, in the user's
# words.
DELIVERY_PROBLEMS: dict[str, tuple[str, str]] = {
"no_owner": (
"there's no owner on the People list to send it to",
"Finish setup so you're on the People list as the owner.",
),
"no_channel": (
"nothing is set up to send it to you",
"Connect Gmail, or add your Slack, Telegram or Discord to your People profile.",
),
"gateway_down": (
"the Executive's mail connection wasn't running",
"It keeps retrying on its own; if the Gmail light on the Setup status page stays red, "
"the API log says why.",
),
"send_failed": (
"every way of sending it failed",
"The Setup status page shows which connection needs attention.",
),
"not_written": (
"it couldn't be written",
"The Setup status page shows which part needs attention — often the AI model.",
),
}
def brief_name(kind: str) -> str:
"""The brief's name in the app ("morning brief"): the scheduler's own label."""
from openexecutive.scheduler.action_phrasing import KIND_LABEL
return KIND_LABEL.get(kind, "brief")
def channel_phrase(channel: str) -> str:
"""As in "sent to you by email" or "sent to you on Slack"."""
return "by email" if channel == "email" else f"on {CHANNEL_NAMES.get(channel, channel)}"
@dataclass(frozen=True)
class DeliveryOutcome:
kind: str
reason: DeliveryReason
# The delivery channel that sent it ("email", "slack_dm", ...), if one did.
channel: str | None
at: datetime
# What happened when it wasn't sent, in a line: the tool's error, or why
# no channel could be tried. None for a delivered brief.
detail: str | None = None
# The longest detail kept: a line for the notice, not a traceback.
DETAIL_MAX_CHARS = 300
# A grant that died shows in the detail like this (orchestrator.mcp_gateway.
# grant_failure); the notice's fix then says to reconnect rather than to
# look at the status page.
_RECONNECT_HINT_RE = re.compile(
r"invalid_grant|expired|revoked|reconnect|unauthori[sz]ed|authentication", re.IGNORECASE
)
def record_delivery_outcome(
kind: str, *, reason: DeliveryReason, channel: str | None, detail: str | None = None
) -> None:
"""Remember how this brief's latest run ended. Never raises."""
detail = " ".join(detail.split())[:DETAIL_MAX_CHARS] if detail else None
text = json.dumps({"channel": channel or "", "detail": detail}) if detail else (channel or "")
try:
narrative_cache.put(narrative_cache.BriefingNarrative(
scope=f"{DELIVERY_SCOPE_PREFIX}{kind}",
input_hash=reason,
narrative_text=text,
generated_at=narrative_cache.utc_now_iso(),
))
except Exception:
logger.exception("brief_state: delivery outcome write failed for %s", kind)
def _read_outcome_text(text: str) -> tuple[str | None, str | None]:
"""``(channel, detail)`` from the stored row: a bare channel name (the
older shape, and every delivered brief) or the JSON a failure writes."""
if text.startswith("{"):
try:
parsed = json.loads(text)
except ValueError:
parsed = None
if isinstance(parsed, dict):
channel = parsed.get("channel")
detail = parsed.get("detail")
return (
channel if isinstance(channel, str) and channel else None,
detail if isinstance(detail, str) and detail else None,
)
return (text or None), None
def describe_problem(reason: DeliveryReason, detail: str | None = None) -> tuple[str, str]:
"""``(problem, fix)`` for the notice: the reason in the user's words,
with what happened appended when it is known, and a fix that names a
reconnect when the detail shows a grant that died."""
problem, fix = DELIVERY_PROBLEMS[reason]
if not detail:
return problem, fix
if reason in ("send_failed", "gateway_down"):
problem = f"{problem} ({detail})"
if reason == "send_failed" and _RECONNECT_HINT_RE.search(detail):
fix = (
"The Executive's sign-in to its mailbox expired or was revoked: connect it again, "
"then the next brief goes out."
)
return problem, fix
def last_delivery_outcome() -> DeliveryOutcome | None:
"""The latest run of any recorded message (``DELIVERY_KINDS``: the two
briefs and the weekly review), or None when none has run yet (or the
store can't be read). Never raises."""
latest: DeliveryOutcome | None = None
for kind in DELIVERY_KINDS:
try:
row = narrative_cache.get(f"{DELIVERY_SCOPE_PREFIX}{kind}")
except Exception:
logger.exception("brief_state: delivery outcome read failed for %s", kind)
continue
at = parse_aware(row.generated_at) if row is not None else None
if row is None or at is None or row.input_hash not in _DELIVERY_REASONS:
continue
channel, detail = _read_outcome_text(row.narrative_text or "")
outcome = DeliveryOutcome(
kind=kind,
reason=cast(DeliveryReason, row.input_hash), # checked above
channel=channel,
at=at,
detail=detail,
)
if latest is None or outcome.at > latest.at:
latest = outcome
return latest
def current_problem(
outcome: DeliveryOutcome | None,
*,
has_owner: bool,
can_deliver: bool,
gateway_down: bool = False,
) -> DeliveryReason | None:
"""What still keeps the latest brief from the owner, or None.
A failed send, or a brief that couldn't be written, stays reported until
the next brief records a new outcome. Having nowhere to send it is judged
from now (``has_owner``, ``can_deliver``, ``gateway_down``: email is set
up but the gateway that sends it is not running), not from the record, so
a partial fix reports the problem that is left: once a channel exists the
next brief will go, and there is nothing to report.
"""
if outcome is None or outcome.reason == "delivered":
return None
if outcome.reason in ("send_failed", "not_written"):
return outcome.reason
if can_deliver:
return None
if not has_owner:
return "no_owner"
return "gateway_down" if gateway_down else "no_channel"
def split_proposals(
proposals: list[dict[str, Any]], since: datetime | None
) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
"""``(new, carried)``: proposals created at/after ``since`` vs earlier.
With ``since`` None everything is "new" (the legacy single-list view).
"""
if since is None:
return list(proposals), []
new: list[dict[str, Any]] = []
carried: list[dict[str, Any]] = []
for p in proposals:
created = parse_aware(p.get("created_at"))
(new if created is None or created >= since else carried).append(p)
return new, carried
def rewritten_since(
proposals: list[dict[str, Any]], since: datetime | None
) -> list[dict[str, Any]]:
"""Open proposals the review rewrote (verdict ``changed``) at/after ``since``.
These are the alerts that dropped out of the handled block: still open,
text or severity refreshed by the Executive. The brief reports them under
"what changed", never as done. Empty when ``since`` is None.
"""
if since is None:
return []
out: list[dict[str, Any]] = []
for p in proposals:
if p.get("review_verdict") != "changed":
continue
# Fail open like split_proposals: a rewrite with no readable stamp is
# reported rather than dropped from every block.
reviewed = parse_aware(p.get("last_reviewed_at"))
if reviewed is None or reviewed >= since:
out.append(p)
return out
def rewritten_lines(
proposals: list[dict[str, Any]], since: datetime | None, limit: int = 10
) -> list[str]:
"""Bullet lines for the briefs' REWRITTEN block (one per rewritten open
proposal): ``- <headline> — <review note>``. Shared by the morning brief
and the end-of-day digest so the two never drift."""
return [
f"- {str(p.get('headline', ''))[:160]} — {str(p.get('review_note', ''))[:120]}"
for p in rewritten_since(proposals, since)[:limit]
]
def handled_since(
since: datetime, limit: int = 20, *, include_private: bool = False
) -> list[dict[str, Any]]:
"""Completed autonomous moves recorded in the audit log since ``since``.
Each item: ``{"kind": event_type sans prefix, "event_type": str,
"summary": str, "at": iso, "alert_id": int | None, "details": dict}``,
newest first. ``summary`` has the nudge bookkeeping marker stripped;
``details`` is the audit row's structured payload (headline, target
person, evidence ref, new status …) for callers that render more than
one line. Empty when the audit store is unavailable.
Rows private to the principal (one that names their contact, say) are
left out unless ``include_private``: only the principal's own ``/today``
asks for them. The briefs don't, as a written brief can be read by others.
"""
try:
from openexecutive.audit.logger import get_audit_logger
logger_ = get_audit_logger()
out: list[dict[str, Any]] = []
for event_type, kind in HANDLED_EVENT_KINDS.items():
for ev in logger_.query(
event_type=event_type,
since=since.isoformat(),
limit=limit,
include_private=include_private,
):
details = ev.details if isinstance(ev.details, dict) else {}
out.append({
"kind": kind,
"event_type": event_type,
"summary": _ALERT_MARKER_RE.sub("", ev.summary or ""),
"at": ev.ts,
"alert_id": details.get("alert_id"),
"details": details,
})
out.sort(key=lambda e: e["at"], reverse=True)
return out[:limit]
except Exception:
logger.debug("brief_state: handled_since unavailable", exc_info=True)
return []
def build_brief_fingerprint(
*,
today_data: dict[str, Any],
activity: list[dict[str, Any]],
handled: list[dict[str, Any]],
since: datetime | None,
pending_watch_suggestions: int = 0,
mode: str = "team",
live_keys: dict[str, Any] | None = None,
reflection_flags: str = "",
teammate_changes: str = "",
owner_notes: list[Any] | None = None,
getting_started: list[str] | None = None,
) -> str:
"""Stable hash of everything the brief would say. Deliberately free of
dates and timestamps so an unchanged day yields the same fingerprint
tomorrow (activity is keyed by kind + summary, never by its stamp).
``mode="solo"`` leaves out who is awaiting (the solo brief never says)
and carries the mode, so switching mode never suppresses the first brief
in the new one as "unchanged". Team fingerprints are unchanged.
Solo also carries ``due_soon`` (the DUE THIS WEEK items) as
``(loop_id, state)`` pairs — no dates — so a new item, a closed one, or
one that falls due today or goes overdue un-suppresses the brief. And
the TOP THREE TODAY items by key (in order — no dates, no slot times),
plus only a coarse hash of today's calendar (``top_three.calendar_hash``)
when one was read, so an unchanged day still suppresses.
``live_keys`` (``LiveSignals.keys`` — who wrote and about what, what is
stuck, the calendar's shape; no times) and ``reflection_flags`` make the
principal's actual world count: a brief is "unchanged" only when no mail
came in, nothing got stuck and the day looks the same. Both are carried
only when non-empty, so a caller that passes neither keeps its old
fingerprint. So is ``teammate_changes`` (the TEAMMATE CORRECTIONS block):
a correction a teammate made since the last brief un-suppresses it, since
the principal hears of it nowhere else. ``owner_notes`` (the FROM YOUR
NOTES keys, ``history_brief.NotesBlock.keys``: note ids and states, no
dates) likewise, only when non-empty, and ``getting_started`` (the first
week's GETTING STARTED keys, ``first_week.GettingStarted.keys``)."""
new, carried = split_proposals(today_data.get("proposals", []), since)
payload = {
"new": sorted(int(p.get("alert_id") or 0) for p in new),
"carried": sorted(int(p.get("alert_id") or 0) for p in carried),
"likely_stale": sum(1 for p in carried if p.get("review_verdict") == "likely_stale"),
"activity": sorted(
(str(a.get("kind", "")), str(a.get("summary", ""))[:80]) for a in activity
),
"handled": sorted((h["kind"], h["summary"][:80]) for h in handled),
# A rewrite alone must still un-suppress the brief now that it no
# longer rides in `handled` (keyed on the note, never the stamp). Same
# list the REWRITTEN block renders: carried items only — a new item
# already moves the fingerprint by id.
"rewritten": sorted(
(int(p.get("alert_id") or 0), str(p.get("review_note", ""))[:80])
for p in rewritten_since(carried, since)
),
"depts": sorted(
(d.get("slug", ""), d.get("at_risk_count", 0), d.get("off_track_count", 0))
for d in today_data.get("departments", [])
if d.get("at_risk_count", 0) or d.get("off_track_count", 0)
),
"awaiting": sorted(
int(p.get("id", 0)) for p in today_data.get("people", []) if p.get("awaiting_count", 0)
),
"watch_suggestions": int(pending_watch_suggestions),
}
if mode == "solo":
payload.pop("awaiting")
payload["mode"] = mode
due = today_data.get("due_soon") or []
if due:
# Only when present, so a solo fingerprint with nothing due is
# exactly what it was before this block existed.
payload["due_soon"] = sorted(
(int(d.get("loop_id") or 0), str(d.get("state", ""))) for d in due
)
top = today_data.get("top_three") or []
if top:
payload["top_three"] = [str(t.get("key", "")) for t in top]
calendar = today_data.get("today_calendar")
if isinstance(calendar, dict) and calendar.get("hash"):
payload["calendar"] = str(calendar["hash"])
if live_keys and any(live_keys.values()):
payload["live"] = live_keys
if reflection_flags:
payload["reflection_flags"] = reflection_flags
if teammate_changes:
payload["teammate_changes"] = teammate_changes
if owner_notes:
payload["owner_notes"] = [list(k) if isinstance(k, tuple) else k for k in owner_notes]
if getting_started:
payload["getting_started"] = sorted(getting_started)
blob = json.dumps(payload, sort_keys=True, default=str)
return hashlib.sha256(blob.encode("utf-8")).hexdigest()
_FLAGGED_RE = re.compile(
r"\*\*Flagged for the brief:?\*\*:?\s*(.*?)(?=\n\s*\*\*[^*\n]+:?\*\*|\n---|\Z)",
re.DOTALL | re.IGNORECASE,
)
_REFLECTION_FLAGS_MAX = 800
def reflection_flags_since(since: datetime) -> str:
"""The "Flagged for the brief" bullets of the latest executive reflection
that finished at/after ``since``, or "".
The reflection runs just before the morning brief and is told to write
what the principal should see there; nothing carried it across, so the
brief only ever saw an activity line with the run's title. Cut to a few
hundred characters. Never raises."""
try:
from openexecutive.workflows import persistence
for run in persistence.list_runs(
workflow_name="executive_reflection", status="done", limit=3, visible_to=None,
):
finished = parse_aware(run.get("updated_at"))
if finished is None or finished < since:
continue
full = persistence.get_run(str(run["run_id"])) or {}
match = _FLAGGED_RE.search(str(full.get("artifact") or ""))
if match is None:
return ""
text = match.group(1).strip()
if len(text) > _REFLECTION_FLAGS_MAX:
text = text[: _REFLECTION_FLAGS_MAX - 1].rstrip() + "…"
return text
except Exception:
logger.debug("brief_state: reflection flags unavailable", exc_info=True)
return ""
def suppress_unchanged_enabled() -> bool:
"""`PRINCIPAL_BRIEF_SUPPRESS_UNCHANGED`, defaulting to on when settings
cannot be built (bare test DB with no env)."""
try:
from openexecutive.config import get_settings
return bool(get_settings().principal_brief_suppress_unchanged)
except Exception:
return True
def suppressed_line(n_waiting: int) -> str:
return SUPPRESSED_TEMPLATE.format(n=n_waiting, s="" if n_waiting == 1 else "s")
def pending_watch_suggestions() -> int:
"""Research watch suggestions awaiting the principal on /watchlist.
Zero when the monitoring store is unavailable."""
try:
from openexecutive.monitoring import store as monitoring_store
return len(monitoring_store.list_pending_suggestions())
except Exception:
logger.debug("brief_state: pending_watch_suggestions unavailable", exc_info=True)
return 0
__all__ = [
"BRIEF_KINDS",
"CHANNEL_NAMES",
"DELIVERY_KINDS",
"DELIVERY_PROBLEMS",
"HANDLED_EVENT_KINDS",
"REVIEW_EVENT_TYPES",
"SUPPRESSED_TEMPLATE",
"DeliveryOutcome",
"DeliveryReason",
"describe_problem",
"brief_name",
"build_brief_fingerprint",
"channel_phrase",
"current_problem",
"handled_since",
"last_delivered",
"last_delivery_outcome",
"pending_watch_suggestions",
"record_delivered",
"record_delivery_outcome",
"rewritten_lines",
"rewritten_since",
"scope_for",
"since_for",
"split_proposals",
"suppress_unchanged_enabled",
"suppressed_line",
]