Skip to content

AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).

6.5 KB
Raw Blame
"""Mail backend contract + the one rendering every backend feeds the Executive.

Invariants every `MailProvider` MUST uphold:

1. `list_unread` / `fetch` / `mark_read` never raise on a transient or
   malformed backend response — return ``[]`` / ``None`` and log, so one bad
   poll cycle never kills the poller loop.
2. `fetch` derives `from_addr` with `email.utils.parseaddr` (or from a
   structured field), never by string-splitting a header: the address is
   interpolated into the `[POLICY]` notice the Executive reads.
3. `fetch` never surfaces a Reply-To-style redirect header. The Executive
   addresses replies itself; the gateway's roster gate is the enforcement,
   this keeps the attack surface out of the prompt entirely.
4. `build_send_arguments` produces the exact argument dict for
   `send_tool_name`, so alert dispatch and the poller never spell a backend
   shape themselves.
5. `reply_block` names the tool and the threading identifiers for replying to
   *this* message. It rides in the user turn (never in a cached system block —
   CLAUDE.md's caching rule), which is how the persona can stay backend-neutral.
"""
from __future__ import annotations

import re
from dataclasses import dataclass, field
from typing import Any, Protocol, runtime_checkable


@dataclass(frozen=True)
class MessageRef:
    """A message the poller has not fetched yet."""

    message_id: str
    thread_id: str = ""


@dataclass
class InboundMessage:
    """One fetched inbound message, backend-neutral.

    ``raw_text`` is the backend's own text rendering when it already has the
    RFC-822-ish shape the Executive expects (workspace-mcp's Gmail output);
    when set it is shown verbatim. Otherwise `render_for_executive` composes
    the same shape from the structured fields.
    """

    message_id: str
    thread_id: str
    from_addr: str
    from_name: str = ""
    subject: str = ""
    to: list[str] = field(default_factory=list)
    cc: list[str] = field(default_factory=list)
    body_text: str = ""
    has_attachments: bool = False
    attachments: list[str] = field(default_factory=list)
    raw_text: str | None = None


_ALL_MARKERS = ("BODY", "ATTACHMENTS", "REPLY")
# On a backend-rendered raw text (Gmail via workspace-mcp) the BODY and
# ATTACHMENTS markers are the server's own and cannot be told apart from a
# forged copy, so only REPLY — which no backend emits and which the persona
# reads the reply tool from — is neutralized there.
_RAW_TEXT_MARKERS = ("REPLY",)


def _neutralize_markers(text: str, markers: tuple[str, ...] = _ALL_MARKERS) -> str:
    """Defang section markers inside inbound text so a body cannot forge a
    ``--- REPLY ---`` block of its own ahead of the real one (the persona
    reads the reply tool from that block). Quoted, not removed — the
    Executive still sees what the sender wrote."""
    pattern = re.compile(r"^(\s*)---\s*(" + "|".join(markers) + r")\s*---", re.IGNORECASE)
    return "\n".join(pattern.sub(r"\1> --- \2 ---", line) for line in text.splitlines())


def _header_safe(value: str) -> str:
    """One header line: no CR/LF (a display name must not inject a header)."""
    return " ".join(value.replace("\r", " ").replace("\n", " ").split())


def render_message(msg: InboundMessage) -> str:
    """The message itself as the Executive reads it, the same shape for every
    backend: ``Subject:`` / ``From:`` / ``To:`` / ``Cc:`` header lines, a blank
    line, ``--- BODY ---``, the body, and an optional ``--- ATTACHMENTS ---``
    section. `email_poller._parse_recipients` reads the To/Cc lines (it stops
    at the first blank line), and the persona's inbound-email instructions
    refer to the ATTACHMENTS marker. All of it is the sender's text, so the
    poller hands it over labelled as untrusted content.
    """
    if msg.raw_text is not None:
        text = _neutralize_markers(msg.raw_text.rstrip("\n"), _RAW_TEXT_MARKERS)
    else:
        sender = _header_safe(msg.from_addr)
        if msg.from_name:
            sender = f"{_header_safe(msg.from_name)} <{sender}>"
        lines = [f"Subject: {_header_safe(msg.subject)}", f"From: {sender}"]
        if msg.to:
            lines.append("To: " + ", ".join(_header_safe(a) for a in msg.to))
        if msg.cc:
            lines.append("Cc: " + ", ".join(_header_safe(a) for a in msg.cc))
        lines += ["", "--- BODY ---", _neutralize_markers(msg.body_text.rstrip("\n"))]
        if msg.has_attachments or msg.attachments:
            lines += ["", "--- ATTACHMENTS ---", *msg.attachments]
        text = "\n".join(lines)
    return text


def render_reply_block(reply_block: str) -> str:
    """The ``--- REPLY ---`` block naming the reply tool and its threading
    identifiers. The poller's words, not the sender's: it goes after the
    message, outside its untrusted-content label."""
    return f"--- REPLY ---\n{reply_block.rstrip()}\n"


def render_for_executive(msg: InboundMessage, reply_block: str) -> str:
    """`render_message` followed by `render_reply_block`."""
    return f"{render_message(msg)}\n\n{render_reply_block(reply_block)}"


@runtime_checkable
class MailProvider(Protocol):
    """Protocol every mail backend satisfies. See the module docstring for the
    invariants; `google.GoogleMail` and `microsoft.MicrosoftMail` implement it."""

    name: str
    server_name: str
    send_tool_name: str
    discovery_queries: tuple[str, ...]

    async def list_unread(self, gateway: Any, mailbox: str, limit: int) -> list[MessageRef]:
        """Unread inbox messages, newest first. ``[]`` on any failure."""
        ...

    async def fetch(self, gateway: Any, ref: MessageRef, mailbox: str) -> InboundMessage | None:
        """The full message, or ``None`` when the backend returned nothing usable."""
        ...

    async def mark_read(self, gateway: Any, ref: MessageRef, mailbox: str) -> None:
        """Mark the message read so the next poll does not see it again. Never raises."""
        ...

    def build_send_arguments(
        self,
        *,
        mailbox: str,
        to: str,
        subject: str,
        body: str,
        thread_id: str | None = None,
        html: bool = False,
    ) -> dict[str, Any]:
        """Arguments for `send_tool_name` — a message from ``mailbox``, plain
        text unless ``html``."""
        ...

    def reply_block(self, msg: InboundMessage) -> str:
        """The ``--- REPLY ---`` block: which tool replies to ``msg`` and how."""
        ...

    def send_tool_hint(self) -> str:
        """Prose for the scheduler's proactive-email trigger naming the send tool."""
        ...