arbiter-imap 0.9.0.dev1__py3-none-any.whl

agent_arbiter_imap/__init__.py

@@ -0,0 +1,638 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Callable, Protocol, cast
+
+from hydra.core.config_store import ConfigStore
+
+from agent_arbiter.services import (
+    CapabilityDescriptor,
+    OperationDescriptor,
+    ServicePluginContext,
+    ServiceRuntimeContext,
+)
+from agent_arbiter.version import distribution_version
+
+from .config import (
+    IMAPAccessPolicyConfig,
+    IMAPConfig,
+    IMAPFlagMode,
+    register_configs as register_imap_configs,
+    resolve_imap_flag_mode,
+    resolve_system_flag_key,
+)
+
+from .client import FetchedIMAPMessage
+
+CORE_API_VERSION = "0.9"
+
+
+class IMAPClientProtocol(Protocol):
+    def list_messages(self, *, folder: str, limit: int) -> list[FetchedIMAPMessage]: ...
+
+    def get_message(self, *, folder: str, uid: str) -> FetchedIMAPMessage: ...
+
+    def search_messages(
+        self,
+        *,
+        folder: str,
+        query: str,
+        limit: int,
+    ) -> list[FetchedIMAPMessage]: ...
+
+    def move_message(
+        self,
+        *,
+        source_folder: str,
+        uid: str,
+        destination_folder: str,
+    ) -> None: ...
+
+    def mark_message_read(self, *, folder: str, uid: str, read: bool) -> None: ...
+
+    def delete_message(self, *, folder: str, uid: str) -> None: ...
+
+
+IMAPClientFactory = Callable[[IMAPConfig], IMAPClientProtocol]
+
+
+def _object_schema(
+    properties: Mapping[str, object],
+    required: list[str],
+) -> dict[str, object]:
+    return {
+        "type": "object",
+        "properties": dict(properties),
+        "required": required,
+        "additionalProperties": False,
+    }
+
+
+ACCOUNT_PROPERTY = {
+    "type": "string",
+    "description": "Configured IMAP account name.",
+}
+FOLDER_PROPERTY = {
+    "type": "string",
+    "description": "Configured IMAP folder name. Defaults to the account default folder.",
+}
+MESSAGE_ID_PROPERTY = {
+    "type": "string",
+    "description": "IMAP UID scoped to the selected account and folder.",
+}
+LIMIT_PROPERTY = {
+    "type": "integer",
+    "minimum": 1,
+    "maximum": 100,
+    "description": "Maximum number of messages to return.",
+}
+
+IMAP_OPERATION_DESCRIPTORS = (
+    OperationDescriptor(
+        name="list_messages",
+        description=(
+            "List recent messages from a configured IMAP folder on the selected "
+            "account."
+        ),
+        input_schema=_object_schema(
+            {
+                "account": ACCOUNT_PROPERTY,
+                "folder": FOLDER_PROPERTY,
+                "limit": LIMIT_PROPERTY,
+            },
+            ["account"],
+        ),
+    ),
+    OperationDescriptor(
+        name="get_message",
+        description=(
+            "Fetch one message by IMAP UID from a configured folder on the selected "
+            "account."
+        ),
+        input_schema=_object_schema(
+            {
+                "account": ACCOUNT_PROPERTY,
+                "message_id": MESSAGE_ID_PROPERTY,
+                "folder": FOLDER_PROPERTY,
+            },
+            ["account", "message_id"],
+        ),
+    ),
+    OperationDescriptor(
+        name="search_messages",
+        description=(
+            "Search messages in a configured IMAP folder using an IMAP TEXT query."
+        ),
+        input_schema=_object_schema(
+            {
+                "account": ACCOUNT_PROPERTY,
+                "query": {
+                    "type": "string",
+                    "description": "IMAP TEXT search query.",
+                },
+                "folder": FOLDER_PROPERTY,
+                "limit": LIMIT_PROPERTY,
+            },
+            ["account", "query"],
+        ),
+    ),
+    OperationDescriptor(
+        name="move_message",
+        description=(
+            "Move one message by IMAP UID from a configured source folder to a "
+            "configured destination folder."
+        ),
+        input_schema=_object_schema(
+            {
+                "account": ACCOUNT_PROPERTY,
+                "message_id": MESSAGE_ID_PROPERTY,
+                "destination_folder": {
+                    "type": "string",
+                    "description": "Configured destination folder name.",
+                },
+                "folder": FOLDER_PROPERTY,
+            },
+            ["account", "message_id", "destination_folder"],
+        ),
+    ),
+    OperationDescriptor(
+        name="mark_message_read",
+        description="Set or clear the IMAP seen flag for one message by UID.",
+        input_schema=_object_schema(
+            {
+                "account": ACCOUNT_PROPERTY,
+                "message_id": MESSAGE_ID_PROPERTY,
+                "folder": FOLDER_PROPERTY,
+                "read": {
+                    "type": "boolean",
+                    "description": "Whether the message should be marked read.",
+                },
+            },
+            ["account", "message_id"],
+        ),
+    ),
+    OperationDescriptor(
+        name="delete_message",
+        description=(
+            "Delete one message by IMAP UID from a configured folder on the selected "
+            "account."
+        ),
+        input_schema=_object_schema(
+            {
+                "account": ACCOUNT_PROPERTY,
+                "message_id": MESSAGE_ID_PROPERTY,
+                "folder": FOLDER_PROPERTY,
+            },
+            ["account", "message_id"],
+        ),
+    ),
+)
+
+
+class IMAPRuntime:
+    service_name = "imap"
+
+    def __init__(
+        self,
+        accounts: Mapping[str, object],
+        policies: Mapping[str, object],
+        imap_client_factory: IMAPClientFactory | None = None,
+    ) -> None:
+        self._accounts = cast(Mapping[str, IMAPConfig], accounts)
+        self._policies = cast(
+            Mapping[str, IMAPAccessPolicyConfig],
+            policies,
+        )
+        self._imap_client_factory = imap_client_factory
+        self._validate_policy_references()
+
+    def account_summaries(self) -> dict[str, object]:
+        summaries: dict[str, object] = {}
+        for account_name, account in sorted(self._accounts.items()):
+            imap_policy = self._policies[account.policy]
+            summaries[account_name] = {
+                "description": account.description,
+                "policy": account.policy,
+                "enabled": True,
+                "confirmation_required": [
+                    action.value for action in imap_policy.confirmation_required
+                ],
+                "message": self._message_summary(imap_policy),
+            }
+        return summaries
+
+    def list_messages(
+        self,
+        account: str,
+        folder: str | None = None,
+        limit: int = 20,
+    ) -> dict[str, object]:
+        imap_config, imap_policy, folder_name = self._resolve_context(
+            "list_messages", account, folder
+        )
+        if not imap_policy.allow_read:
+            raise ValueError(f"list_messages is not allowed for account: {account}")
+
+        normalized_limit = self._normalize_limit(limit)
+        messages = self._make_client(imap_config).list_messages(
+            folder=folder_name,
+            limit=normalized_limit,
+        )
+        return {
+            "account": account,
+            "folder": folder_name,
+            "messages": [
+                self._message_to_dict(message, imap_policy, include_body=False)
+                for message in messages
+            ],
+        }
+
+    def get_message(
+        self,
+        account: str,
+        message_id: str,
+        folder: str | None = None,
+    ) -> dict[str, object]:
+        imap_config, imap_policy, folder_name = self._resolve_context(
+            "get_message", account, folder
+        )
+        if not imap_policy.allow_read:
+            raise ValueError(f"get_message is not allowed for account: {account}")
+
+        uid = self._normalize_message_uid(message_id)
+        message = self._make_client(imap_config).get_message(
+            folder=folder_name,
+            uid=uid,
+        )
+        return {
+            "account": account,
+            "folder": folder_name,
+            "message": self._message_to_dict(
+                message,
+                imap_policy,
+                include_body=True,
+            ),
+        }
+
+    def search_messages(
+        self,
+        account: str,
+        query: str,
+        folder: str | None = None,
+        limit: int = 20,
+    ) -> dict[str, object]:
+        imap_config, imap_policy, folder_name = self._resolve_context(
+            "search_messages", account, folder
+        )
+        if not imap_policy.allow_search:
+            raise ValueError(f"search_messages is not allowed for account: {account}")
+
+        normalized_query = query.strip()
+        if not normalized_query:
+            raise ValueError("search_messages requires a non-empty query")
+
+        normalized_limit = self._normalize_limit(limit)
+        messages = self._make_client(imap_config).search_messages(
+            folder=folder_name,
+            query=normalized_query,
+            limit=normalized_limit,
+        )
+        return {
+            "account": account,
+            "folder": folder_name,
+            "query": normalized_query,
+            "messages": [
+                self._message_to_dict(message, imap_policy, include_body=False)
+                for message in messages
+            ],
+        }
+
+    def move_message(
+        self,
+        account: str,
+        message_id: str,
+        destination_folder: str,
+        folder: str | None = None,
+    ) -> dict[str, object]:
+        imap_config, imap_policy, source_folder = self._resolve_context(
+            "move_message", account, folder
+        )
+        if not imap_policy.allow_move:
+            raise ValueError(f"move_message is not allowed for account: {account}")
+
+        uid = self._normalize_message_uid(message_id)
+        normalized_destination = self._resolve_folder(
+            "move_message", imap_config, destination_folder
+        )
+        self._make_client(imap_config).move_message(
+            source_folder=source_folder,
+            uid=uid,
+            destination_folder=normalized_destination,
+        )
+        return {
+            "ok": True,
+            "account": account,
+            "source_folder": source_folder,
+            "destination_folder": normalized_destination,
+            "message_id": uid,
+        }
+
+    def mark_message_read(
+        self,
+        account: str,
+        message_id: str,
+        folder: str | None = None,
+        read: bool = True,
+    ) -> dict[str, object]:
+        imap_config, imap_policy, folder_name = self._resolve_context(
+            "mark_message_read", account, folder
+        )
+        if resolve_imap_flag_mode(imap_policy, "\\Seen") is not IMAPFlagMode.read_write:
+            raise ValueError(
+                f"mark_message_read requires read_write access to the seen flag for account: {account}"
+            )
+
+        uid = self._normalize_message_uid(message_id)
+        self._make_client(imap_config).mark_message_read(
+            folder=folder_name,
+            uid=uid,
+            read=read,
+        )
+        return {
+            "ok": True,
+            "account": account,
+            "folder": folder_name,
+            "message_id": uid,
+            "read": read,
+        }
+
+    def delete_message(
+        self,
+        account: str,
+        message_id: str,
+        folder: str | None = None,
+    ) -> dict[str, object]:
+        imap_config, imap_policy, folder_name = self._resolve_context(
+            "delete_message", account, folder
+        )
+        if not imap_policy.allow_delete:
+            raise ValueError(f"delete_message is not allowed for account: {account}")
+
+        uid = self._normalize_message_uid(message_id)
+        self._make_client(imap_config).delete_message(
+            folder=folder_name,
+            uid=uid,
+        )
+        return {
+            "ok": True,
+            "account": account,
+            "folder": folder_name,
+            "message_id": uid,
+        }
+
+    def _resolve_context(
+        self,
+        tool_name: str,
+        account_name: str,
+        folder: str | None,
+    ) -> tuple[IMAPConfig, IMAPAccessPolicyConfig, str]:
+        imap_config = self._accounts.get(account_name)
+        if imap_config is None:
+            raise ValueError(
+                f"{tool_name} requires an IMAP-enabled account: {account_name}"
+            )
+
+        folder_name = self._resolve_optional_folder(tool_name, imap_config, folder)
+        imap_policy = self._policies.get(imap_config.policy)
+        if imap_policy is None:
+            raise ValueError(
+                f"{tool_name} account references an unknown IMAP policy: {account_name}"
+            )
+        return imap_config, imap_policy, folder_name
+
+    def _validate_policy_references(self) -> None:
+        for account_name, imap_config in sorted(self._accounts.items()):
+            if imap_config.policy not in self._policies:
+                raise ValueError(
+                    "IMAP account references an unknown policy: "
+                    f"{account_name} -> {imap_config.policy}"
+                )
+
+    def _resolve_optional_folder(
+        self,
+        tool_name: str,
+        imap_config: IMAPConfig,
+        folder: str | None,
+    ) -> str:
+        folder_name = folder.strip() if folder else imap_config.default_folder
+        if not folder_name:
+            raise ValueError(
+                f"{tool_name} requires folder when the account has no default_folder"
+            )
+        return self._resolve_folder(tool_name, imap_config, folder_name)
+
+    def _resolve_folder(
+        self,
+        tool_name: str,
+        imap_config: IMAPConfig,
+        folder: str,
+    ) -> str:
+        folder_name = folder.strip()
+        if not folder_name:
+            raise ValueError(f"{tool_name} requires a non-empty folder")
+        if folder_name not in imap_config.folders:
+            raise ValueError(f"{tool_name} received an unconfigured folder: {folder}")
+        return folder_name
+
+    def _make_client(self, imap_config: IMAPConfig) -> IMAPClientProtocol:
+        if self._imap_client_factory is None:
+            raise RuntimeError("IMAP client factory is not configured")
+        return self._imap_client_factory(imap_config)
+
+    def _message_summary(
+        self,
+        imap_policy: IMAPAccessPolicyConfig,
+    ) -> dict[str, object]:
+        flags = self._flag_summary(imap_policy)
+        return {
+            "read_allowed": imap_policy.allow_read,
+            "move_allowed": imap_policy.allow_move,
+            "delete_allowed": imap_policy.allow_delete,
+            "flags": flags,
+        }
+
+    def _flag_summary(
+        self,
+        imap_policy: IMAPAccessPolicyConfig,
+    ) -> dict[str, object]:
+        system_flags = {
+            "seen": imap_policy.system_flags.seen,
+            "flagged": imap_policy.system_flags.flagged,
+            "answered": imap_policy.system_flags.answered,
+            "deleted": imap_policy.system_flags.deleted,
+            "draft": imap_policy.system_flags.draft,
+        }
+        flags: dict[str, object] = {
+            flag_name: mode.value for flag_name, mode in system_flags.items()
+        }
+
+        user_flags = {
+            flag_name: mode.value
+            for flag_name, mode in sorted(imap_policy.user_flags.items())
+            if mode is not IMAPFlagMode.hidden
+        }
+        if user_flags:
+            flags["user"] = user_flags
+
+        return flags
+
+    def _normalize_limit(self, limit: int) -> int:
+        if limit < 1:
+            raise ValueError("IMAP message limit must be at least 1")
+        if limit > 100:
+            raise ValueError("IMAP message limit must be at most 100")
+        return limit
+
+    def _normalize_message_uid(self, message_id: str) -> str:
+        uid = message_id.strip()
+        if not uid:
+            raise ValueError("IMAP message_id must be non-empty")
+        if not uid.isdigit():
+            raise ValueError("IMAP message_id must be an IMAP UID")
+        return uid
+
+    def _message_to_dict(
+        self,
+        message: FetchedIMAPMessage,
+        imap_policy: IMAPAccessPolicyConfig,
+        *,
+        include_body: bool,
+    ) -> dict[str, object]:
+        message_dict: dict[str, object] = {
+            "id": message.uid,
+            "uid": message.uid,
+            "subject": message.subject,
+            "from": message.from_addr,
+            "to": message.to,
+            "cc": message.cc,
+            "date": message.date,
+            "flags": self._visible_flags(imap_policy, message.flags),
+        }
+        if message.rfc822_message_id:
+            message_dict["rfc822_message_id"] = message.rfc822_message_id
+        if message.snippet:
+            message_dict["snippet"] = message.snippet
+        if include_body:
+            message_dict["text_body"] = message.text_body
+            message_dict["html_body"] = message.html_body
+        return message_dict
+
+    def _visible_flags(
+        self,
+        imap_policy: IMAPAccessPolicyConfig,
+        flags: list[str],
+    ) -> list[str]:
+        visible_flags: list[str] = []
+        for flag in flags:
+            mode = resolve_imap_flag_mode(imap_policy, flag)
+            if mode is IMAPFlagMode.hidden:
+                continue
+            visible_flags.append(resolve_system_flag_key(flag) or flag)
+        return visible_flags
+
+
+class IMAPServicePlugin:
+    name = "imap"
+    version = distribution_version("arbiter-imap", package_file=__file__)
+    core_api_version = CORE_API_VERSION
+
+    def register_configs(self, config_store: ConfigStore) -> None:
+        register_imap_configs(config_store)
+
+    def bootstrap_config(self, *, kind: str, name: str) -> object | None:
+        return None
+
+    def build_runtime(
+        self,
+        accounts: Mapping[str, object],
+        policies: Mapping[str, object],
+        context: ServiceRuntimeContext,
+    ) -> object:
+        from .client import IMAPClient
+
+        imap_client_factory = cast(
+            IMAPClientFactory,
+            context.dependencies.get("imap_client_factory", IMAPClient),
+        )
+        return IMAPRuntime(
+            accounts=accounts,
+            policies=policies,
+            imap_client_factory=imap_client_factory,
+        )
+
+    def describe_capability(
+        self,
+        context: ServicePluginContext,
+    ) -> CapabilityDescriptor:
+        return CapabilityDescriptor(
+            name=self.name,
+            description="Read and manage mail through configured IMAP accounts.",
+        )
+
+    def describe_operations(
+        self,
+        context: ServicePluginContext,
+    ) -> tuple[OperationDescriptor, ...]:
+        return IMAP_OPERATION_DESCRIPTORS
+
+    def invoke_operation(
+        self,
+        operation: str,
+        arguments: Mapping[str, object],
+        context: ServicePluginContext,
+    ) -> object:
+        runtime = context.runtimes.require(self.name, IMAPRuntime)
+        if operation == "list_messages":
+            return runtime.list_messages(
+                account=cast(str, arguments.get("account")),
+                folder=cast(str | None, arguments.get("folder")),
+                limit=cast(int, arguments.get("limit", 20)),
+            )
+        if operation == "get_message":
+            return runtime.get_message(
+                account=cast(str, arguments.get("account")),
+                message_id=cast(str, arguments.get("message_id")),
+                folder=cast(str | None, arguments.get("folder")),
+            )
+        if operation == "search_messages":
+            return runtime.search_messages(
+                account=cast(str, arguments.get("account")),
+                query=cast(str, arguments.get("query")),
+                folder=cast(str | None, arguments.get("folder")),
+                limit=cast(int, arguments.get("limit", 20)),
+            )
+        if operation == "move_message":
+            return runtime.move_message(
+                account=cast(str, arguments.get("account")),
+                message_id=cast(str, arguments.get("message_id")),
+                destination_folder=cast(str, arguments.get("destination_folder")),
+                folder=cast(str | None, arguments.get("folder")),
+            )
+        if operation == "mark_message_read":
+            return runtime.mark_message_read(
+                account=cast(str, arguments.get("account")),
+                message_id=cast(str, arguments.get("message_id")),
+                folder=cast(str | None, arguments.get("folder")),
+                read=cast(bool, arguments.get("read", True)),
+            )
+        if operation == "delete_message":
+            return runtime.delete_message(
+                account=cast(str, arguments.get("account")),
+                message_id=cast(str, arguments.get("message_id")),
+                folder=cast(str | None, arguments.get("folder")),
+            )
+        raise ValueError(f"unknown IMAP operation: {operation}")
+
+
+def plugin() -> IMAPServicePlugin:
+    return IMAPServicePlugin()

agent_arbiter_imap/client.py

@@ -0,0 +1,344 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from email import policy
+from email.message import EmailMessage
+from email.parser import BytesParser
+from email.utils import formataddr, getaddresses
+import imaplib
+import re
+import ssl
+from typing import Any
+
+from .config import IMAPConfig, MailTlsMode
+
+
+@dataclass(frozen=True)
+class FetchedIMAPMessage:
+    uid: str
+    subject: str
+    from_addr: str
+    to: list[str]
+    cc: list[str]
+    date: str
+    flags: list[str]
+    rfc822_message_id: str | None
+    text_body: str | None
+    html_body: str | None
+    snippet: str
+
+
+class IMAPOperationError(RuntimeError):
+    pass
+
+
+class IMAPClient:
+    def __init__(self, config: IMAPConfig) -> None:
+        self._config = config
+
+    def list_messages(self, *, folder: str, limit: int) -> list[FetchedIMAPMessage]:
+        with self._session() as server:
+            self._select_folder(server, folder, readonly=True)
+            uids = self._search_uids(server, "ALL")
+            selected_uids = list(reversed(uids))[:limit]
+            return [self._fetch_message(server, uid) for uid in selected_uids]
+
+    def get_message(self, *, folder: str, uid: str) -> FetchedIMAPMessage:
+        with self._session() as server:
+            self._select_folder(server, folder, readonly=True)
+            return self._fetch_message(server, uid)
+
+    def search_messages(
+        self, *, folder: str, query: str, limit: int
+    ) -> list[FetchedIMAPMessage]:
+        with self._session() as server:
+            self._select_folder(server, folder, readonly=True)
+            uids = self._search_uids(server, "TEXT", self._quote_search_text(query))
+            selected_uids = list(reversed(uids))[:limit]
+            return [self._fetch_message(server, uid) for uid in selected_uids]
+
+    def move_message(
+        self, *, source_folder: str, uid: str, destination_folder: str
+    ) -> None:
+        with self._session() as server:
+            self._select_folder(server, source_folder, readonly=False)
+            try:
+                status, data = server.uid("MOVE", uid, destination_folder)
+                if self._move_status_supports_fallback(status, data):
+                    self._copy_then_delete(server, uid, destination_folder)
+                    return
+                self._expect_ok(status, data, "move message")
+            except imaplib.IMAP4.error:
+                self._copy_then_delete(server, uid, destination_folder)
+
+    def mark_message_read(self, *, folder: str, uid: str, read: bool) -> None:
+        with self._session() as server:
+            self._select_folder(server, folder, readonly=False)
+            operation = "+FLAGS.SILENT" if read else "-FLAGS.SILENT"
+            status, data = server.uid("STORE", uid, operation, r"(\Seen)")
+            self._expect_ok(status, data, "mark message read")
+
+    def delete_message(self, *, folder: str, uid: str) -> None:
+        with self._session() as server:
+            self._select_folder(server, folder, readonly=False)
+            self._mark_deleted(server, uid)
+            self._expunge_uid(server, uid, "expunge deleted message")
+
+    def _session(self) -> IMAPSession:
+        return IMAPSession(self._connect())
+
+    def _connect(self) -> imaplib.IMAP4 | imaplib.IMAP4_SSL:
+        ssl_context = self._build_ssl_context()
+        imap_client: imaplib.IMAP4 | imaplib.IMAP4_SSL
+        if self._config.tls == MailTlsMode.implicit:
+            imap_client = imaplib.IMAP4_SSL(
+                self._config.host,
+                self._config.port,
+                ssl_context=ssl_context,
+                timeout=self._config.timeout_seconds,
+            )
+        else:
+            imap_client = imaplib.IMAP4(
+                self._config.host,
+                self._config.port,
+                timeout=self._config.timeout_seconds,
+            )
+            if self._config.tls == MailTlsMode.starttls:
+                imap_client.starttls(ssl_context=ssl_context)
+
+        if self._config.username:
+            imap_client.login(self._config.username, self._config.password)
+
+        return imap_client
+
+    def _build_ssl_context(self) -> ssl.SSLContext:
+        if self._config.verify_peer:
+            return ssl.create_default_context()
+
+        context = ssl.create_default_context()
+        context.check_hostname = False
+        context.verify_mode = ssl.CERT_NONE
+        return context
+
+    def _select_folder(
+        self,
+        server: imaplib.IMAP4 | imaplib.IMAP4_SSL,
+        folder: str,
+        *,
+        readonly: bool,
+    ) -> None:
+        status, data = server.select(folder, readonly=readonly)
+        self._expect_ok(status, data, f"select folder {folder}")
+
+    def _search_uids(
+        self,
+        server: imaplib.IMAP4 | imaplib.IMAP4_SSL,
+        *criteria: str,
+    ) -> list[str]:
+        status, data = server.uid("SEARCH", None, *criteria)  # type: ignore[arg-type]
+        self._expect_ok(status, data, "search messages")
+        if not data:
+            return []
+        raw_uids = data[0]
+        if isinstance(raw_uids, bytes):
+            return [uid.decode("ascii") for uid in raw_uids.split()]
+        if isinstance(raw_uids, str):
+            return raw_uids.split()
+        return []
+
+    def _fetch_message(
+        self,
+        server: imaplib.IMAP4 | imaplib.IMAP4_SSL,
+        uid: str,
+    ) -> FetchedIMAPMessage:
+        flags = self._fetch_flags(server, uid)
+        message_bytes = self._fetch_message_bytes(server, uid)
+        email_message = BytesParser(policy=policy.default).parsebytes(message_bytes)
+        text_body, html_body = self._extract_bodies(email_message)
+        snippet = self._snippet_from_body(text_body or html_body or "")
+        return FetchedIMAPMessage(
+            uid=uid,
+            subject=email_message.get("Subject", ""),
+            from_addr=self._first_address(email_message, "From"),
+            to=self._addresses(email_message, "To"),
+            cc=self._addresses(email_message, "Cc"),
+            date=email_message.get("Date", ""),
+            flags=flags,
+            rfc822_message_id=email_message.get("Message-ID"),
+            text_body=text_body,
+            html_body=html_body,
+            snippet=snippet,
+        )
+
+    def _fetch_flags(
+        self,
+        server: imaplib.IMAP4 | imaplib.IMAP4_SSL,
+        uid: str,
+    ) -> list[str]:
+        status, data = server.uid("FETCH", uid, "(FLAGS)")
+        self._expect_ok(status, data, "fetch message flags")
+        flags: list[str] = []
+        for item in data:
+            raw = self._raw_fetch_item(item)
+            if raw is None:
+                continue
+            match = re.search(rb"FLAGS \((.*?)\)", raw)
+            if match is None:
+                continue
+            flags.extend(
+                flag.decode("utf-8", errors="replace")
+                for flag in match.group(1).split()
+            )
+        return flags
+
+    def _fetch_message_bytes(
+        self,
+        server: imaplib.IMAP4 | imaplib.IMAP4_SSL,
+        uid: str,
+    ) -> bytes:
+        status, data = server.uid("FETCH", uid, "(RFC822)")
+        self._expect_ok(status, data, "fetch message body")
+        for item in data:
+            if (
+                isinstance(item, tuple)
+                and len(item) >= 2
+                and isinstance(item[1], bytes)
+            ):
+                return item[1]
+        raise IMAPOperationError(f"IMAP fetch for UID {uid} did not return RFC822 data")
+
+    def _copy_then_delete(
+        self,
+        server: imaplib.IMAP4 | imaplib.IMAP4_SSL,
+        uid: str,
+        destination_folder: str,
+    ) -> None:
+        status, data = server.uid("COPY", uid, destination_folder)
+        self._expect_ok(status, data, "copy message")
+        self._mark_deleted(server, uid)
+        self._expunge_uid(server, uid, "expunge moved message")
+
+    def _mark_deleted(
+        self,
+        server: imaplib.IMAP4 | imaplib.IMAP4_SSL,
+        uid: str,
+    ) -> None:
+        status, data = server.uid("STORE", uid, "+FLAGS.SILENT", r"(\Deleted)")
+        self._expect_ok(status, data, "mark message deleted")
+
+    def _expunge_uid(
+        self,
+        server: imaplib.IMAP4 | imaplib.IMAP4_SSL,
+        uid: str,
+        action: str,
+    ) -> None:
+        status, data = server.uid("EXPUNGE", uid)
+        self._expect_ok(status, data, action)
+
+    def _expect_ok(self, status: str, data: list[Any], action: str) -> None:
+        if status.upper() != "OK":
+            raise IMAPOperationError(f"IMAP {action} failed: {status} {data!r}")
+
+    def _move_status_supports_fallback(self, status: str, data: list[Any]) -> bool:
+        normalized_status = status.upper()
+        if normalized_status not in {"BAD", "NO"}:
+            return False
+
+        response_text = " ".join(
+            (
+                item.decode("utf-8", errors="replace")
+                if isinstance(item, bytes)
+                else str(item)
+            )
+            for item in data
+        ).lower()
+        return any(
+            marker in response_text
+            for marker in (
+                "move unsupported",
+                "move unavailable",
+                "move not supported",
+                "unknown command",
+                "unrecognized command",
+            )
+        )
+
+    def _raw_fetch_item(self, item: object) -> bytes | None:
+        if isinstance(item, bytes):
+            return item
+        if isinstance(item, tuple) and item and isinstance(item[0], bytes):
+            return item[0]
+        return None
+
+    def _quote_search_text(self, query: str) -> str:
+        return '"' + query.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+    def _addresses(self, message: EmailMessage, header_name: str) -> list[str]:
+        values = message.get_all(header_name, [])
+        return [
+            formataddr((display_name, address)) if display_name else address
+            for display_name, address in getaddresses(values)
+            if address
+        ]
+
+    def _first_address(self, message: EmailMessage, header_name: str) -> str:
+        addresses = self._addresses(message, header_name)
+        if not addresses:
+            return ""
+        return addresses[0]
+
+    def _extract_bodies(self, message: EmailMessage) -> tuple[str | None, str | None]:
+        text_body: str | None = None
+        html_body: str | None = None
+
+        if message.is_multipart():
+            for part in message.walk():
+                email_part = part
+                if email_part.is_multipart():
+                    continue
+                if email_part.get_content_disposition() == "attachment":
+                    continue
+                content_type = email_part.get_content_type()
+                if content_type == "text/plain" and text_body is None:
+                    text_body = self._part_content(email_part)
+                elif content_type == "text/html" and html_body is None:
+                    html_body = self._part_content(email_part)
+            return text_body, html_body
+
+        content_type = message.get_content_type()
+        if content_type == "text/html":
+            return None, self._part_content(message)
+        return self._part_content(message), None
+
+    def _part_content(self, part: EmailMessage) -> str:
+        content = part.get_content()
+        if isinstance(content, str):
+            return content
+        if isinstance(content, bytes):
+            return content.decode(
+                part.get_content_charset() or "utf-8", errors="replace"
+            )
+        return str(content)
+
+    def _snippet_from_body(self, body: str) -> str:
+        compact = " ".join(body.split())
+        return compact[:240]
+
+
+class IMAPSession:
+    def __init__(self, server: imaplib.IMAP4 | imaplib.IMAP4_SSL) -> None:
+        self._server = server
+
+    def __enter__(self) -> imaplib.IMAP4 | imaplib.IMAP4_SSL:
+        return self._server
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: object,
+    ) -> None:
+        try:
+            self._server.logout()
+        except OSError:
+            return

agent_arbiter_imap/config.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+from agent_arbiter.config import Policy
+from hydra.core.config_store import ConfigStore
+
+
+class MailTlsMode(str, Enum):
+    none = "none"
+    starttls = "starttls"
+    implicit = "implicit"
+
+
+class IMAPFlagMode(str, Enum):
+    hidden = "hidden"
+    read_only = "read_only"
+    read_write = "read_write"
+
+
+class IMAPConfirmationAction(str, Enum):
+    read = "read"
+    search = "search"
+    move = "move"
+    mark_read = "mark_read"
+    delete = "delete"
+
+
+@dataclass
+class IMAPFolderConfig:
+    description: str = ""
+
+
+@dataclass
+class IMAPConfig(Policy):
+    policy: str = "bot"
+    description: str = ""
+    host: str = "localhost"
+    port: int = 993
+    username: str = ""
+    password: str = ""
+    tls: MailTlsMode = MailTlsMode.implicit
+    verify_peer: bool = True
+    timeout_seconds: float = 30.0
+    default_folder: str | None = None
+    folders: dict[str, IMAPFolderConfig] = field(default_factory=dict)
+
+
+@dataclass
+class IMAPSystemFlagsPolicyConfig:
+    seen: IMAPFlagMode = IMAPFlagMode.read_only
+    flagged: IMAPFlagMode = IMAPFlagMode.read_only
+    answered: IMAPFlagMode = IMAPFlagMode.read_only
+    deleted: IMAPFlagMode = IMAPFlagMode.read_only
+    draft: IMAPFlagMode = IMAPFlagMode.read_only
+
+
+@dataclass
+class IMAPAccessPolicyConfig(Policy):
+    allow_read: bool = True
+    allow_search: bool = True
+    allow_move: bool = True
+    allow_delete: bool = True
+    confirmation_required: list[IMAPConfirmationAction] = field(default_factory=list)
+    system_flags: IMAPSystemFlagsPolicyConfig = field(
+        default_factory=IMAPSystemFlagsPolicyConfig
+    )
+    user_flags: dict[str, IMAPFlagMode] = field(default_factory=dict)
+
+
+SYSTEM_FLAG_NAME_MAP = {
+    "\\Seen": "seen",
+    "\\Flagged": "flagged",
+    "\\Answered": "answered",
+    "\\Deleted": "deleted",
+    "\\Draft": "draft",
+}
+
+
+def resolve_system_flag_key(flag_name: str) -> str | None:
+    return SYSTEM_FLAG_NAME_MAP.get(flag_name)
+
+
+def resolve_imap_flag_mode(
+    policy: IMAPAccessPolicyConfig,
+    flag_name: str,
+) -> IMAPFlagMode:
+    system_flag_key = resolve_system_flag_key(flag_name)
+    if system_flag_key == "seen":
+        return policy.system_flags.seen
+    if system_flag_key == "flagged":
+        return policy.system_flags.flagged
+    if system_flag_key == "answered":
+        return policy.system_flags.answered
+    if system_flag_key == "deleted":
+        return policy.system_flags.deleted
+    if system_flag_key == "draft":
+        return policy.system_flags.draft
+    if flag_name.startswith("\\"):
+        return IMAPFlagMode.read_only
+    return policy.user_flags.get(flag_name, IMAPFlagMode.hidden)
+
+
+def register_configs(config_store: ConfigStore) -> None:
+    config_store.store(
+        group="arbiter/account/imap",
+        name="schema",
+        node=IMAPConfig,
+        provider="arbiter-imap",
+    )
+    config_store.store(
+        group="arbiter/policy/imap",
+        name="schema",
+        node=IMAPAccessPolicyConfig,
+        provider="arbiter-imap",
+    )

agent_arbiter_imap/py.typed

@@ -0,0 +1 @@
+

arbiter_imap-0.9.0.dev1.dist-info/METADATA

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: arbiter-imap
+Version: 0.9.0.dev1
+Summary: IMAP service plugin for Arbiter
+Author-email: Omry Yadan <omry@yadan.net>
+Maintainer-email: Omry Yadan <omry@yadan.net>
+License: MIT
+Project-URL: Homepage, https://github.com/omry/arbiter
+Project-URL: Repository, https://github.com/omry/arbiter
+Keywords: agent,mcp,imap,email
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: arbiter-core<0.10.0,>=0.9.0.dev1
+
+IMAP service plugin for Arbiter.

arbiter_imap-0.9.0.dev1.dist-info/RECORD

@@ -0,0 +1,9 @@
+agent_arbiter_imap/__init__.py,sha256=QpOkIQHlmkBzzP5N_fL2GvoQYCI2OIhHynZdfiQVXpc,20844
+agent_arbiter_imap/client.py,sha256=AcSkSgiFZ76lfp_9CvmPsX0HYSD5kplGph30ntd2W2o,12119
+agent_arbiter_imap/config.py,sha256=Lq9V4OdawRhnJPyd47zJ96gyeiyNy-g9TQgYHQdvgR4,3080
+agent_arbiter_imap/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+arbiter_imap-0.9.0.dev1.dist-info/METADATA,sha256=OLgl1ZMaOHOwL0rSvVLC9aYwxTQxXH2OvpY63MH-TS8,985
+arbiter_imap-0.9.0.dev1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+arbiter_imap-0.9.0.dev1.dist-info/entry_points.txt,sha256=kww1EGT9CIlo4US329fqJUgKTOJOt0533pKxGnTqmDk,58
+arbiter_imap-0.9.0.dev1.dist-info/top_level.txt,sha256=lWokCNTLRj3gAUsRwTziOTAfOVuZBoUUP_HM1lxG6sw,19
+arbiter_imap-0.9.0.dev1.dist-info/RECORD,,

arbiter_imap-0.9.0.dev1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

arbiter_imap-0.9.0.dev1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[agent_arbiter.services]
+imap = agent_arbiter_imap:plugin

arbiter_imap-0.9.0.dev1.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_arbiter_imap