esbi-cli 0.2.1__py3-none-any.whl

esbi_cli/llm/schemas.py

@@ -0,0 +1,146 @@
+"""The edit plan: the only thing the LLM produces. The worker validates and applies it."""
+
+from typing import Annotated
+
+from annotated_types import MaxLen
+from pydantic import BaseModel, BeforeValidator, Field, field_validator
+
+
+def _clamp(max_items: int):
+    def clamp(value):
+        return value[:max_items] if isinstance(value, list) else value
+
+    return BeforeValidator(clamp)
+
+
+class ConceptEdit(BaseModel):
+    """A concept or entity this source touches."""
+
+    title: str = Field(
+        min_length=2, max_length=60, description="Canonical name, short (at most 6 words)"
+    )
+    aliases: list[str] = Field(default_factory=list, description="Other names or acronyms")
+    description: str = Field(
+        min_length=10,
+        description="1-3 sentences on what this source adds to this concept or entity",
+    )
+
+
+class Term(BaseModel):
+    """A technical term used in the source, with what it means."""
+
+    term: str = Field(
+        min_length=2, max_length=60, description="Exactly as it appears in the source"
+    )
+    definition: str = Field(min_length=10, description="Definition in one sentence")
+
+
+class Relation(BaseModel):
+    """A link between two ideas, drawn later as an edge of the concept map."""
+
+    a: str = Field(min_length=2, max_length=50, description="Name of a concept or term, 1-4 words")
+    relation: str = Field(
+        min_length=2, max_length=40, description="A short label for how the two relate"
+    )
+    b: str = Field(min_length=2, max_length=50, description="Name of a concept or term, 1-4 words")
+
+
+class ChunkNotes(BaseModel):
+    """What one reads out of one chunk of a long source."""
+
+    points: Annotated[list[str], _clamp(8), MaxLen(8)] = Field(
+        min_length=1,
+        description="3-8 concrete statements: facts, methods, results, arguments",
+    )
+    terms: Annotated[list[Term], _clamp(6), MaxLen(6)] = Field(default_factory=list)
+    quotes: Annotated[list[str], _clamp(3), MaxLen(3)] = Field(
+        default_factory=list, description="Sentences copied EXACTLY from the chunk"
+    )
+    relations: Annotated[list[Relation], _clamp(6), MaxLen(6)] = Field(default_factory=list)
+
+
+class Insight(BaseModel):
+    idea: str = Field(min_length=10, description="The idea, in one or two sentences")
+    why: str = Field(min_length=10, description="What follows from the idea, in one sentence")
+
+
+class Digest(BaseModel):
+    """The long-form part of a note, written from the chunk notes."""
+
+    # a list, not one string: a string has no bound a model's grammar can enforce, and a small model
+    # repeated paragraphs in it until the token cap in 5 of 20 calls (0 of 10 as a list of at most 5)
+    paragraphs: Annotated[list[str], _clamp(4), MaxLen(4)] = Field(
+        min_length=3,
+        description="Detailed summary: the problem, the approach, the findings, the implications",
+    )
+    insights: Annotated[list[Insight], _clamp(6), MaxLen(6)] = Field(min_length=1)
+    open_questions: Annotated[list[str], _clamp(5), MaxLen(5)] = Field(default_factory=list)
+
+    @field_validator("paragraphs")
+    @classmethod
+    def _enough_to_read(cls, value: list[str]) -> list[str]:
+        if sum(len(p.strip()) for p in value) < 200:
+            raise ValueError("the detailed summary is too short: write real paragraphs")
+        return value
+
+    @property
+    def abstract(self) -> str:
+        return "\n\n".join(p.strip() for p in self.paragraphs)
+
+
+class Connection(BaseModel):
+    """How a new source relates to a page already in the wiki."""
+
+    page: str = Field(description="EXACT title of an existing page")
+    relation: str = Field(
+        min_length=2, max_length=40, description="A short label for how the two relate"
+    )
+    why: str = Field(min_length=10, description="One sentence: why they are related")
+
+
+class ConnectionPlan(BaseModel):
+    connections: Annotated[list[Connection], _clamp(8), MaxLen(8)] = Field(default_factory=list)
+
+
+class Contradiction(BaseModel):
+    page: str = Field(description="EXACT title of the existing page that is contradicted")
+    note: str = Field(min_length=5, description="What is contradicted, in one sentence")
+
+
+class EditPlan(BaseModel):
+    title: str = Field(min_length=3, description="Title of the source")
+    one_liner: str = Field(min_length=10, description="One-sentence summary for the index")
+    summary: str = Field(
+        min_length=30, description="Executive summary: 2-3 sentences, what it is and why it matters"
+    )
+    abstract: str = Field(
+        default="",
+        description="Detailed summary, 3-5 paragraphs: problem, approach, findings, implications",
+    )
+    insights: Annotated[list[Insight], _clamp(8), MaxLen(8)] = Field(default_factory=list)
+    terms: Annotated[list[Term], _clamp(10), MaxLen(10)] = Field(default_factory=list)
+    quotes: Annotated[list[str], _clamp(6), MaxLen(6)] = Field(
+        default_factory=list, description="Sentences copied EXACTLY from the source"
+    )
+    relations: Annotated[list[Relation], _clamp(10), MaxLen(10)] = Field(default_factory=list)
+    open_questions: Annotated[list[str], _clamp(5), MaxLen(5)] = Field(default_factory=list)
+    key_points: Annotated[list[str], _clamp(8), MaxLen(8)] = Field(description="3-8 key points")
+    tags: Annotated[list[str], _clamp(6), MaxLen(6)] = Field(default_factory=list)
+    concepts: Annotated[list[ConceptEdit], _clamp(6), MaxLen(6)] = Field(
+        min_length=1, description="2-6 central concepts or techniques (never empty)"
+    )
+    entities: Annotated[list[ConceptEdit], _clamp(5), MaxLen(5)] = Field(default_factory=list)
+    related_pages: Annotated[list[str], _clamp(6), MaxLen(6)] = Field(
+        default_factory=list,
+        description="EXACT titles of related existing pages (only from the given list)",
+    )
+    contradictions: Annotated[list[Contradiction], _clamp(4), MaxLen(4)] = Field(
+        default_factory=list
+    )
+
+    @field_validator("one_liner")
+    @classmethod
+    def _one_liner_is_a_sentence(cls, value: str) -> str:
+        if value.strip().lower().startswith(("http://", "https://")) or " " not in value.strip():
+            raise ValueError("must be a descriptive sentence, not a URL")
+        return value

esbi_cli/mail/convert.py

@@ -0,0 +1,194 @@
+"""Turn a raw email (RFC 5322 bytes) into a Web Clipper-style note for the vault's inbox."""
+
+import email
+import hashlib
+import io
+import re
+from dataclasses import dataclass, field
+from datetime import date
+from email import policy
+from email.message import EmailMessage
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from urllib.parse import urlparse
+
+import lxml.html
+import trafilatura
+from PIL import Image
+
+from esbi_cli import lang
+from esbi_cli.vault import Page, safe_title
+
+
+@dataclass
+class ClipNote:
+    filename: str
+    content: str  # empty when the mail is only attachments
+    source: str  # stable id of the mail (`mail:<message-id>`), used to spot duplicates
+    pdfs: list[tuple[str, bytes]] = field(default_factory=list)  # (file name, bytes) attached
+    images: list[tuple[str, bytes]] = field(default_factory=list)  # (safe file name, bytes) kept
+    links: list[str] = field(default_factory=list)  # http(s) links worth following, in order
+
+
+# Newsletters pad the preview text with these (zero-width and joiner characters, soft hyphens)
+INVISIBLE = re.compile("[\u034f\u200b-\u200f\u2060\u00ad\ufeff]")
+
+
+def _clean(text: str) -> str:
+    """Drop the invisible padding, then the blank lines it leaves behind."""
+    text = INVISIBLE.sub("", text)
+    text = "\n".join(line.rstrip() for line in text.splitlines())
+    return re.sub(r"\n{3,}", "\n\n", text).strip()
+
+
+def _html_to_text(html: str) -> str:
+    """Article extraction when the email looks like one, else the page's visible text."""
+    extracted = trafilatura.extract(html, output_format="markdown", favor_recall=True)
+    if extracted and len(extracted.strip()) > 40:
+        return extracted.strip()
+    tree = lxml.html.fromstring(html)
+    for junk in tree.xpath("//script | //style | //head"):
+        junk.drop_tree()
+    return re.sub(r"\n{3,}", "\n\n", tree.text_content()).strip()
+
+
+MIN_PLAIN_CHARS = 100  # shorter plain parts are usually a "view in browser" stub
+
+
+def _body(msg: EmailMessage) -> str:
+    plain = msg.get_body(preferencelist=("plain",))
+    html = msg.get_body(preferencelist=("html",))
+    plain_text = plain.get_content().strip() if plain else ""
+    if plain_text and (len(plain_text) >= MIN_PLAIN_CHARS or html is None):
+        return plain_text
+    return _html_to_text(html.get_content()) if html else plain_text
+
+
+# Image attachments: what the bytes are decides, never the declared type or the file name.
+IMAGE_FORMATS = {  # declared content type -> (format Pillow must find in the bytes, extension)
+    "image/png": ("PNG", ".png"),
+    "image/jpeg": ("JPEG", ".jpg"),
+    "image/webp": ("WEBP", ".webp"),
+    "image/tiff": ("TIFF", ".tiff"),
+}
+MIN_IMAGE_SIDE_PX = 200  # signature logos, icons and tracking pixels are smaller
+MIN_IMAGE_BYTES = 5_000  # ...or flat: a screenshot or a photo is never this light
+MAX_IMAGE_BYTES = 5_000_000
+MAX_MAIL_IMAGE_BYTES = 15_000_000
+MAX_IMAGE_PIXELS = 50_000_000  # the decoder allocates width x height: refuse absurd sizes
+
+
+def _image_name(data: bytes, declared: str, filename: str | None) -> str | None:
+    """`<safe stem><extension>` for an image worth keeping, else None."""
+    if declared not in IMAGE_FORMATS or not MIN_IMAGE_BYTES <= len(data) <= MAX_IMAGE_BYTES:
+        return None
+    try:
+        with Image.open(io.BytesIO(data)) as img:
+            fmt, (width, height) = img.format, img.size
+    except Exception:  # Pillow raises several unrelated error types for bytes that are no image
+        return None
+    expected, suffix = IMAGE_FORMATS[declared]
+    if (
+        fmt != expected
+        or min(width, height) < MIN_IMAGE_SIDE_PX
+        or width * height > MAX_IMAGE_PIXELS
+    ):
+        return None
+    stem = Path((filename or "").replace("\\", "/")).stem  # never a path: only the last part
+    return f"{safe_title(stem, 40) or 'image'}{suffix}"
+
+
+def _images(msg: EmailMessage) -> list[tuple[str, bytes]]:
+    kept, total = [], 0
+    for part in msg.walk():
+        if part.is_multipart() or not part.get_content_type().startswith("image/"):
+            continue
+        data = part.get_content()
+        name = _image_name(data, part.get_content_type(), part.get_filename())
+        if name and total + len(data) <= MAX_MAIL_IMAGE_BYTES:
+            kept.append((name, data))
+            total += len(data)
+    return kept
+
+
+_URL = re.compile(r"https?://[^\s<>\"')\]]+")
+_NOT_AN_ARTICLE = re.compile(
+    r"unsubscri|opt-?out|preferences|view-?in-?browser|view_in_browser|web-?version|"
+    r"manage[-_]?subscription|confirm|verif|reset|log-?in|sign-?in|magic|activat|password|token=|"
+    r"\.(?:gif|png|jpe?g|svg|webp|css|js|ico)(?:\?|$)",
+    re.IGNORECASE,
+)
+_REDIRECT_HOSTS = (
+    "click",
+    "clicks",
+    "track",
+    "tracking",
+    "links",
+    "trk",
+    "email",
+    "em",
+)  # click.news.test
+MAX_LINK_CHARS = 500
+
+
+def _links(text: str) -> list[str]:
+    """http(s) links in the mail's text, in order and without repeats, minus tracking redirects,
+    unsubscribe/preferences/view-in-browser housekeeping and pictures. ponytail: only links that
+    show in the text; a link hidden behind anchor text in an HTML-only mail is not found."""
+    found: list[str] = []
+    for url in (u.rstrip(".,;:!?") for u in _URL.findall(text)):
+        host = urlparse(url).hostname or ""
+        if (
+            len(url) <= MAX_LINK_CHARS
+            and host
+            and not _NOT_AN_ARTICLE.search(url)
+            and not (host.count(".") >= 2 and host.partition(".")[0] in _REDIRECT_HOSTS)
+            and host != "list-manage.com"
+            and not host.endswith(".list-manage.com")
+            and url not in found
+        ):
+            found.append(url)
+    return found
+
+
+def _sent_date(msg: EmailMessage) -> date:
+    try:
+        return parsedate_to_datetime(str(msg["Date"])).date()
+    except (TypeError, ValueError):
+        return date.today()
+
+
+def email_to_clip(raw: bytes, language: str = lang.DEFAULT) -> ClipNote:
+    msg = email.message_from_bytes(raw, policy=policy.default)
+    subject = str(msg["Subject"] or lang.t(language, "no_subject")).strip()
+    body = _clean(_body(msg))
+    pdfs = [
+        (part.get_filename() or "attachment.pdf", part.get_content())
+        for part in msg.iter_attachments()
+        if part.get_content_type() == "application/pdf"
+    ]
+    images = _images(msg)
+    if not body and not pdfs and not images:
+        raise ValueError("the email has no readable text")
+    sent = _sent_date(msg).isoformat()
+    # an id is used as a source name and written into notes: letters, digits and . @ + = _ - only
+    message_id = (
+        re.sub(r"[^\w.@+=-]", "", str(msg["Message-ID"] or ""))[:150]
+        or hashlib.sha256(raw).hexdigest()[:16]
+    )
+    meta = {
+        "title": subject,
+        "source": f"mail:{message_id}",
+        "kind": "email",
+        "from": str(msg["From"] or ""),
+        "date": sent,
+    }
+    content = Page(Path("clip.md"), meta, body).render() if body else ""
+    return ClipNote(
+        filename=f"{sent} {safe_title(subject, 60)}.md",
+        content=content,
+        source=meta["source"],
+        pdfs=pdfs,
+        images=images,
+        links=_links(body),
+    )

esbi_cli/mail/credentials.py

@@ -0,0 +1,65 @@
+"""The IMAP app password lives in the macOS Keychain (via keyring), never in a file."""
+
+import threading
+
+import keyring
+from keyring.errors import KeyringError
+
+SERVICE = "esbi-cli-imap"
+OLD_SERVICE = "secondbrain-imap"  # legacy: the name before esbi-cli
+
+
+class CredentialError(RuntimeError):
+    pass
+
+
+def save_password(user: str, password: str, backend=None) -> None:
+    # Google shows app passwords in groups separated by spaces; the spaces are not part of it
+    try:
+        (backend or keyring).set_password(SERVICE, user, "".join(password.split()))
+    except KeyringError as exc:
+        hint = ""
+        if "-25244" in str(exc):  # the existing item was made by another program (a reinstall)
+            hint = (
+                " The old item belongs to another program; delete it and try again: "
+                f"security delete-generic-password -s {SERVICE} -a {user}"
+            )
+        raise CredentialError(f"Could not write to the Keychain: {exc}.{hint}") from exc
+
+
+def get_password(user: str, backend=None, timeout_seconds: float = 20) -> str:
+    # macOS can show "allow this program to use the item?" and block until someone clicks; an
+    # unattended run must not hang there holding the run lock, so the read has a time limit.
+    # A daemon thread, so a read still blocked at exit cannot keep the process alive.
+    outcome: dict = {}
+
+    def read() -> None:
+        try:
+            store = backend or keyring
+            outcome["password"] = store.get_password(SERVICE, user)
+            if not outcome["password"] and (old := store.get_password(OLD_SERVICE, user)):
+                store.set_password(SERVICE, user, old)  # move it to the new name
+                outcome["password"] = old
+        except BaseException as exc:  # handed to the caller below
+            outcome["error"] = exc
+
+    thread = threading.Thread(target=read, daemon=True)
+    thread.start()
+    thread.join(timeout_seconds)
+    if thread.is_alive():
+        raise CredentialError(
+            "The Keychain is waiting for permission: a dialog on the Mac asks whether `sb` may use "
+            "the item. Click Always Allow, or store the password again with `sb email set-password`."
+        )
+    if isinstance(outcome.get("error"), KeyringError):  # no backend (Linux/CI), locked or denied
+        raise CredentialError(f"Could not read the Keychain: {outcome['error']}") from outcome[
+            "error"
+        ]
+    if "error" in outcome:
+        raise outcome["error"]
+    password = outcome["password"]
+    if not password:
+        raise CredentialError(
+            f"No IMAP password in the Keychain for {user}. Store it with `sb email set-password`."
+        )
+    return password

esbi_cli/mail/fetch.py

@@ -0,0 +1,154 @@
+"""Pull unseen mail from the dedicated mailbox into the vault's inbox/ as clip notes."""
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from esbi_cli.mail.convert import email_to_clip
+from esbi_cli.queue import Queue, normalize_target
+from esbi_cli.vault import Vault, free_path, safe_title
+
+MAIL_LINK_ORIGIN = "mail-link"  # queue origin of a link found in a mail: its page is email
+
+
+class MailClient(Protocol):
+    def recent(self, days: int = 14) -> list[tuple[str, bytes]]:
+        """(uid, raw RFC 5322 message) for every message of the last `days`, seen or not."""
+        ...
+
+    def mark_seen(self, uid: str) -> None: ...
+
+    def close(self) -> None: ...
+
+
+@dataclass
+class FetchResult:
+    saved: int = 0
+    duplicates: int = 0
+    failed: int = 0
+    images: int = 0  # image attachments kept
+    links: int = 0  # links found in mail and queued
+
+
+def _known_sources(vault: Vault) -> set[str]:
+    """`mail:<id>` sources already saved: waiting in inbox/, moved to raw/inbox/, or ingested."""
+    known = set()
+    for folder in (vault.root / "inbox", vault.root / "raw" / "inbox"):
+        for path in folder.glob("*.md") if folder.is_dir() else ():
+            known.add(str(vault.read_page(path).meta.get("source")))
+    known |= {str(p.meta.get("url")) for p in vault.iter_pages(("sources",))}
+    return known
+
+
+def _kept_file(vault: Vault, data: bytes, suffix: str) -> bool:
+    """Is this very file already waiting in inbox/ or kept in raw/inbox/?"""
+    return any(
+        f.stat().st_size == len(data) and f.read_bytes() == data
+        for folder in (vault.root / "inbox", vault.root / "raw" / "inbox")
+        if folder.is_dir()
+        for f in folder.iterdir()
+        if f.suffix.lower() == suffix
+    )
+
+
+def _save(vault: Vault, inbox: Path, clip) -> int:
+    """Write the note and its attachments; returns how many images were new."""
+    if clip.content:
+        free_path(inbox, clip.filename).write_text(clip.content, encoding="utf-8")
+    stem, images = clip.filename.removesuffix(".md"), 0
+    for name, data in clip.pdfs:
+        _remember_mail_file(vault, data)
+        if not _kept_file(vault, data, ".pdf"):
+            free_path(inbox, f"{stem} - {safe_title(Path(name).stem, 40)}.pdf").write_bytes(data)
+    for name, data in clip.images:  # `name` is already safe: stem and extension from the bytes
+        _remember_mail_file(vault, data)
+        if not _kept_file(vault, data, Path(name).suffix):
+            free_path(inbox, f"{stem} - {name}").write_bytes(data)
+            images += 1
+    return images
+
+
+def _queue_links(vault: Vault, queue: Queue, links: list[str], max_links: int) -> int:
+    """Queue links not already known (queued, done or a source) as email-derived items. Never
+    fetches: the nightly run reads them, with its limits and the private model."""
+    queued = 0
+    for url in links:
+        if queued == max_links:
+            break
+        if not vault.find_source("url", normalize_target(url)) and queue.add(
+            url, origin=MAIL_LINK_ORIGIN
+        ):
+            queued += 1
+    return queued
+
+
+def fetch_mail(
+    client: MailClient,
+    vault: Vault,
+    queue: Queue | None = None,
+    follow_links: bool = False,
+    max_links: int = 3,
+) -> FetchResult:
+    """Save each recent mail as inbox/<date> <subject>.md (and its PDF and image attachments), mark
+    it seen. With `follow_links` and a queue, the links in a newly saved mail are queued.
+
+    Never deletes mail. Mail already captured is skipped by Message-ID, so the window can overlap
+    runs. A mail that cannot be converted is reported once: its id is remembered in
+    `.esbi/mail-failed.txt` and skipped from then on.
+    """
+    result = FetchResult()
+    inbox = vault.root / "inbox"
+    inbox.mkdir(exist_ok=True)
+    known = _known_sources(vault)
+    failed_file = vault.root / ".esbi" / "mail-failed.txt"
+    failed_before = set(failed_file.read_text().split()) if failed_file.exists() else set()
+    for uid, raw in client.recent():
+        key = hashlib.sha256(raw).hexdigest()[:16]  # the uid is not stable across mailboxes
+        if key in failed_before:
+            continue
+        try:
+            clip = email_to_clip(raw, vault.language)
+        except Exception:  # one unreadable mail must not block the rest
+            result.failed += 1
+            failed_file.parent.mkdir(exist_ok=True)
+            with failed_file.open("a") as fh:
+                fh.write(key + "\n")
+            continue
+        if clip.source in known:
+            result.duplicates += 1
+        else:
+            try:
+                result.images += _save(vault, inbox, clip)
+                if follow_links and queue is not None:
+                    result.links += _queue_links(vault, queue, clip.links, max_links)
+            except OSError:  # a name the disk refuses: report it once, not on every run
+                result.failed += 1
+                failed_file.parent.mkdir(exist_ok=True)
+                with failed_file.open("a") as fh:
+                    fh.write(key + "\n")
+                continue
+            known.add(clip.source)
+            result.saved += 1
+        client.mark_seen(uid)
+    return result
+
+
+def _hashes_path(vault: Vault) -> Path:
+    return vault.root / ".esbi" / "mail-pdfs.txt"
+
+
+def _remember_mail_file(vault: Vault, data: bytes) -> None:
+    """A PDF or image saved from a mail is email: its hash is kept so the privacy rules still know
+    that once it sits in inbox/ as a plain file."""
+    path, digest = _hashes_path(vault), hashlib.sha256(data).hexdigest()
+    path.parent.mkdir(exist_ok=True)
+    known = set(path.read_text().split()) if path.exists() else set()
+    if digest not in known:
+        with path.open("a") as fh:
+            fh.write(digest + "\n")
+
+
+def is_mail_file(vault: Vault, data: bytes) -> bool:
+    path = _hashes_path(vault)
+    return path.exists() and hashlib.sha256(data).hexdigest() in path.read_text().split()

esbi_cli/mail/imap.py

@@ -0,0 +1,92 @@
+"""IMAP access to the dedicated mailbox (a Gmail label works as a mailbox name)."""
+
+import imaplib
+import ssl
+from collections.abc import Callable
+from datetime import date, timedelta
+
+MONTHS = (
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+)  # IMAP wants English
+
+
+class MailError(RuntimeError):
+    pass
+
+
+def _verified_ssl(host: str) -> imaplib.IMAP4:
+    """imaplib's own default context does not check the certificate: the app password would go to
+    whoever answers. This one verifies the chain and the host name."""
+    return imaplib.IMAP4_SSL(host, ssl_context=ssl.create_default_context())
+
+
+class ImapMailClient:
+    def __init__(
+        self,
+        host: str,
+        user: str,
+        password: str,
+        mailbox: str,
+        factory: Callable[[str], imaplib.IMAP4] = _verified_ssl,
+    ):
+        self.host, self.user, self.mailbox = host, user, mailbox
+        self._password = password
+        self._factory = factory
+        self._imap: imaplib.IMAP4 | None = None
+
+    def _connect(self) -> imaplib.IMAP4:
+        if self._imap is None:
+            try:
+                imap = self._factory(self.host)
+                imap.login(self.user, self._password)
+                quoted = '"' + self.mailbox.replace("\\", "\\\\").replace('"', '\\"') + '"'
+                status, _ = imap.select(quoted, readonly=False)
+            except (imaplib.IMAP4.error, OSError) as exc:
+                raise MailError(
+                    f"IMAP login/select failed for {self.user}@{self.host}: {exc}"
+                ) from None
+            if status != "OK":
+                raise MailError(f"Mailbox {self.mailbox!r} not found on {self.host}")
+            self._imap = imap
+        return self._imap
+
+    def recent(self, days: int = 14, today: date | None = None) -> list[tuple[str, bytes]]:
+        """Every message of the last `days`, opened in Gmail or not: the worker dedupes by
+        Message-ID, so the window can overlap runs without saving a mail twice."""
+        imap = self._connect()
+        since = (today or date.today()) - timedelta(days=days)
+        try:
+            _, data = imap.uid(
+                "SEARCH", None, "SINCE", f"{since.day:02d}-{MONTHS[since.month - 1]}-{since.year}"
+            )
+            mails = []
+            for uid in data[0].decode().split():
+                # BODY.PEEK[] reads the message without setting \Seen: only the worker does that,
+                # after the note is safely written
+                _, parts = imap.uid("FETCH", uid, "(BODY.PEEK[])")
+                mails.append((uid, parts[0][1]))
+            return mails
+        except (imaplib.IMAP4.error, OSError) as exc:
+            raise MailError(f"Reading mail failed: {exc}") from None
+
+    def mark_seen(self, uid: str) -> None:
+        self._connect().uid("STORE", uid, "+FLAGS", "(\\Seen)")
+
+    def close(self) -> None:
+        if self._imap is not None:
+            try:
+                self._imap.logout()
+            except (imaplib.IMAP4.error, OSError):
+                pass
+            self._imap = None