Skip to content

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

65.3 KB
Raw Blame
"""A direct Gmail client for one person's own mailbox (Act as me).

The Executive's own mailbox is reached through the MCP gateway, where the
model can call any Gmail tool by name. A mailbox someone lent the Executive
must never be reachable that way, so this client talks to the Gmail REST API
itself and is never registered with the gateway: only typed handlers
(``orchestrator.delegation_tools``, the voice learner, the inbox watcher and
the reply cards) call it.

**Credential.** One file per person in ``DELEGATION_GOOGLE_CREDENTIALS_DIR``,
named from a hash of the address and written by
``scripts/connect-own-gmail.py``: ``{"version": 1, "email": ..., "authorized_user":
{refresh_token, client_id, client_secret, token_uri}}``. It is never in
``WORKSPACE_MCP_CREDENTIALS_DIR`` — workspace-mcp picks a credential there by
address, which would hand the model this mailbox. Scopes: ``gmail.readonly``
and ``gmail.compose``, and a calendar scope when they connected with
``--calendar`` for Read my calendar (``delegation.calendar``; ``list_events``
refuses with ``CalendarNotGranted`` without it): ``calendar.events`` now,
which also lets it answer a meeting invite as them (``answer_invite``,
``delegation.invites``); a sign-in made with ``calendar.readonly`` before
keeps reading, and ``answer_invite`` refuses with ``CalendarWriteNotGranted``.

**One way to send.** It reads mail and saves or deletes drafts. The only
send is ``send_draft``: an existing draft, by its id, exactly as it is in
Gmail (the request body is the id and nothing else). Only
``delegation.reply_send`` calls it, after the person tapped Send on that
draft's card; unit tests pin the public methods, the one send endpoint and
that call site.

**Outlook too.** A person may connect an Outlook mailbox instead
(``scripts/connect-own-outlook.py``, which writes ``"provider": "microsoft"``
into the same file). ``gmail_for`` then hands back
``delegation.outlook.DelegateOutlook``, which keeps this client's methods,
return types and errors, so every caller works with either mailbox.

**Always checked.** ``gmail_status`` asks Google whose mailbox the token opens
and compares it with the person's People email on every use — a roster email
can change, and a client slot swaps the roster — and refuses the Executive's
own address outright (a "shared mailbox" would make everything the Executive
writes look like the person's).
"""
from __future__ import annotations

import asyncio
import base64
import hashlib
import html
import json
import logging
import re
import time
from dataclasses import dataclass, field, replace
from datetime import UTC, datetime
from email.message import EmailMessage, Message
from email.utils import formataddr, getaddresses
from pathlib import Path
from typing import Any, Literal
from urllib.parse import quote

import httpx

from openexecutive.utils.html_tags import strip_tags

logger = logging.getLogger(__name__)

GMAIL_BASE = "https://gmail.googleapis.com/gmail/v1/users/me"
DEFAULT_TOKEN_URI = "https://oauth2.googleapis.com/token"
SCOPE_READONLY = "https://www.googleapis.com/auth/gmail.readonly"
SCOPE_COMPOSE = "https://www.googleapis.com/auth/gmail.compose"
SCOPES: tuple[str, ...] = (SCOPE_READONLY, SCOPE_COMPOSE)
# Read my calendar (delegation.calendar): optional, so a mail-only sign-in still works.
SCOPE_CALENDAR = "https://www.googleapis.com/auth/calendar.readonly"
# What --calendar asks for now: reads, and answers a meeting invite as them
# (delegation.invites). Either scope reads; only this one (or the full
# calendar scope) answers.
SCOPE_CALENDAR_EVENTS = "https://www.googleapis.com/auth/calendar.events"
_SCOPE_CALENDAR_FULL = "https://www.googleapis.com/auth/calendar"
CALENDAR_READ_SCOPES = frozenset({SCOPE_CALENDAR, SCOPE_CALENDAR_EVENTS, _SCOPE_CALENDAR_FULL})
CALENDAR_WRITE_SCOPES = frozenset({SCOPE_CALENDAR_EVENTS, _SCOPE_CALENDAR_FULL})
CALENDAR_BASE = "https://www.googleapis.com/calendar/v3/calendars/primary"
CREDENTIAL_VERSION = 1
PROVIDER = "google"

# Marks a draft this package wrote. Best-effort only: Gmail may rebuild a
# draft when it is sent from its own UI.
GHOSTWRITTEN_HEADER = "X-OE-Ghostwritten"

GmailStatus = Literal[
    "connected",
    "not_configured",
    "needs_reconnect",
    "mismatch",
    "no_email",
    "shared_mailbox",
    "error",
]

# What each status tells the person, in the tool result and on Settings.
# A status that blocks using the mailbox → the 409 code a caller gets.
BLOCKING_CODES: dict[str, str] = {
    "not_configured": "gmail_not_connected",
    "needs_reconnect": "gmail_needs_reconnect",
    "mismatch": "gmail_mismatch",
    "no_email": "no_email",
    "shared_mailbox": "shared_mailbox",
    "error": "gmail_error",
}

STATUS_MESSAGES: dict[str, str] = {
    "connected": "Connected.",
    "not_configured": (
        "Your mailbox isn't connected. Run scripts/connect-own-gmail.py (Gmail) or "
        "scripts/connect-own-outlook.py (Outlook) as yourself (Delegate → Act as me "
        "shows how)."
    ),
    "needs_reconnect": (
        "Your mailbox no longer accepts the saved sign-in. Connect it again with "
        "scripts/connect-own-gmail.py or scripts/connect-own-outlook.py."
    ),
    "mismatch": (
        "The connected mailbox isn't the address on your People entry. Connect that "
        "account, or correct your email on the People page."
    ),
    "no_email": "Your People entry has no email address. Add it on the People page first.",
    "shared_mailbox": (
        "Your address is the Executive's own mailbox, so it can't write as you from "
        "it. Give the Executive a Google account of its own first."
    ),
    "error": "Couldn't reach your mailbox just now. Try again in a moment.",
}

# Gmail ids are short hex strings; anything else never reaches a URL path.
_ID_RE = re.compile(r"[A-Za-z0-9_-]{1,64}")
# Google Calendar event ids: base32hex, with an instance's "_" suffix.
_EVENT_ID_RE = re.compile(r"[A-Za-z0-9_]{1,1024}")
# A forward's attached files, at most (Gmail's own message limit is 25 MB).
FORWARD_MAX_FILES = 10
FORWARD_MAX_BYTES = 20 * 1024 * 1024
# Gmail's attachment ids are far longer than its message ids.
_ATTACHMENT_ID_RE = re.compile(r"[A-Za-z0-9_-]{1,4096}")
_EMAIL_RE = re.compile(r"[\w.+\-]+@[\w\-]+(?:\.[\w\-]+)+")
_TOKEN_URI_RE = re.compile(r"^https://oauth2\.googleapis\.com/")
_MAX_HEADER = 900
_TOKEN_SLACK_SECONDS = 60
_FETCH_CONCURRENCY = 5

# Access tokens by (address, refresh token) — never written anywhere.
_TOKENS: dict[str, tuple[str, float]] = {}
# The scopes Google said each of those tokens carries ("" when it didn't say).
_GRANTED: dict[str, str] = {}
# Events one calendar read returns, at most.
MAX_EVENTS = 100


class GmailError(Exception):
    """A Gmail call failed (network, 5xx, an unexpected response).
    ``maybe_done`` is True when the request may have reached Google and been
    carried out anyway (a timeout after sending, a 5xx, an unreadable
    success): for a send, not knowing is not the same as not sent."""

    def __init__(self, message: str = "", *, maybe_done: bool = False) -> None:
        super().__init__(message)
        self.maybe_done = maybe_done


class GmailNotConfigured(GmailError):
    """No credential for this address."""


class GmailRateLimited(GmailError):
    """Gmail asked us to slow down (429, or a quota 403): back off, don't
    reconnect."""


class GmailNotFound(GmailError):
    """No such message, thread or draft (404). For a draft: sent or deleted."""


class DraftChanged(GmailError):
    """A draft can't be rewritten from the card: it changed in the mailbox
    since it was last read (``reason`` "changed"), or it holds more than plain
    text, such as files ("not_plain")."""

    def __init__(self, reason: str) -> None:
        super().__init__(f"draft {reason}")
        self.reason = reason


class CalendarNotGranted(GmailError):
    """Their saved sign-in doesn't let the Executive read their calendar:
    they connected without it (``--calendar``), or took it back."""


class CalendarWriteNotGranted(GmailError):
    """Their saved sign-in reads their calendar but can't answer an invite:
    it was made with read-only access (``calendar.readonly``,
    ``Calendars.Read``). Connecting again with ``--calendar`` adds it."""


class GmailChanged(GmailError):
    """The item changed since it was read (an ``If-Match`` didn't match)."""


class GmailAuthError(GmailError):
    """Google refused the credential: revoked, expired, or missing a scope."""


@dataclass(frozen=True)
class GmailCredential:
    email: str
    refresh_token: str
    client_id: str
    client_secret: str
    token_uri: str = DEFAULT_TOKEN_URI


@dataclass(frozen=True)
class CalendarEvent:
    """One event on someone's own calendar, as Read my calendar shows it.
    ``start`` / ``end`` are ISO 8601 (a date alone for an all-day event)."""

    id: str
    title: str
    start: str
    end: str
    all_day: bool = False
    location: str = ""
    organizer: str = ""
    attendees: tuple[str, ...] = ()
    # Their own answer: accepted, declined, tentative, needs_action, organizer.
    response: str = ""


_ATTENDEES_MAX = 25


def _google_who(entry: Any) -> str:
    if not isinstance(entry, dict):
        return ""
    name = clean_header(str(entry.get("displayName") or ""))
    address = normalize_email(str(entry.get("email") or ""))
    return f"{name} <{address}>" if name and address else (name or address)


def _google_when(value: Any) -> tuple[str, bool]:
    if not isinstance(value, dict):
        return "", False
    if value.get("dateTime"):
        return str(value["dateTime"]), False
    return str(value.get("date") or ""), True


def parse_google_event(raw: dict[str, Any]) -> CalendarEvent | None:
    """A Google Calendar event, or None for one that isn't on their day
    (cancelled, or a working-location marker)."""
    if raw.get("status") == "cancelled" or raw.get("eventType") == "workingLocation":
        return None
    start, all_day = _google_when(raw.get("start"))
    end, _ = _google_when(raw.get("end"))
    if not start:
        return None
    attendees = [a for a in raw.get("attendees") or [] if isinstance(a, dict)]
    own = next((a for a in attendees if a.get("self")), None)
    organizer_raw = raw.get("organizer")
    organizer: dict[str, Any] = organizer_raw if isinstance(organizer_raw, dict) else {}
    if organizer.get("self"):
        response = "organizer"
    else:
        response = {
            "accepted": "accepted", "declined": "declined", "tentative": "tentative", "needsAction": "needs_action",
        }.get(str((own or {}).get("responseStatus") or ""), "")
    return CalendarEvent(
        id=str(raw.get("id") or ""),
        title=clean_header(str(raw.get("summary") or "")) or "(no title)",
        start=start,
        end=end,
        all_day=all_day,
        location=clean_header(str(raw.get("location") or "")),
        organizer=_google_who(organizer),
        attendees=tuple(w for w in (_google_who(a) for a in attendees[:_ATTENDEES_MAX] if not a.get("self")) if w),
        response=response,
    )


@dataclass
class MailAttachment:
    """A file attached to a message: its place among the message's
    attachments (1-based), and what the mailbox says it is. The provider's
    own id is looked up afresh when it is read (Gmail's changes per fetch)."""

    index: int
    name: str
    mime_type: str = ""
    size: int = 0


@dataclass
class MailMessage:
    id: str
    thread_id: str
    from_addr: str = ""
    from_name: str = ""
    to: list[str] = field(default_factory=list)
    cc: list[str] = field(default_factory=list)
    reply_to: str = ""
    subject: str = ""
    date: str = ""
    message_id_header: str = ""
    references: str = ""
    labels: list[str] = field(default_factory=list)
    text: str = ""
    mailing_list: bool = False
    auto_generated: bool = False
    ghostwritten: bool = False
    bcc: list[str] = field(default_factory=list)
    # When Gmail received it (internalDate, ISO in UTC), not the Date header
    # the sender wrote; "" when unknown.
    received_at: str = ""
    # Bulk or auto-reply mail (by its headers), a delivery report (a
    # bounce), a calendar invite: nobody wrote it for this reader.
    bulk: bool = False
    delivery_report: bool = False
    calendar_invite: bool = False
    # Gmail's own Authentication-Results found From's domain authenticated
    # (dmarc=pass): who it says it is from is who it is from.
    sender_authenticated: bool = False
    # Files attached to it. Gmail lists them with the message; Outlook only
    # says whether there are any (``has_attachments``) until asked
    # (``list_attachments``).
    attachments: list[MailAttachment] = field(default_factory=list)
    has_attachments: bool = False
    # The display name each To / Cc address was written with, as the
    # sender's own mail app put it ("" for none). Names a contact the
    # person writes to (``people.contact_keeper``).
    names: dict[str, str] = field(default_factory=dict)
    # A calendar invite's own iCalendar method (REQUEST, CANCEL, REPLY, ...)
    # and event UID, from its text/calendar part ("" when it has none, or
    # it is only attached as a file). Outlook leaves them empty: Graph
    # names the event itself (``find_invite``).
    invite_method: str = ""
    invite_uid: str = ""


@dataclass
class MailThread:
    id: str
    messages: list[MailMessage]


@dataclass
class ThreadSummary:
    id: str
    subject: str
    sender: str
    date: str
    # The mail service found the sender's domain authenticated
    # (``MailMessage.sender_authenticated``); False when it can't tell.
    sender_authenticated: bool = False


# The headers a search reads of each thread's newest message: what it lists,
# and what proving its sender takes (``headers_authenticated``, which a list's
# own headers make fail).
_SUMMARY_HEADERS = (
    "Subject", "From", "Date", "Authentication-Results", "List-Id", "X-Google-Group-Id", "Mailing-List",
)


@dataclass
class ForwardOf:
    """The message a draft forwards (``DraftSpec.forward``): the provider's
    id for it, and the header block and text Gmail quotes under the note.
    Outlook forwards by id (``createForward``), original and files included;
    Gmail's draft quotes ``header`` and ``text`` and attaches the message's
    files itself (``DelegateGmail.create_draft``)."""

    message_id: str
    header: str
    text: str


@dataclass
class DraftSpec:
    to: list[str]
    subject: str
    body: str
    cc: list[str] = field(default_factory=list)
    thread_id: str | None = None
    in_reply_to: str | None = None
    references: str | None = None
    from_name: str = ""
    # One of the person's own send-as addresses to write from (the one the
    # mail being answered went to); None is their primary address.
    from_addr: str | None = None
    # A forward instead of a reply or a new email: the body is the note above it.
    forward: ForwardOf | None = None
    # Files to attach (name, MIME type, bytes): a forward's, on Gmail.
    attachments: list[tuple[str, str, bytes]] = field(default_factory=list)


@dataclass
class CreatedDraft:
    draft_id: str
    message_id: str
    thread_id: str
    # A forward's files that were left off (too many or too large).
    skipped_attachments: int = 0


@dataclass
class SentMessage:
    """What ``send_draft`` sent: the new message's id and its thread."""

    id: str
    thread_id: str


@dataclass
class DraftInfo:
    """A draft as Gmail holds it now: its id and its current message (which
    gets a new id each time the draft is edited)."""

    draft_id: str
    message: MailMessage


# --------------------------------------------------------------------------- #
# Credential file
# --------------------------------------------------------------------------- #


def normalize_email(email: str | None) -> str:
    return (email or "").strip().lower()


def email_key(email: str) -> str:
    """The credential file's stem for ``email`` (so the address is not in a
    file name on the volume)."""
    return hashlib.sha256(normalize_email(email).encode()).hexdigest()[:16]


def credentials_dir() -> Path:
    from openexecutive.config import get_settings

    return Path(get_settings().delegation_google_credentials_dir)


def credential_path(email: str, *, directory: Path | None = None) -> Path:
    return (directory or credentials_dir()) / f"{email_key(email)}.json"


def credential_provider(email: str, *, directory: Path | None = None) -> str:
    """Which mailbox ``email``'s credential file opens: ``"google"`` (also
    for a file with no provider, or none at all) or ``"microsoft"``."""
    address = normalize_email(email)
    if not address:
        return PROVIDER
    try:
        data = json.loads(credential_path(address, directory=directory).read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return PROVIDER
    return "microsoft" if isinstance(data, dict) and data.get("provider") == "microsoft" else PROVIDER


def load_credential(email: str, *, directory: Path | None = None) -> GmailCredential | None:
    """The stored credential for ``email``, or None when there is none or it
    is unreadable (logged). A file naming another address is ignored."""
    address = normalize_email(email)
    if not address:
        return None
    path = credential_path(address, directory=directory)
    if not path.is_file():
        return None
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, ValueError):
        logger.warning("delegation.gmail: unreadable credential file %s", path.name)
        return None
    if not isinstance(data, dict) or data.get("provider", PROVIDER) != PROVIDER:
        return None
    if normalize_email(str(data.get("email") or "")) != address:
        logger.warning("delegation.gmail: credential file %s is for another address", path.name)
        return None
    user = data.get("authorized_user")
    if not isinstance(user, dict):
        return None
    values = {k: user.get(k) for k in ("refresh_token", "client_id", "client_secret")}
    if not all(isinstance(v, str) and v for v in values.values()):
        logger.warning("delegation.gmail: credential file %s is incomplete", path.name)
        return None
    token_uri = user.get("token_uri") or DEFAULT_TOKEN_URI
    if not isinstance(token_uri, str) or not _TOKEN_URI_RE.match(token_uri):
        logger.warning("delegation.gmail: credential file %s names an unexpected token endpoint", path.name)
        return None
    return GmailCredential(
        email=address,
        refresh_token=str(values["refresh_token"]),
        client_id=str(values["client_id"]),
        client_secret=str(values["client_secret"]),
        token_uri=token_uri,
    )


# --------------------------------------------------------------------------- #
# Parsing
# --------------------------------------------------------------------------- #


def _b64decode(data: str) -> bytes:
    return base64.urlsafe_b64decode(data + "=" * (-len(data) % 4))


def _headers(payload: dict[str, Any]) -> dict[str, str]:
    out: dict[str, str] = {}
    for h in payload.get("headers") or []:
        if isinstance(h, dict) and isinstance(h.get("name"), str):
            out.setdefault(h["name"].lower(), str(h.get("value") or ""))
    return out


# Everything here runs on mail anyone can send, on the event loop, so each step
# is one forward pass: these patterns end at the next "<" as well as at ">",
# and no two quantifiers compete for the same characters.
_BR_RE = re.compile(r"(?i)<\s*(?:/\s*)?br\b[^<>]*>")
# Opening and closing tags alike: Gmail puts a signature's first line straight
# in its outer <div> and each later line in a <div> of its own.
_BLOCK_EDGE_RE = re.compile(
    r"(?i)<\s*(?:/\s*)?(?:address|article|aside|blockquote|center|dd|div|dl|dt|figcaption|figure|"
    r"footer|h[1-6]|header|hr|li|main|nav|ol|p|pre|section|table|tr|ul)\b[^<>]*>"
)
_HIDDEN = {
    name: (re.compile(rf"(?i)<{name}\b"), re.compile(rf"(?i)</{name}\s*>")) for name in ("script", "style")
}
_DECIMAL_REF_RE = re.compile(r"&#(\d+)(;?)")
_EDGE = "\x00"


def _short_decimal_ref(match: re.Match[str]) -> str:
    # html.unescape turns the digits into an int, and Python refuses more than
    # 4,300 of them (ValueError). Beyond seven significant digits the value is
    # past Unicode's range, which unescape reads as U+FFFD anyway.
    digits = match.group(1).lstrip("0") or "0"
    return "�" if len(digits) > 7 else f"&#{digits}{match.group(2)}"


def _drop_hidden(markup: str) -> str:
    """``markup`` without its ``<script>`` and ``<style>`` elements, in one
    pass each: an element nothing closes is left for the tag strip."""
    for opening, closing in _HIDDEN.values():
        out: list[str] = []
        at = 0
        while (start := opening.search(markup, at)) is not None:
            end = closing.search(markup, start.end())
            if end is None:
                break
            out.append(markup[at:start.start()])
            at = end.end()
        out.append(markup[at:])
        markup = "".join(out)
    return markup


def html_to_text(markup: str) -> str:
    """Plain text from an HTML body or signature. A ``<br>`` (or a line break
    in the markup) always ends a line; a block's opening or closing tag ends
    one only when it has text, so ``</div><div>`` is a single break and
    ``<div><br></div>`` a blank line."""
    text = _drop_hidden(markup.replace(_EDGE, ""))
    text = _BLOCK_EDGE_RE.sub(_EDGE, _BR_RE.sub("\n", text))
    text = html.unescape(_DECIMAL_REF_RE.sub(_short_decimal_ref, strip_tags(text)))
    out: list[str] = []
    has_text = False
    for piece in re.split(f"({_EDGE}|\n)", text):
        if piece == "\n" or (piece == _EDGE and has_text):
            out.append("\n")
            has_text = False
        elif piece != _EDGE:
            out.append(piece)
            # Only markup whitespace: a line of &nbsp; is a line the reader sees.
            has_text = has_text or bool(piece.strip(" \t\r\n\f\v"))
    lines = [ln.rstrip() for ln in "".join(out).splitlines()]
    return re.sub(r"\n{3,}", "\n\n", "\n".join(lines)).strip()


def _part_text(part: dict[str, Any]) -> str:
    data = (part.get("body") or {}).get("data")
    if not isinstance(data, str) or not data:
        return ""
    try:
        return _b64decode(data).decode("utf-8", errors="replace")
    except (ValueError, TypeError):
        return ""


def _body_text(payload: dict[str, Any]) -> str:
    """The message's plain text: its text/plain part, else its HTML as text."""
    plain: list[str] = []
    markup: list[str] = []
    stack = [payload]
    while stack:
        part = stack.pop(0)
        mime = str(part.get("mimeType") or "").lower()
        if mime == "text/plain":
            plain.append(_part_text(part))
        elif mime == "text/html":
            markup.append(_part_text(part))
        stack.extend(p for p in part.get("parts") or [] if isinstance(p, dict))
    if any(t.strip() for t in plain):
        return "\n".join(t for t in plain if t.strip()).strip()
    return html_to_text("\n".join(markup))


def _addresses(value: str) -> list[str]:
    return [normalize_email(addr) for _, addr in getaddresses([value]) if "@" in addr]


def _names(*values: str) -> dict[str, str]:
    """Each address in the ``values`` headers with the name written next to it."""
    out: dict[str, str] = {}
    for name, addr in getaddresses(list(values)):
        if "@" in addr:
            out.setdefault(normalize_email(addr), clean_header(name))
    return out


def _hide_tokens(text: str) -> str:
    """``text`` with the Executive's one-time answer tokens hidden. The
    owner's own mailbox holds the roster and standing-fact confirmation
    emails the Executive sent them; the drafting model must never read a live
    token (``mcp_gateway.hide_roster_tokens`` does the same for the
    Executive's mailbox)."""
    from openexecutive.orchestrator.mcp_gateway import hide_roster_tokens

    return hide_roster_tokens(text)


_REPORT_SENDERS = ("mailer-daemon", "postmaster")
_BULK_PRECEDENCE = frozenset({"bulk", "junk", "list", "auto_reply"})
# Set by out-of-office and other auto-responders.
_AUTOREPLY_HEADERS = ("x-autoreply", "x-autorespond", "x-autoresponder")
_CALENDAR_TYPES = frozenset({"text/calendar", "application/ics"})
_ICS_UID_MAX = 1024


def ics_invite(text: str) -> tuple[str, str]:
    """An iCalendar text's method and its first event's UID, ``("", "")``
    when it has neither. Only these two are read: nothing else in the file
    (its title, its description) is used from here."""
    unfolded = re.sub(r"\r?\n[ \t]", "", text or "")
    method = uid = ""
    in_event = False
    for line in unfolded.splitlines():
        name, sep, value = line.partition(":")
        if not sep:
            continue
        key = name.split(";", 1)[0].strip().upper()
        if key == "BEGIN" and value.strip().upper() == "VEVENT":
            in_event = True
        elif key == "END" and value.strip().upper() == "VEVENT":
            if uid:
                break
            in_event = False
        elif key == "METHOD" and not in_event and not method:
            method = value.strip().upper()[:20]
        elif key == "UID" and in_event and not uid:
            candidate = value.strip()
            if 0 < len(candidate) <= _ICS_UID_MAX and candidate.isprintable():
                uid = candidate
    return method, uid


def _invite_part(payload: dict[str, Any]) -> tuple[str, str]:
    """The method and UID of the message's inline text/calendar part."""
    stack = [payload]
    while stack:
        part = stack.pop(0)
        if str(part.get("mimeType") or "").lower() in _CALENDAR_TYPES:
            found = ics_invite(_part_text(part))
            if found[1]:
                return found
        stack.extend(p for p in part.get("parts") or [] if isinstance(p, dict))
    return "", ""


def _header_message(payload: dict[str, Any]) -> Message:
    """The payload's headers, in order and with repeats, as an ``email``
    Message — what the DMARC and out-of-office checks read."""
    msg = Message()
    for h in payload.get("headers") or []:
        if isinstance(h, dict) and isinstance(h.get("name"), str):
            value = str(h.get("value") or "").replace("\r", " ").replace("\n", " ")
            try:
                msg[h["name"]] = value
            except (ValueError, TypeError):
                continue
    return msg


def _part_types(payload: dict[str, Any]) -> set[str]:
    types: set[str] = set()
    stack = [payload]
    while stack:
        part = stack.pop()
        types.add(str(part.get("mimeType") or "").lower())
        stack.extend(p for p in part.get("parts") or [] if isinstance(p, dict))
    return types


def _attachment_parts(payload: dict[str, Any]) -> list[dict[str, Any]]:
    """The message's attached files, in the order Gmail lists its parts: any
    part that names a file, but an image the HTML body shows in place (one
    with a Content-ID, such as a signature's logo)."""
    out: list[dict[str, Any]] = []
    stack = [payload]
    while stack:
        part = stack.pop(0)
        embedded = str(part.get("mimeType") or "").lower().startswith("image/") and "content-id" in _headers(part)
        if str(part.get("filename") or "").strip() and not embedded:
            out.append(part)
        stack.extend(p for p in part.get("parts") or [] if isinstance(p, dict))
    return out


def _attachments(payload: dict[str, Any]) -> list[MailAttachment]:
    out = []
    for i, part in enumerate(_attachment_parts(payload), 1):
        size = (part.get("body") or {}).get("size")
        out.append(MailAttachment(
            index=i,
            name=str(part.get("filename") or "").strip(),
            mime_type=str(part.get("mimeType") or "").lower(),
            size=size if isinstance(size, int) else 0,
        ))
    return out


def _received_at(raw: dict[str, Any]) -> str:
    try:
        ms = int(str(raw.get("internalDate") or ""))
    except ValueError:
        return ""
    return datetime.fromtimestamp(ms / 1000, UTC).isoformat()


def parse_message(raw: dict[str, Any]) -> MailMessage:
    """A Gmail API ``format=full`` message as a ``MailMessage``, with any
    one-time answer token hidden (``_hide_tokens``)."""
    from openexecutive.integrations.fact_confirmation import headers_authenticated

    raw_payload = raw.get("payload")
    payload: dict[str, Any] = raw_payload if isinstance(raw_payload, dict) else {}
    headers = _headers(payload)
    header_msg = _header_message(payload)
    sender = getaddresses([headers.get("from", "")])
    from_name, from_addr = sender[0] if sender else ("", "")
    auto = headers.get("auto-submitted", "no").strip().lower() not in ("", "no")
    types = _part_types(payload)
    local_part = normalize_email(from_addr).partition("@")[0]
    attachments = _attachments(payload)
    invite_method, invite_uid = _invite_part(payload) if types & _CALENDAR_TYPES else ("", "")
    return MailMessage(
        id=str(raw.get("id") or ""),
        thread_id=str(raw.get("threadId") or ""),
        from_addr=normalize_email(from_addr),
        from_name=from_name.strip(),
        to=_addresses(headers.get("to", "")),
        cc=_addresses(headers.get("cc", "")),
        reply_to=",".join(_addresses(headers.get("reply-to", ""))),
        subject=_hide_tokens(headers.get("subject", "").strip()),
        date=headers.get("date", "").strip(),
        message_id_header=headers.get("message-id", "").strip(),
        references=headers.get("references", "").strip(),
        labels=[str(label) for label in raw.get("labelIds") or []],
        text=_hide_tokens(_body_text(payload)),
        mailing_list=bool(headers.get("list-unsubscribe") or headers.get("list-id")),
        auto_generated=auto or "calendar-notification" in headers.get("sender", "").lower(),
        ghostwritten=bool(headers.get(GHOSTWRITTEN_HEADER.lower())),
        bcc=_addresses(headers.get("bcc", "")),
        received_at=_received_at(raw),
        bulk=headers.get("precedence", "").strip().lower() in _BULK_PRECEDENCE
        or any(name in headers for name in _AUTOREPLY_HEADERS),
        delivery_report="multipart/report" in types or local_part in _REPORT_SENDERS,
        calendar_invite=bool(types & _CALENDAR_TYPES),
        sender_authenticated=headers_authenticated(header_msg, normalize_email(from_addr)),
        attachments=attachments,
        has_attachments=bool(attachments),
        names=_names(headers.get("to", ""), headers.get("cc", "")),
        invite_method=invite_method,
        invite_uid=invite_uid,
    )


# --------------------------------------------------------------------------- #
# Drafts
# --------------------------------------------------------------------------- #


def clean_header(value: str) -> str:
    """One header value, with no line breaks or control characters, capped."""
    cleaned = "".join(ch if ch >= " " else " " for ch in value.replace("\r", " ").replace("\n", " "))
    return " ".join(cleaned.split())[:_MAX_HEADER]


_MESSAGE_ID = re.compile(r"<[^<>\s]+>")


def references_header(prior: str, parent: str) -> str | None:
    """The References of a reply to ``parent`` (a Message-ID) whose own
    References were ``prior``: whole ids only, the parent always last. When
    the chain is too long for one header, the oldest ids after the thread's
    first one go — never half an id, and never the parent."""
    parents = _MESSAGE_ID.findall(parent or "")[-1:]
    ids = [i for i in dict.fromkeys(_MESSAGE_ID.findall(prior or "")) if i not in parents] + parents
    if not ids:
        return None
    while len(ids) > 2 and len(" ".join(ids)) > _MAX_HEADER:
        del ids[1]
    if len(" ".join(ids)) > _MAX_HEADER:
        ids = ids[-1:]
    joined = " ".join(ids)
    # A single id too long for the header: none beats half of one.
    return joined if len(joined) <= _MAX_HEADER else None


def build_raw(sender: str, spec: DraftSpec) -> str:
    """The draft as a base64url RFC 2822 message (Gmail's ``raw``)."""
    msg = EmailMessage()
    name = clean_header(spec.from_name)
    sender = clean_header(spec.from_addr) if spec.from_addr else sender
    msg["From"] = formataddr((name, sender)) if name else sender
    msg["To"] = ", ".join(clean_header(a) for a in spec.to)
    if spec.cc:
        msg["Cc"] = ", ".join(clean_header(a) for a in spec.cc)
    msg["Subject"] = clean_header(spec.subject)
    if spec.in_reply_to:
        msg["In-Reply-To"] = clean_header(spec.in_reply_to)
    if spec.references:
        msg["References"] = clean_header(spec.references)
    msg[GHOSTWRITTEN_HEADER] = "1"
    body = spec.body
    if spec.forward is not None:
        body = f"{spec.body}\n\n{spec.forward.header}\n\n{spec.forward.text}"
    msg.set_content(body)
    for name, mime, data in spec.attachments:
        maintype, _, subtype = (mime or "application/octet-stream").partition("/")
        msg.add_attachment(
            data, maintype=maintype or "application", subtype=subtype or "octet-stream",
            filename=clean_header(name) or "attachment",
        )
    return base64.urlsafe_b64encode(msg.as_bytes()).decode("ascii")


def gmail_link(email: str, *, thread_id: str | None = None, message_id: str | None = None) -> str:
    """A link that opens the draft in Gmail, built from a fixed prefix: the
    thread for a reply, the draft itself for a new email."""
    base = f"https://mail.google.com/mail/u/?authuser={quote(normalize_email(email))}"
    if thread_id and _ID_RE.fullmatch(thread_id):
        return f"{base}#all/{thread_id}"
    if message_id and _ID_RE.fullmatch(message_id):
        return f"{base}#drafts?compose={message_id}"
    return f"{base}#drafts"


def valid_id(value: object) -> bool:
    return isinstance(value, str) and bool(_ID_RE.fullmatch(value))


# Every link ``mailbox_link`` builds starts with one of these; the chat chip
# and the reply cards (packages/ui/src/lib/replyCards.ts) link nowhere else.
MAILBOX_LINK_PREFIXES: tuple[str, ...] = (
    "https://mail.google.com/",
    "https://outlook.office.com/mail/",
    "https://outlook.live.com/mail/",
)


def mailbox_link(
    email: str,
    *,
    thread_id: str | None = None,
    message_id: str | None = None,
    draft_id: str | None = None,
) -> str:
    """A link that opens a draft in the person's own mailbox, whichever it
    is. Gmail opens the thread for a reply (``thread_id``), else the draft by
    its message id; Outlook opens the draft itself (``draft_id``, else
    ``message_id``), as Outlook on the web has no link to a conversation."""
    if credential_provider(email) != "microsoft":
        return gmail_link(email, thread_id=thread_id, message_id=message_id)
    from openexecutive.delegation.outlook import load_credential as load_outlook
    from openexecutive.delegation.outlook import outlook_link

    cred = load_outlook(email)
    return outlook_link(personal=bool(cred and cred.personal), message_id=draft_id or message_id)


# --------------------------------------------------------------------------- #
# Client
# --------------------------------------------------------------------------- #


# Gmail answers some quota errors with 403, not 429: slow down, don't reconnect.
_RATE_LIMIT_REASONS = frozenset({"rateLimitExceeded", "userRateLimitExceeded", "dailyLimitExceeded", "quotaExceeded"})


def _rate_limited(resp: httpx.Response) -> bool:
    """Whether a 403 is Gmail's rate limit rather than a refused sign-in."""
    try:
        errors = resp.json().get("error", {}).get("errors", [])
    except (ValueError, AttributeError):
        return False
    if not isinstance(errors, list):
        return False
    return any(isinstance(e, dict) and e.get("reason") in _RATE_LIMIT_REASONS for e in errors)


def _token_key(cred: GmailCredential) -> str:
    return hashlib.sha256(f"{cred.email}\n{cred.refresh_token}".encode()).hexdigest()


class DelegateGmail:
    """One person's mailbox. ``transport`` is for tests (httpx MockTransport)."""

    provider = PROVIDER
    valid_id = staticmethod(valid_id)

    def __init__(
        self,
        email: str,
        *,
        credential: GmailCredential | None = None,
        transport: httpx.AsyncBaseTransport | None = None,
        timeout: float = 15.0,
    ) -> None:
        self.email = normalize_email(email)
        self._credential = credential
        self._transport = transport
        self._timeout = timeout

    def _client(self) -> httpx.AsyncClient:
        return httpx.AsyncClient(timeout=self._timeout, transport=self._transport)

    def _cred(self) -> GmailCredential:
        cred = self._credential or load_credential(self.email)
        if cred is None:
            raise GmailNotConfigured(self.email)
        return cred

    async def _access_token(self, client: httpx.AsyncClient) -> str:
        cred = self._cred()
        key = _token_key(cred)
        cached = _TOKENS.get(key)
        if cached is not None and cached[1] - _TOKEN_SLACK_SECONDS > time.time():
            return cached[0]
        try:
            resp = await client.post(
                cred.token_uri,
                data={
                    "grant_type": "refresh_token",
                    "refresh_token": cred.refresh_token,
                    "client_id": cred.client_id,
                    "client_secret": cred.client_secret,
                },
            )
        except httpx.HTTPError as exc:
            raise GmailError(f"token refresh failed: {type(exc).__name__}") from exc
        if resp.status_code in (400, 401):
            try:
                code = str(resp.json().get("error") or "")
            except ValueError:
                code = ""
            if code in ("invalid_grant", "unauthorized_client", "invalid_client") or resp.status_code == 401:
                raise GmailAuthError(code or "unauthorized")
        if resp.status_code >= 400:
            raise GmailError(f"token refresh returned {resp.status_code}")
        try:
            payload = resp.json()
            token = str(payload["access_token"])
            ttl = int(payload.get("expires_in", 3600))
        except (ValueError, KeyError, TypeError) as exc:
            raise GmailError("token refresh returned an unexpected response") from exc
        granted = str(payload.get("scope") or "")
        if granted and not set(SCOPES) <= set(granted.split()):
            raise GmailAuthError("missing_scope")
        _TOKENS[key] = (token, time.time() + ttl)
        _GRANTED[key] = granted
        return token

    async def _get(
        self, client: httpx.AsyncClient, path: str, params: Any = None
    ) -> dict[str, Any]:
        return await self._request(client, "GET", path, params=params)

    async def _request(
        self,
        client: httpx.AsyncClient,
        method: str,
        path: str,
        *,
        params: Any = None,
        json_body: dict[str, Any] | None = None,
        base: str = GMAIL_BASE,
        if_match: str | None = None,
    ) -> dict[str, Any]:
        token = await self._access_token(client)
        headers = {"Authorization": f"Bearer {token}"}
        if if_match:
            headers["If-Match"] = if_match
        try:
            resp = await client.request(
                method,
                f"{base}{path}",
                params=params,
                json=json_body,
                headers=headers,
            )
        except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
            # Never reached Google: nothing was done.
            raise GmailError(f"gmail {method} failed: {type(exc).__name__}") from exc
        except httpx.HTTPError as exc:
            raise GmailError(f"gmail {method} failed: {type(exc).__name__}", maybe_done=True) from exc
        if resp.status_code == 401:
            _TOKENS.pop(_token_key(self._cred()), None)
            raise GmailAuthError("unauthorized")
        if resp.status_code == 403 and not _rate_limited(resp):
            raise GmailAuthError("forbidden")
        if resp.status_code in (403, 429):
            raise GmailRateLimited(f"gmail {method} returned {resp.status_code}")
        if resp.status_code == 404:
            raise GmailNotFound(f"gmail {method} returned 404")
        if resp.status_code == 412:
            raise GmailChanged(f"gmail {method} returned 412")
        if resp.status_code >= 500:
            raise GmailError(f"gmail {method} returned {resp.status_code}", maybe_done=True)
        if resp.status_code >= 400:
            raise GmailError(f"gmail {method} returned {resp.status_code}")
        if not resp.content:
            return {}  # a DELETE answers 204 with no body
        try:
            data = resp.json()
        except ValueError as exc:
            raise GmailError("gmail returned a non-JSON response", maybe_done=True) from exc
        return data if isinstance(data, dict) else {}

    async def profile_email(self) -> str:
        """The address the credential opens, as Google reports it."""
        async with self._client() as client:
            data = await self._get(client, "/profile")
        return normalize_email(str(data.get("emailAddress") or ""))

    async def search_threads(self, query: str, *, max_results: int = 5) -> list[ThreadSummary]:
        """Threads matching a Gmail search, newest first: subject, sender and
        date only (no body text)."""
        from openexecutive.integrations.fact_confirmation import headers_authenticated

        async with self._client() as client:
            data = await self._get(
                client, "/threads", {"q": query[:300], "maxResults": max(1, min(max_results, 10))}
            )
            ids = [str(t.get("id")) for t in data.get("threads") or [] if valid_id(t.get("id"))]
            summaries: list[ThreadSummary] = []
            for thread_id in ids:
                meta = await self._get(
                    client,
                    f"/threads/{thread_id}",
                    [("format", "metadata"),
                     *(("metadataHeaders", name) for name in _SUMMARY_HEADERS)],
                )
                messages = [m for m in meta.get("messages") or [] if isinstance(m, dict)]
                payload = (messages[-1].get("payload") or {}) if messages else {}
                headers = _headers(payload)
                sender = getaddresses([headers.get("from", "")])
                from_addr = sender[0][1] if sender else ""
                summaries.append(ThreadSummary(
                    id=thread_id,
                    subject=_hide_tokens(headers.get("subject", "")),
                    sender=headers.get("from", ""),
                    date=headers.get("date", ""),
                    sender_authenticated=headers_authenticated(
                        _header_message(payload), normalize_email(from_addr)
                    ),
                ))
        return summaries

    async def get_thread(self, thread_id: str) -> MailThread:
        if not valid_id(thread_id):
            raise GmailError("invalid thread id")
        async with self._client() as client:
            data = await self._get(client, f"/threads/{thread_id}", {"format": "full"})
        messages = [parse_message(m) for m in data.get("messages") or [] if isinstance(m, dict)]
        return MailThread(id=thread_id, messages=messages)

    async def list_sent(self, limit: int = 40) -> list[MailMessage]:
        """The person's recent sent mail, newest first (at most ``limit``)."""
        async with self._client() as client:
            data = await self._get(
                client,
                "/messages",
                {"q": "in:sent -in:chats newer_than:1y", "maxResults": max(1, min(limit, 100))},
            )
            ids = [str(m.get("id")) for m in data.get("messages") or [] if valid_id(m.get("id"))]
            gate = asyncio.Semaphore(_FETCH_CONCURRENCY)

            async def fetch(message_id: str) -> MailMessage | GmailAuthError | None:
                # Returns the auth error rather than raising it, so every
                # fetch finishes before the client closes.
                async with gate:
                    try:
                        raw = await self._get(client, f"/messages/{message_id}", {"format": "full"})
                    except GmailAuthError as exc:
                        return exc
                    except GmailError:
                        logger.warning("delegation.gmail: skipped an unreadable sent message")
                        return None
                return parse_message(raw)

            fetched = await asyncio.gather(*(fetch(i) for i in ids))
        refused = next((f for f in fetched if isinstance(f, GmailAuthError)), None)
        if refused is not None:
            raise refused
        return [m for m in fetched if isinstance(m, MailMessage)]

    async def send_as_signature(self) -> str:
        """The signature on the person's primary Gmail address, as plain text."""
        async with self._client() as client:
            data = await self._get(client, "/settings/sendAs")
        entries = [e for e in data.get("sendAs") or [] if isinstance(e, dict)]
        primary = next((e for e in entries if e.get("isPrimary")), None) or next(
            (e for e in entries if normalize_email(str(e.get("sendAsEmail") or "")) == self.email),
            None,
        )
        return html_to_text(str((primary or {}).get("signature") or ""))

    async def list_message_ids(self, query: str, *, max_results: int = 25) -> list[tuple[str, str]]:
        """``(message id, thread id)`` for mail matching a Gmail search,
        newest first (at most ``max_results``, capped at 100)."""
        async with self._client() as client:
            data = await self._get(
                client, "/messages", {"q": query[:500], "maxResults": max(1, min(max_results, 100))}
            )
        return [
            (str(m["id"]), str(m.get("threadId") or ""))
            for m in data.get("messages") or []
            if isinstance(m, dict) and valid_id(m.get("id"))
        ]

    async def inbox_message_ids(self, *, after: datetime, max_results: int = 25) -> list[tuple[str, str]]:
        """``(message id, thread id)`` for mail that reached the Primary inbox
        since ``after``, newest first, leaving out the person's own."""
        query = (
            "in:inbox -in:chats -from:me -category:promotions -category:social "
            f"-category:updates -category:forums after:{int(after.timestamp())}"
        )
        return await self.list_message_ids(query, max_results=max_results)

    async def has_written_to(self, address: str) -> bool:
        """Whether the person's sent mail holds mail to ``address``."""
        target = normalize_email(address)
        if not _EMAIL_RE.fullmatch(target):
            return False
        return bool(await self.list_message_ids(f"in:sent to:{target}", max_results=1))

    async def latest_from(self, address: str, *, days: int = 90) -> MailMessage | None:
        """The newest mail ``address`` sent the person in the last ``days``,
        or None."""
        target = normalize_email(address)
        if not _EMAIL_RE.fullmatch(target):
            return None
        found = await self.list_message_ids(f"from:{target} -in:chats newer_than:{int(days)}d", max_results=1)
        return await self.get_message(found[0][0]) if found else None

    async def recent_from(self, address: str, *, days: int = 90, limit: int = 5) -> list[MailMessage]:
        """The newest ``limit`` mails ``address`` sent the person in the last
        ``days``, newest first."""
        target = normalize_email(address)
        if not _EMAIL_RE.fullmatch(target):
            return []
        found = await self.list_message_ids(
            f"from:{target} -in:chats newer_than:{int(days)}d", max_results=max(1, min(int(limit), 25)),
        )
        messages: list[MailMessage] = []
        for message_id, _thread in found:
            try:
                messages.append(await self.get_message(message_id))
            except GmailNotFound:
                continue  # deleted since it was listed
        return messages

    async def get_message(self, message_id: str) -> MailMessage:
        if not valid_id(message_id):
            raise GmailError("invalid message id")
        async with self._client() as client:
            data = await self._get(client, f"/messages/{message_id}", {"format": "full"})
        return parse_message(data)

    async def list_attachments(self, message_id: str) -> list[MailAttachment]:
        return (await self.get_message(message_id)).attachments

    async def _with_forwarded_files(self, spec: DraftSpec) -> tuple[DraftSpec, int]:
        """``spec`` with its forwarded message's files attached, and how
        many were left off for the caps."""
        assert spec.forward is not None
        files: list[tuple[str, str, bytes]] = []
        total = skipped = 0
        for meta in await self.list_attachments(spec.forward.message_id):
            if len(files) >= FORWARD_MAX_FILES or total + meta.size > FORWARD_MAX_BYTES:
                skipped += 1
                continue
            meta, data = await self.attachment_bytes(spec.forward.message_id, meta.index)
            if total + len(data) > FORWARD_MAX_BYTES:
                skipped += 1
                continue
            total += len(data)
            files.append((meta.name, meta.mime_type, data))
        return replace(spec, attachments=files), skipped

    async def attachment_bytes(self, message_id: str, index: int) -> tuple[MailAttachment, bytes]:
        """The ``index``-th attached file of the message (1-based) and its
        bytes, read with the attachment id Gmail gives on this fetch."""
        if not valid_id(message_id):
            raise GmailError("invalid message id")
        async with self._client() as client:
            raw = await self._get(client, f"/messages/{message_id}", {"format": "full"})
            raw_payload = raw.get("payload")
            payload: dict[str, Any] = raw_payload if isinstance(raw_payload, dict) else {}
            parts = _attachment_parts(payload)
            if not 1 <= index <= len(parts):
                raise GmailNotFound("no such attachment")
            meta = _attachments(payload)[index - 1]
            body = parts[index - 1].get("body") or {}
            attachment_id = body.get("attachmentId")
            if isinstance(attachment_id, str) and attachment_id:
                if not _ATTACHMENT_ID_RE.fullmatch(attachment_id):
                    raise GmailError("gmail returned an unusable attachment id")
                body = await self._get(client, f"/messages/{message_id}/attachments/{attachment_id}")
        data = body.get("data")
        if not isinstance(data, str):
            raise GmailError("gmail returned no attachment data")
        try:
            return meta, _b64decode(data)
        except (ValueError, TypeError) as exc:
            raise GmailError("gmail returned unreadable attachment data") from exc

    async def send_as_addresses(self) -> list[str]:
        """Every address the person can send as (their primary and aliases)."""
        async with self._client() as client:
            data = await self._get(client, "/settings/sendAs")
        entries = [e for e in data.get("sendAs") or [] if isinstance(e, dict)]
        return [a for a in (normalize_email(str(e.get("sendAsEmail") or "")) for e in entries) if a]

    async def get_draft(self, draft_id: str) -> DraftInfo | None:
        """The draft as it is now, or None when it is gone (sent or deleted)."""
        if not valid_id(draft_id):
            raise GmailError("invalid draft id")
        async with self._client() as client:
            try:
                data = await self._get(client, f"/drafts/{draft_id}", {"format": "full"})
            except GmailNotFound:
                return None
        raw_message = data.get("message")
        message = parse_message(raw_message if isinstance(raw_message, dict) else {})
        return DraftInfo(draft_id=str(data.get("id") or draft_id), message=message)

    async def delete_draft(self, draft_id: str) -> bool:
        """Delete a draft (never a sent message). False when it was already gone."""
        if not valid_id(draft_id):
            raise GmailError("invalid draft id")
        async with self._client() as client:
            try:
                await self._request(client, "DELETE", f"/drafts/{draft_id}")
            except GmailNotFound:
                return False
        return True

    async def update_draft_text(
        self, draft_id: str, expected_version: str, text: str, *,
        to: list[str] | None = None, cc: list[str] | None = None,
    ) -> str:
        """Replace the words of the draft ``draft_id`` with ``text``, keeping
        every header (who it goes to, the subject, the thread), when it is
        still the version ``expected_version``. With ``to`` it goes to ``to``
        and ``cc`` instead. Returns its new version (the
        message id Gmail gives the edited draft). Raises ``GmailNotFound``
        when it is gone and ``DraftChanged`` when it changed meanwhile or is
        more than plain text. Nothing is sent."""
        if not valid_id(draft_id):
            raise GmailError("invalid draft id")
        async with self._client() as client:
            data = await self._get(client, f"/drafts/{draft_id}", {"format": "raw"})
            current = data.get("message")
            current = current if isinstance(current, dict) else {}
            if str(current.get("id") or "") != expected_version:
                raise DraftChanged("changed")
            raw = current.get("raw")
            if not isinstance(raw, str):
                raise GmailError("gmail returned no draft")
            try:
                from email import message_from_bytes, policy

                msg = message_from_bytes(_b64decode(raw), policy=policy.default)
            except (ValueError, TypeError) as exc:
                raise GmailError("gmail returned an unreadable draft") from exc
            if not isinstance(msg, EmailMessage) or msg.is_multipart() or msg.get_content_type() != "text/plain":
                raise DraftChanged("not_plain")
            msg.set_content(text)
            if to is not None:
                del msg["To"]
                del msg["Cc"]
                msg["To"] = ", ".join(clean_header(a) for a in to)
                if cc:
                    msg["Cc"] = ", ".join(clean_header(a) for a in cc)
            message: dict[str, Any] = {"raw": base64.urlsafe_b64encode(msg.as_bytes()).decode("ascii")}
            thread_id = current.get("threadId")
            if isinstance(thread_id, str) and valid_id(thread_id):
                message["threadId"] = thread_id
            updated = await self._request(
                client, "PUT", f"/drafts/{draft_id}", json_body={"id": draft_id, "message": message},
            )
        saved = updated.get("message")
        version = str(saved.get("id") or "") if isinstance(saved, dict) else ""
        if not version:
            raise GmailError("gmail returned no edited draft", maybe_done=True)
        return version

    async def send_draft(self, draft_id: str) -> SentMessage:
        """Send the draft ``draft_id`` exactly as it is in Gmail now: the
        request body is its id and nothing else, so nothing here can change
        what goes, or to whom. Gmail deletes a draft it sends. Only
        ``delegation.reply_send`` calls this (a unit test holds it to that).
        A ``GmailError`` whose ``maybe_done`` is set may have sent it."""
        if not valid_id(draft_id):
            raise GmailError("invalid draft id")
        async with self._client() as client:
            data = await self._request(client, "POST", "/drafts/send", json_body={"id": draft_id})
        return SentMessage(id=str(data.get("id") or ""), thread_id=str(data.get("threadId") or ""))

    async def create_draft(self, spec: DraftSpec) -> CreatedDraft:
        """Save ``spec`` as a draft in the person's Gmail. Nothing is sent.
        A forward attaches the forwarded message's files, as many as fit
        ``FORWARD_MAX_FILES`` and ``FORWARD_MAX_BYTES``."""
        if spec.thread_id is not None and not valid_id(spec.thread_id):
            raise GmailError("invalid thread id")
        skipped = 0
        if spec.forward is not None and not spec.attachments:
            spec, skipped = await self._with_forwarded_files(spec)
        message: dict[str, Any] = {"raw": build_raw(self.email, spec)}
        if spec.thread_id:
            message["threadId"] = spec.thread_id
        async with self._client() as client:
            data = await self._request(client, "POST", "/drafts", json_body={"message": message})
        raw_created = data.get("message")
        created: dict[str, Any] = raw_created if isinstance(raw_created, dict) else {}
        return CreatedDraft(
            draft_id=str(data.get("id") or ""),
            message_id=str(created.get("id") or ""),
            thread_id=str(created.get("threadId") or spec.thread_id or ""),
            skipped_attachments=skipped,
        )


    async def _granted_scopes(self, client: httpx.AsyncClient) -> str:
        await self._access_token(client)
        return _GRANTED.get(_token_key(self._cred()), "")

    async def calendar_granted(self) -> bool | None:
        """Whether their saved sign-in reads their calendar
        (``calendar.readonly`` or ``calendar.events``); None when Google
        didn't say which scopes it carries."""
        async with self._client() as client:
            granted = await self._granted_scopes(client)
        return bool(CALENDAR_READ_SCOPES & set(granted.split())) if granted else None

    async def calendar_write_granted(self) -> bool | None:
        """Whether their saved sign-in can answer a meeting invite
        (``calendar.events``); None when Google didn't say."""
        async with self._client() as client:
            granted = await self._granted_scopes(client)
        return bool(CALENDAR_WRITE_SCOPES & set(granted.split())) if granted else None

    async def list_events(self, start: datetime, end: datetime, *, max_results: int = MAX_EVENTS) -> list[CalendarEvent]:
        """The events on their primary calendar between ``start`` and ``end``,
        recurring ones expanded, in order. A read (``calendar.readonly`` or
        ``calendar.events``)."""
        async with self._client() as client:
            granted = await self._granted_scopes(client)
            if granted and not CALENDAR_READ_SCOPES & set(granted.split()):
                raise CalendarNotGranted("calendar.readonly not granted")
            params = {
                "timeMin": start.astimezone(UTC).isoformat().replace("+00:00", "Z"),
                "timeMax": end.astimezone(UTC).isoformat().replace("+00:00", "Z"),
                "singleEvents": "true",
                "orderBy": "startTime",
                "maxResults": str(max(1, min(max_results, MAX_EVENTS))),
            }
            try:
                data = await self._request(client, "GET", "/events", params=params, base=CALENDAR_BASE)
            except GmailAuthError as exc:
                if str(exc) != "forbidden":
                    raise
                # With the scope granted, a refusal is the project's (the API
                # not enabled, a quota), and reconnecting wouldn't fix it.
                if CALENDAR_READ_SCOPES & set(granted.split()):
                    raise GmailError("calendar read refused with the scope granted") from exc
                raise CalendarNotGranted("calendar read refused") from exc
        items_raw = data.get("items")
        items: list[Any] = items_raw if isinstance(items_raw, list) else []
        events = [parse_google_event(item) for item in items if isinstance(item, dict)]
        return [e for e in events if e is not None]

    async def _invite_uid(self, message: MailMessage) -> tuple[str, str]:
        """The invite's method and UID: from its inline part, else from its
        attached .ics file."""
        if message.invite_uid:
            return message.invite_method, message.invite_uid
        for attachment in message.attachments:
            if attachment.mime_type in _CALENDAR_TYPES or attachment.name.lower().endswith(".ics"):
                _meta, data = await self.attachment_bytes(message.id, attachment.index)
                found = ics_invite(data[:200_000].decode("utf-8", errors="replace"))
                if found[1]:
                    return found
        return "", ""

    async def find_invite(self, message: MailMessage) -> CalendarEvent | None:
        """The event a meeting invite ``message`` asks them to, as it is on
        their own primary calendar (found by its iCalendar UID), or None:
        not a request (a cancellation, someone's answer), or not on their
        calendar. A read."""
        method, uid = await self._invite_uid(message)
        if not uid or method not in ("", "REQUEST"):
            return None
        async with self._client() as client:
            granted = await self._granted_scopes(client)
            if granted and not CALENDAR_READ_SCOPES & set(granted.split()):
                raise CalendarNotGranted("calendar.readonly not granted")
            try:
                data = await self._request(
                    client, "GET", "/events", params={"iCalUID": uid, "maxResults": "5"}, base=CALENDAR_BASE,
                )
            except GmailAuthError as exc:
                if str(exc) != "forbidden":
                    raise
                if CALENDAR_READ_SCOPES & set(granted.split()):
                    raise GmailError("calendar read refused with the scope granted") from exc
                raise CalendarNotGranted("calendar read refused") from exc
        items_raw = data.get("items")
        items: list[Any] = items_raw if isinstance(items_raw, list) else []
        for item in items:
            if isinstance(item, dict) and _EVENT_ID_RE.fullmatch(str(item.get("id") or "")):
                event = parse_google_event(item)
                if event is not None:
                    return event
        return None

    async def answer_invite(self, event_id: str, *, accept: bool) -> None:
        """Answer the invite to ``event_id`` on their primary calendar, as
        them: their own attendee entry's answer becomes accepted or declined,
        and Google tells the organizer (``sendUpdates=all``). Nothing else on
        the event changes: the write carries the event's ``etag``, so a change
        made since it was read (a guest added, another answer) is read again
        rather than overwritten, once. Called only by ``delegation.invites``,
        on the person's tap or under Handle it for me (accept only).
        Answering twice is the same as once. Raises ``CalendarWriteNotGranted`` for a
        read-only sign-in, ``GmailNotFound`` when the event or their place on
        it is gone."""
        if not _EVENT_ID_RE.fullmatch(event_id or ""):
            raise GmailError("invalid event id")
        async with self._client() as client:
            granted = await self._granted_scopes(client)
            if granted and not CALENDAR_WRITE_SCOPES & set(granted.split()):
                raise CalendarWriteNotGranted("calendar.events not granted")
            path = f"/events/{event_id}"
            try:
                for attempt in range(2):
                    event = await self._request(client, "GET", path, base=CALENDAR_BASE)
                    attendees = [dict(a) for a in event.get("attendees") or [] if isinstance(a, dict)]
                    mine = next((a for a in attendees if a.get("self") is True), None)
                    if mine is None:
                        mine = next(
                            (a for a in attendees if normalize_email(str(a.get("email") or "")) == self.email),
                            None,
                        )
                    if mine is None:
                        raise GmailNotFound("not an attendee")
                    mine["responseStatus"] = "accepted" if accept else "declined"
                    try:
                        await self._request(
                            client, "PATCH", path, params={"sendUpdates": "all"},
                            json_body={"attendees": attendees}, base=CALENDAR_BASE,
                            if_match=str(event.get("etag") or "") or None,
                        )
                        return
                    except GmailChanged:
                        if attempt:
                            raise
            except GmailAuthError as exc:
                if str(exc) != "forbidden":
                    raise
                if CALENDAR_WRITE_SCOPES & set(granted.split()):
                    raise GmailError("calendar write refused with the scope granted") from exc
                raise CalendarWriteNotGranted("calendar write refused") from exc


def gmail_for(email: str) -> Any:
    """The client for ``email``'s own mailbox: ``DelegateGmail``, or
    ``outlook.DelegateOutlook`` when their credential file is a Microsoft one.
    Both have the same methods, return types and errors."""
    if credential_provider(email) == "microsoft":
        from openexecutive.delegation.outlook import DelegateOutlook

        return DelegateOutlook(email)
    return DelegateGmail(email)


async def gmail_status(person_email: str | None, *, gmail: Any = None) -> GmailStatus:
    """Whether ``person_email``'s own mailbox can be used right now. Asks
    the mail service which mailbox the credential opens. Never raises."""
    from openexecutive.config import get_settings

    address = normalize_email(person_email)
    if not address:
        return "no_email"
    try:
        exec_address = normalize_email(get_settings().exec_email_address)
    except Exception:
        logger.warning("delegation.gmail: settings unreadable — refusing", exc_info=True)
        return "error"
    if address == exec_address:
        return "shared_mailbox"
    client = gmail if gmail is not None else gmail_for(address)
    try:
        opened = await client.profile_email()
    except GmailNotConfigured:
        return "not_configured"
    except GmailAuthError:
        return "needs_reconnect"
    except Exception:
        logger.warning("delegation.gmail: status check failed", exc_info=True)
        return "error"
    return "connected" if opened == address else "mismatch"