arbiter-smtp 0.9.0.dev1__tar.gz → 0.9.1.dev2__tar.gz

{arbiter_smtp-0.9.0.dev1 → arbiter_smtp-0.9.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arbiter-smtp
-Version: 0.9.0.dev1
+Version: 0.9.1.dev2
 Summary: SMTP service plugin for Arbiter
 Author-email: Omry Yadan <omry@yadan.net>
 Maintainer-email: Omry Yadan <omry@yadan.net>
@@ -20,7 +20,7 @@ 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
+Requires-Dist: arbiter-server<0.10.0,>=0.9.1.dev2
 Requires-Dist: diskcache<6.0,>=5.6
 
 SMTP service plugin for Arbiter.

{arbiter_smtp-0.9.0.dev1 → arbiter_smtp-0.9.1.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arbiter-smtp"
-version = "0.9.0.dev1"
+version = "0.9.1.dev2"
 description = "SMTP service plugin for Arbiter"
 readme = { text = "SMTP service plugin for Arbiter.", content-type = "text/markdown" }
 requires-python = ">=3.10,<3.15"
@@ -29,7 +29,7 @@ classifiers = [
   "Topic :: Communications :: Email",
 ]
 dependencies = [
-  "arbiter-core>=0.9.0.dev1,<0.10.0",
+  "arbiter-server>=0.9.1.dev2,<0.10.0",
   "diskcache>=5.6,<6.0",
 ]
 
@@ -37,8 +37,8 @@ dependencies = [
 Homepage = "https://github.com/omry/arbiter"
 Repository = "https://github.com/omry/arbiter"
 
-[project.entry-points."agent_arbiter.services"]
-smtp = "agent_arbiter_smtp:plugin"
+[project.entry-points."arbiter.services"]
+smtp = "arbiter_smtp:plugin"
 
 [tool.setuptools]
 package-dir = {"" = "src"}
@@ -47,11 +47,11 @@ package-dir = {"" = "src"}
 where = ["src"]
 
 [tool.setuptools.package-data]
-"agent_arbiter_smtp" = ["py.typed"]
+"arbiter_smtp" = ["py.typed"]
 
 [tool.towncrier]
 name = "Arbiter SMTP"
-package = "agent_arbiter_smtp"
+package = "arbiter_smtp"
 package_dir = "src"
 filename = "NEWS.md"
 directory = "newsfragments"

{arbiter_smtp-0.9.0.dev1/src/agent_arbiter_smtp → arbiter_smtp-0.9.1.dev2/src/arbiter_smtp}/__init__.py

@@ -2,23 +2,27 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from dataclasses import dataclass
+from datetime import datetime, timezone
+from email import policy as email_policy
 from email.message import EmailMessage
-from email.utils import formataddr, make_msgid
+from email.utils import format_datetime, formataddr, make_msgid
 import hashlib
 import json
+import secrets
 import smtplib
 from time import monotonic
 from typing import Callable, Protocol, cast
 
 from hydra.core.config_store import ConfigStore
 
-from agent_arbiter.services import (
+from arbiter_server.services import (
     CapabilityDescriptor,
     OperationDescriptor,
     ServicePluginContext,
     ServiceRuntimeContext,
 )
-from agent_arbiter.version import distribution_version
+from arbiter_server.storage import PluginStorage
+from arbiter_server.version import distribution_version
 
 from .config import (
     SMTPConfig,
@@ -27,7 +31,7 @@ from .config import (
 )
 from .idempotency import SMTPIdempotencyResult, SMTPIdempotencyStore
 
-CORE_API_VERSION = "0.9"
+SERVER_API_VERSION = "0.9"
 
 
 @dataclass(frozen=True)
@@ -35,18 +39,50 @@ class SendEmailResult:
     tool: str
     message_id: str
     recipient_count: int
+    sent_copy: dict[str, object] | None = None
     idempotency_replayed: bool = False
 
 
+@dataclass(frozen=True)
+class SentCopyDestination:
+    account: str
+    folder: str
+
+
+class SMTPSentCopyError(RuntimeError):
+    def __init__(self, message: str, *, result: SendEmailResult) -> None:
+        super().__init__(message)
+        self.result = result
+
+
 class SMTPClientProtocol(Protocol):
+    def test_connection(self) -> None: ...
+
     def send(
         self,
-        message: EmailMessage,
+        message_bytes: bytes,
         sender: str,
         recipients: list[str],
     ) -> None: ...
 
 
+class SentMessageAppender(Protocol):
+    def resolve_destination(
+        self,
+        *,
+        account: str,
+        folder: str | None,
+    ) -> SentCopyDestination: ...
+
+    def append_sent_message(
+        self,
+        *,
+        account: str,
+        folder: str,
+        message_bytes: bytes,
+    ) -> None: ...
+
+
 SMTPClientFactory = Callable[[SMTPConfig], SMTPClientProtocol]
 TimeProvider = Callable[[], float]
 SMTPIdempotencyStoreFactory = Callable[[str], SMTPIdempotencyStore]
@@ -112,6 +148,8 @@ class SMTPRuntime:
         smtp_client_factory: SMTPClientFactory,
         time_provider: TimeProvider = monotonic,
         idempotency_store_factory: SMTPIdempotencyStoreFactory = SMTPIdempotencyStore,
+        plugin_storage: PluginStorage | None = None,
+        sent_message_appender: SentMessageAppender | None = None,
     ) -> None:
         self._accounts = cast(Mapping[str, SMTPConfig], accounts)
         self._policies = cast(
@@ -121,14 +159,23 @@ class SMTPRuntime:
         self._smtp_client_factory = smtp_client_factory
         self._time_provider = time_provider
         self._idempotency_store_factory = idempotency_store_factory
+        self._plugin_storage = plugin_storage
+        self._sent_message_appender = sent_message_appender
         self._idempotency_stores: dict[str, SMTPIdempotencyStore] = {}
         self._attempt_timestamps: dict[str, list[float]] = {}
         self._validate_config()
 
+    def configure_sent_message_appender(
+        self,
+        sent_message_appender: SentMessageAppender,
+    ) -> None:
+        self._sent_message_appender = sent_message_appender
+
     def account_summaries(self) -> dict[str, object]:
         return {
             account_name: {
                 "description": account.description,
+                "guidance": account.guidance,
                 "policy": account.policy,
                 "enabled": True,
                 "send": "allowed",
@@ -139,6 +186,47 @@ class SMTPRuntime:
             for account_name, account in sorted(self._accounts.items())
         }
 
+    def test_accounts(self) -> dict[str, object]:
+        results: dict[str, object] = {}
+        for account_name, smtp_config in sorted(self._accounts.items()):
+            smtp_policy = self._policies[smtp_config.policy]
+            stage = "connect_auth_noop_idempotency"
+            strict_sent_copy = self._sent_copy_requires_readiness_check(smtp_policy)
+            try:
+                self._smtp_client_factory(smtp_config).test_connection()
+                self._test_idempotency_storage(smtp_policy)
+                if strict_sent_copy:
+                    stage = "connect_auth_noop_idempotency_sent_copy"
+                    self._test_sent_copy_destination(
+                        account=account_name,
+                        smtp_config=smtp_config,
+                        smtp_policy=smtp_policy,
+                    )
+            except Exception as exc:
+                results[account_name] = {
+                    "status": "failed",
+                    "stage": stage,
+                    "error_type": type(exc).__name__,
+                    "message": str(exc),
+                }
+                continue
+            checks = ["connect", "ehlo", "noop"]
+            if smtp_config.tls.value != "none":
+                checks.append("tls")
+            if smtp_config.authenticate:
+                checks.append("authenticate")
+            checks.append("idempotency_storage")
+            if strict_sent_copy:
+                checks.append("sent_copy_destination")
+            results[account_name] = {
+                "status": "ok",
+                "stage": stage,
+                "checks": checks,
+                "delivery": "skipped",
+                "reason": "read-only SMTP account test does not send mail",
+            }
+        return results
+
     def send_email(
         self,
         account: str,
@@ -169,6 +257,7 @@ class SMTPRuntime:
         if recipients_cc:
             message["Cc"] = ", ".join(recipients_cc)
         message["Subject"] = normalized_subject
+        message["Date"] = format_datetime(datetime.now(timezone.utc))
         message["Message-ID"] = make_msgid(domain=self._sender_domain(smtp_config))
 
         if text_body:
@@ -177,6 +266,7 @@ class SMTPRuntime:
                 message.add_alternative(html_body, subtype="html")
         else:
             message.set_content(html_body or "", subtype="html")
+        message_bytes = message.as_bytes(policy=email_policy.SMTP)
 
         envelope_recipients = recipients_to + recipients_cc + recipients_bcc
         self._enforce_policy(account, smtp_policy, envelope_recipients)
@@ -203,17 +293,28 @@ class SMTPRuntime:
             )
             replayed_result = self._reserve_or_replay_idempotency(
                 smtp_policy,
+                account=account,
+                smtp_config=smtp_config,
                 cache_key=cache_key,
                 payload_hash=payload_hash,
             )
             if replayed_result is not None:
                 return replayed_result
 
+        sent_copy_destination: SentCopyDestination | None = None
+        sent_copy_result: dict[str, object] | None = None
         try:
+            sent_copy_destination, sent_copy_result = (
+                self._resolve_sent_copy_destination(
+                    account=account,
+                    smtp_config=smtp_config,
+                    smtp_policy=smtp_policy,
+                )
+            )
             self._consume_rate_limit(account, smtp_policy)
             smtp_client = self._smtp_client_factory(smtp_config)
             smtp_client.send(
-                message,
+                message_bytes,
                 sender=smtp_config.from_email,
                 recipients=envelope_recipients,
             )
@@ -225,10 +326,23 @@ class SMTPRuntime:
                 self._idempotency_store(smtp_policy).delete(cache_key)
             raise
 
+        if sent_copy_result is None and sent_copy_destination is not None:
+            sent_copy_result = self._append_sent_copy(
+                destination=sent_copy_destination,
+                message_bytes=message_bytes,
+            )
+        if sent_copy_result is None:
+            sent_copy_result = self._sent_copy_outcome(
+                "skipped",
+                account=account,
+                reason="sent copy destination was not resolved",
+            )
+
         result = SendEmailResult(
             tool="send_email",
             message_id=str(message["Message-ID"]),
             recipient_count=len(envelope_recipients),
+            sent_copy=sent_copy_result,
         )
         if cache_key is not None and payload_hash is not None:
             self._idempotency_store(smtp_policy).store_success(
@@ -237,9 +351,15 @@ class SMTPRuntime:
                 result=SMTPIdempotencyResult(
                     message_id=result.message_id,
                     recipient_count=result.recipient_count,
+                    sent_copy=result.sent_copy,
+                    sent_copy_message_bytes=self._sent_copy_retry_message_bytes(
+                        sent_copy_result,
+                        message_bytes,
+                    ),
                 ),
                 expire_seconds=self._idempotency_expire_seconds(smtp_policy),
             )
+        self._raise_if_submitted_sent_copy_required(result, smtp_policy)
         return result
 
     def _resolve_context(
@@ -260,6 +380,191 @@ class SMTPRuntime:
 
         return smtp_config, smtp_policy
 
+    def _resolve_sent_copy_destination(
+        self,
+        *,
+        account: str,
+        smtp_config: SMTPConfig,
+        smtp_policy: SMTPServicePolicyConfig,
+        enforce_required: bool = True,
+    ) -> tuple[SentCopyDestination | None, dict[str, object] | None]:
+        if not smtp_policy.sent_copy.enabled:
+            return None, self._sent_copy_outcome("disabled", account=account)
+
+        folder_override = self._normalize_sent_copy_folder(smtp_config.sent_copy.folder)
+        if self._sent_message_appender is None:
+            result = self._sent_copy_outcome(
+                "skipped",
+                account=account,
+                reason="IMAP sent-copy appender is not configured",
+            )
+            if enforce_required:
+                self._raise_if_sent_copy_required(result, smtp_policy)
+            return None, result
+
+        try:
+            destination = self._sent_message_appender.resolve_destination(
+                account=account,
+                folder=folder_override,
+            )
+        except Exception as exc:
+            result = self._sent_copy_outcome(
+                "skipped",
+                account=account,
+                reason=str(exc),
+                error_type=type(exc).__name__,
+            )
+            if enforce_required:
+                self._raise_if_sent_copy_required(result, smtp_policy)
+            return None, result
+
+        return destination, None
+
+    def _append_sent_copy(
+        self,
+        *,
+        destination: SentCopyDestination,
+        message_bytes: bytes,
+    ) -> dict[str, object]:
+        if self._sent_message_appender is None:
+            return self._sent_copy_outcome(
+                "skipped",
+                account=destination.account,
+                folder=destination.folder,
+                reason="IMAP sent-copy appender is not configured",
+            )
+        try:
+            self._sent_message_appender.append_sent_message(
+                account=destination.account,
+                folder=destination.folder,
+                message_bytes=message_bytes,
+            )
+        except Exception as exc:
+            return self._sent_copy_outcome(
+                "failed",
+                account=destination.account,
+                folder=destination.folder,
+                reason=str(exc),
+                error_type=type(exc).__name__,
+            )
+        return self._sent_copy_outcome(
+            "saved",
+            account=destination.account,
+            folder=destination.folder,
+        )
+
+    def _raise_if_sent_copy_required(
+        self,
+        result: dict[str, object],
+        smtp_policy: SMTPServicePolicyConfig,
+    ) -> None:
+        if smtp_policy.sent_copy.on_failure.value != "fail":
+            return
+        raise RuntimeError(f"send_email sent-copy preflight failed: {result['reason']}")
+
+    def _normalize_sent_copy_folder(self, folder: str | None) -> str | None:
+        if folder is None:
+            return None
+        normalized = folder.strip()
+        if not normalized:
+            raise ValueError("SMTP sent_copy.folder must be non-empty when configured")
+        return normalized
+
+    def _sent_copy_outcome(
+        self,
+        status: str,
+        *,
+        account: str | None = None,
+        folder: str | None = None,
+        reason: str | None = None,
+        error_type: str | None = None,
+    ) -> dict[str, object]:
+        result: dict[str, object] = {"status": status}
+        if account is not None:
+            result["account"] = account
+        if folder is not None:
+            result["folder"] = folder
+        if reason is not None:
+            result["reason"] = reason
+        if error_type is not None:
+            result["error_type"] = error_type
+        return result
+
+    def _sent_copy_retry_message_bytes(
+        self,
+        sent_copy_result: dict[str, object],
+        message_bytes: bytes,
+    ) -> bytes | None:
+        if sent_copy_result.get("status") in {"failed", "skipped"}:
+            return message_bytes
+        return None
+
+    def _sent_copy_needs_idempotent_retry(
+        self,
+        result: SMTPIdempotencyResult,
+    ) -> bool:
+        if result.sent_copy_message_bytes is None:
+            return False
+        if result.sent_copy is None:
+            return True
+        return result.sent_copy.get("status") in {"failed", "skipped"}
+
+    def _retry_sent_copy_from_idempotency(
+        self,
+        *,
+        account: str,
+        smtp_config: SMTPConfig,
+        smtp_policy: SMTPServicePolicyConfig,
+        result: SMTPIdempotencyResult,
+    ) -> SendEmailResult:
+        sent_copy_result = result.sent_copy
+        if result.sent_copy_message_bytes is not None:
+            destination, resolved_result = self._resolve_sent_copy_destination(
+                account=account,
+                smtp_config=smtp_config,
+                smtp_policy=smtp_policy,
+                enforce_required=False,
+            )
+            sent_copy_result = resolved_result
+            if destination is not None:
+                sent_copy_result = self._append_sent_copy(
+                    destination=destination,
+                    message_bytes=result.sent_copy_message_bytes,
+                )
+        if sent_copy_result is None:
+            sent_copy_result = self._sent_copy_outcome(
+                "skipped",
+                account=account,
+                reason="sent copy destination was not resolved",
+            )
+        replayed_result = SendEmailResult(
+            tool="send_email",
+            message_id=result.message_id,
+            recipient_count=result.recipient_count,
+            sent_copy=sent_copy_result,
+            idempotency_replayed=True,
+        )
+        self._raise_if_submitted_sent_copy_required(replayed_result, smtp_policy)
+        return replayed_result
+
+    def _raise_if_submitted_sent_copy_required(
+        self,
+        result: SendEmailResult,
+        smtp_policy: SMTPServicePolicyConfig,
+    ) -> None:
+        if smtp_policy.sent_copy.on_failure.value != "fail":
+            return
+        sent_copy_result = result.sent_copy or {}
+        if sent_copy_result.get("status") in {"saved", "disabled"}:
+            return
+        reason = sent_copy_result.get("reason")
+        suffix = f": {reason}" if reason else ""
+        raise SMTPSentCopyError(
+            "send_email submitted the SMTP message but failed to save "
+            f"a sent copy{suffix}",
+            result=result,
+        )
+
     def _validate_config(self) -> None:
         for account_name, smtp_config in sorted(self._accounts.items()):
             if smtp_config.policy not in self._policies:
@@ -267,16 +572,26 @@ class SMTPRuntime:
                     "SMTP account references an unknown policy: "
                     f"{account_name} -> {smtp_config.policy}"
                 )
+            if (
+                smtp_config.sent_copy.folder is not None
+                and not smtp_config.sent_copy.folder.strip()
+            ):
+                raise ValueError(
+                    f"SMTP sent_copy.folder must be non-empty: {account_name}"
+                )
         for policy_name, smtp_policy in sorted(self._policies.items()):
             if smtp_policy.idempotency.expiration_days <= 0:
                 raise ValueError(
                     "SMTP idempotency expiration_days must be positive: "
                     f"{policy_name}"
                 )
-            if not smtp_policy.idempotency.cache_dir.strip():
+            cache_dir = smtp_policy.idempotency.cache_dir
+            if cache_dir is not None and not cache_dir.strip():
                 raise ValueError(
                     f"SMTP idempotency cache_dir must be non-empty: {policy_name}"
                 )
+            if cache_dir is not None and self._plugin_storage is not None:
+                self._plugin_storage.path(cache_dir.strip())
 
     def _normalize_recipients(
         self,
@@ -437,6 +752,8 @@ class SMTPRuntime:
         self,
         smtp_policy: SMTPServicePolicyConfig,
         *,
+        account: str,
+        smtp_config: SMTPConfig,
         cache_key: str,
         payload_hash: str,
     ) -> SendEmailResult | None:
@@ -466,10 +783,33 @@ class SMTPRuntime:
             )
         if record.result is None:
             raise ValueError("send_email idempotency_key is already in progress")
+        if self._sent_copy_needs_idempotent_retry(record.result):
+            replayed_result = self._retry_sent_copy_from_idempotency(
+                account=account,
+                smtp_config=smtp_config,
+                smtp_policy=smtp_policy,
+                result=record.result,
+            )
+            store.store_success(
+                cache_key,
+                payload_hash=payload_hash,
+                result=SMTPIdempotencyResult(
+                    message_id=replayed_result.message_id,
+                    recipient_count=replayed_result.recipient_count,
+                    sent_copy=replayed_result.sent_copy,
+                    sent_copy_message_bytes=self._sent_copy_retry_message_bytes(
+                        replayed_result.sent_copy or {},
+                        record.result.sent_copy_message_bytes or b"",
+                    ),
+                ),
+                expire_seconds=expire_seconds,
+            )
+            return replayed_result
         return SendEmailResult(
             tool="send_email",
             message_id=record.result.message_id,
             recipient_count=record.result.recipient_count,
+            sent_copy=record.result.sent_copy,
             idempotency_replayed=True,
         )
 
@@ -477,13 +817,69 @@ class SMTPRuntime:
         self,
         smtp_policy: SMTPServicePolicyConfig,
     ) -> SMTPIdempotencyStore:
-        cache_dir = smtp_policy.idempotency.cache_dir
+        cache_dir = self._idempotency_cache_dir(smtp_policy)
         store = self._idempotency_stores.get(cache_dir)
         if store is None:
             store = self._idempotency_store_factory(cache_dir)
             self._idempotency_stores[cache_dir] = store
         return store
 
+    def _test_idempotency_storage(
+        self,
+        smtp_policy: SMTPServicePolicyConfig,
+    ) -> None:
+        store = self._idempotency_store(smtp_policy)
+        key = f"__arbiter_readiness__:{secrets.token_urlsafe(16)}"
+        payload_hash = hashlib.sha256(key.encode("utf-8")).hexdigest()
+        try:
+            added = store.add_pending(
+                key,
+                payload_hash=payload_hash,
+                expire_seconds=60,
+            )
+            if not added:
+                raise ValueError("SMTP idempotency cache readiness key collided")
+            record = store.get(key)
+            if record is None or record.payload_hash != payload_hash:
+                raise ValueError("SMTP idempotency cache readiness read failed")
+        finally:
+            store.delete(key)
+
+    def _sent_copy_requires_readiness_check(
+        self,
+        smtp_policy: SMTPServicePolicyConfig,
+    ) -> bool:
+        return (
+            smtp_policy.sent_copy.enabled
+            and smtp_policy.sent_copy.on_failure.value == "fail"
+        )
+
+    def _test_sent_copy_destination(
+        self,
+        *,
+        account: str,
+        smtp_config: SMTPConfig,
+        smtp_policy: SMTPServicePolicyConfig,
+    ) -> None:
+        self._resolve_sent_copy_destination(
+            account=account,
+            smtp_config=smtp_config,
+            smtp_policy=smtp_policy,
+            enforce_required=True,
+        )
+
+    def _idempotency_cache_dir(self, smtp_policy: SMTPServicePolicyConfig) -> str:
+        configured_cache_dir = smtp_policy.idempotency.cache_dir
+        if configured_cache_dir is not None:
+            if self._plugin_storage is not None:
+                return str(self._plugin_storage.path(configured_cache_dir.strip()))
+            return configured_cache_dir.strip()
+        if self._plugin_storage is None:
+            raise ValueError(
+                "SMTP idempotency cache_dir is required when plugin storage is unavailable"
+            )
+        return str(self._plugin_storage.path("idempotency"))
+
     def _idempotency_expire_seconds(
         self,
         smtp_policy: SMTPServicePolicyConfig,
@@ -524,6 +920,9 @@ defaults:
 # Human-facing summary shown by account listing tools.
 description: SMTP account for (${{.from_email}})
 
+# Operator guidance shown to agents during discovery.
+guidance: ""
+
 # Matching policy generated alongside this account.
 policy: {policy_name}
 
@@ -546,6 +945,11 @@ from_name: Arbiter
 tls: starttls
 verify_peer: true
 timeout_seconds: 30
+
+# Optional override for the IMAP sent-copy folder used after successful sends.
+# Leave null to infer the only kind=sent folder on the matching IMAP account.
+sent_copy:
+  folder: null
 """
 
 
@@ -567,7 +971,9 @@ limits:
 # Dedupe window for repeated send attempts.
 idempotency:
   expiration_days: 7
-  cache_dir: .arbiter/smtp-idempotency
+  # Optional plugin-relative subdirectory. Defaults to the SMTP plugin's
+  # private writable space under idempotency/.
+  cache_dir: null
 
 # Empty lists do not restrict recipients. Add entries to enforce allow/block rules.
 recipient_policy:
@@ -575,13 +981,20 @@ recipient_policy:
   blocked_recipients: []
   allowed_domain_patterns: []
   blocked_domain_patterns: []
+
+# Save submitted messages to the matching IMAP account's Sent folder when one
+# can be resolved. on_failure=warn keeps SMTP success even if IMAP append fails;
+# on_failure=fail treats missing sent-copy audit as an operation failure.
+sent_copy:
+  enabled: true
+  on_failure: warn
 """
 
 
 class SMTPServicePlugin:
     name = "smtp"
     version = distribution_version("arbiter-smtp", package_file=__file__)
-    core_api_version = CORE_API_VERSION
+    server_api_version = SERVER_API_VERSION
 
     def register_configs(self, config_store: ConfigStore) -> None:
         register_smtp_configs(config_store)
@@ -621,6 +1034,13 @@ class SMTPServicePlugin:
             policies=policies,
             smtp_client_factory=smtp_client_factory,
             time_provider=time_provider,
+            plugin_storage=cast(
+                PluginStorage | None, context.dependencies.get("plugin_storage")
+            ),
+            sent_message_appender=cast(
+                SentMessageAppender | None,
+                context.dependencies.get("sent_message_appender"),
+            ),
         )
 
     def describe_capability(
@@ -668,6 +1088,7 @@ class SMTPServicePlugin:
             "ok": True,
             "message_id": result.message_id,
             "recipient_count": result.recipient_count,
+            "sent_copy": result.sent_copy,
             "idempotency_replayed": result.idempotency_replayed,
         }
 

arbiter_smtp-0.9.1.dev2/src/arbiter_smtp/client.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import smtplib
+import ssl
+
+from .config import MailTlsMode, SMTPConfig
+
+
+class SMTPSubmissionClient:
+    def __init__(self, config: SMTPConfig) -> None:
+        self._config = config
+
+    def test_connection(self) -> None:
+        with self._connect() as server:
+            self._prepare_session(server)
+            self._expect_ok(server.noop(), "NOOP")
+
+    def send(self, message_bytes: bytes, sender: str, recipients: list[str]) -> None:
+        with self._connect() as server:
+            self._prepare_session(server)
+            refused_recipients = server.sendmail(sender, recipients, message_bytes)
+            if refused_recipients:
+                raise smtplib.SMTPRecipientsRefused(refused_recipients)
+
+    def _connect(self) -> smtplib.SMTP | smtplib.SMTP_SSL:
+        ssl_context = self._build_ssl_context()
+        if self._config.tls == MailTlsMode.implicit:
+            return smtplib.SMTP_SSL(
+                self._config.host,
+                self._config.port,
+                timeout=self._config.timeout_seconds,
+                context=ssl_context,
+            )
+        return smtplib.SMTP(
+            self._config.host,
+            self._config.port,
+            timeout=self._config.timeout_seconds,
+        )
+
+    def _prepare_session(self, server: smtplib.SMTP | smtplib.SMTP_SSL) -> None:
+        ssl_context = self._build_ssl_context()
+        self._expect_ok(server.ehlo(), "EHLO")
+        if self._config.tls == MailTlsMode.starttls:
+            self._expect_ok(server.starttls(context=ssl_context), "STARTTLS")
+            self._expect_ok(server.ehlo(), "EHLO")
+
+        if self._config.authenticate:
+            self._expect_ok(
+                server.login(self._config.username, self._config.password), "login"
+            )
+
+    def _expect_ok(self, response: tuple[int, bytes], action: str) -> None:
+        code, message = response
+        if code < 200 or code >= 400:
+            raise smtplib.SMTPResponseException(
+                code, f"SMTP {action} failed: {message!r}"
+            )
+
+    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

{arbiter_smtp-0.9.0.dev1/src/agent_arbiter_smtp → arbiter_smtp-0.9.1.dev2/src/arbiter_smtp}/config.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from enum import Enum
 
-from agent_arbiter.config import Policy
+from arbiter_server.config import Policy
 from hydra.core.config_store import ConfigStore
 
 
@@ -13,6 +13,11 @@ class MailTlsMode(str, Enum):
     implicit = "implicit"
 
 
+class SMTPSentCopyFailureMode(str, Enum):
+    warn = "warn"
+    fail = "fail"
+
+
 @dataclass
 class SMTPLimitsConfig:
     max_messages_per_minute: int | None = None
@@ -22,7 +27,7 @@ class SMTPLimitsConfig:
 @dataclass
 class SMTPIdempotencyConfig:
     expiration_days: int = 7
-    cache_dir: str = ".arbiter/smtp-idempotency"
+    cache_dir: str | None = None
 
 
 @dataclass
@@ -33,10 +38,22 @@ class SMTPRecipientPolicyConfig:
     blocked_domain_patterns: list[str] = field(default_factory=list)
 
 
+@dataclass
+class SMTPSentCopyAccountConfig:
+    folder: str | None = None
+
+
+@dataclass
+class SMTPSentCopyPolicyConfig:
+    enabled: bool = True
+    on_failure: SMTPSentCopyFailureMode = SMTPSentCopyFailureMode.warn
+
+
 @dataclass
 class SMTPConfig(Policy):
     policy: str = "bot"
     description: str = ""
+    guidance: str = ""
     host: str = "localhost"
     port: int = 587
     authenticate: bool = False
@@ -47,6 +64,9 @@ class SMTPConfig(Policy):
     tls: MailTlsMode = MailTlsMode.starttls
     verify_peer: bool = True
     timeout_seconds: float = 30.0
+    sent_copy: SMTPSentCopyAccountConfig = field(
+        default_factory=SMTPSentCopyAccountConfig
+    )
 
 
 @dataclass
@@ -57,6 +77,9 @@ class SMTPServicePolicyConfig(Policy):
     recipient_policy: SMTPRecipientPolicyConfig = field(
         default_factory=SMTPRecipientPolicyConfig
     )
+    sent_copy: SMTPSentCopyPolicyConfig = field(
+        default_factory=SMTPSentCopyPolicyConfig
+    )
 
 
 SMTP_ACCOUNT_EXAMPLE = SMTPConfig(

{arbiter_smtp-0.9.0.dev1/src/agent_arbiter_smtp → arbiter_smtp-0.9.1.dev2/src/arbiter_smtp}/idempotency.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import base64
+import binascii
 from dataclasses import dataclass
 import json
 from pathlib import Path
@@ -11,6 +13,8 @@ from diskcache import Cache  # type: ignore[import-untyped]
 class SMTPIdempotencyResult:
     message_id: str
     recipient_count: int
+    sent_copy: dict[str, object] | None = None
+    sent_copy_message_bytes: bytes | None = None
 
 
 @dataclass(frozen=True)
@@ -66,6 +70,14 @@ def _encode_record(record: SMTPIdempotencyRecord) -> str:
                 else {
                     "message_id": record.result.message_id,
                     "recipient_count": record.result.recipient_count,
+                    "sent_copy": record.result.sent_copy,
+                    "sent_copy_message": (
+                        None
+                        if record.result.sent_copy_message_bytes is None
+                        else base64.b64encode(
+                            record.result.sent_copy_message_bytes
+                        ).decode("ascii")
+                    ),
                 }
             ),
         },
@@ -90,12 +102,31 @@ def _decode_record(raw_record: str) -> SMTPIdempotencyRecord:
         raise ValueError("SMTP idempotency cache contains an invalid result")
     message_id = raw_result.get("message_id")
     recipient_count = raw_result.get("recipient_count")
+    sent_copy = raw_result.get("sent_copy")
+    sent_copy_message = raw_result.get("sent_copy_message")
     if not isinstance(message_id, str) or not isinstance(recipient_count, int):
         raise ValueError("SMTP idempotency cache contains an invalid result")
+    if sent_copy is not None and not isinstance(sent_copy, dict):
+        raise ValueError("SMTP idempotency cache contains an invalid sent_copy result")
+    if sent_copy_message is not None and not isinstance(sent_copy_message, str):
+        raise ValueError("SMTP idempotency cache contains an invalid sent_copy message")
+    sent_copy_message_bytes: bytes | None = None
+    if sent_copy_message is not None:
+        try:
+            sent_copy_message_bytes = base64.b64decode(
+                sent_copy_message,
+                validate=True,
+            )
+        except (binascii.Error, ValueError) as exc:
+            raise ValueError(
+                "SMTP idempotency cache contains an invalid sent_copy message"
+            ) from exc
     return SMTPIdempotencyRecord(
         payload_hash=payload_hash,
         result=SMTPIdempotencyResult(
             message_id=message_id,
             recipient_count=recipient_count,
+            sent_copy=sent_copy,
+            sent_copy_message_bytes=sent_copy_message_bytes,
         ),
     )

{arbiter_smtp-0.9.0.dev1 → arbiter_smtp-0.9.1.dev2}/src/arbiter_smtp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arbiter-smtp
-Version: 0.9.0.dev1
+Version: 0.9.1.dev2
 Summary: SMTP service plugin for Arbiter
 Author-email: Omry Yadan <omry@yadan.net>
 Maintainer-email: Omry Yadan <omry@yadan.net>
@@ -20,7 +20,7 @@ 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
+Requires-Dist: arbiter-server<0.10.0,>=0.9.1.dev2
 Requires-Dist: diskcache<6.0,>=5.6
 
 SMTP service plugin for Arbiter.

{arbiter_smtp-0.9.0.dev1 → arbiter_smtp-0.9.1.dev2}/src/arbiter_smtp.egg-info/SOURCES.txt

@@ -1,9 +1,9 @@
 pyproject.toml
-src/agent_arbiter_smtp/__init__.py
-src/agent_arbiter_smtp/client.py
-src/agent_arbiter_smtp/config.py
-src/agent_arbiter_smtp/idempotency.py
-src/agent_arbiter_smtp/py.typed
+src/arbiter_smtp/__init__.py
+src/arbiter_smtp/client.py
+src/arbiter_smtp/config.py
+src/arbiter_smtp/idempotency.py
+src/arbiter_smtp/py.typed
 src/arbiter_smtp.egg-info/PKG-INFO
 src/arbiter_smtp.egg-info/SOURCES.txt
 src/arbiter_smtp.egg-info/dependency_links.txt

arbiter_smtp-0.9.1.dev2/src/arbiter_smtp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[arbiter.services]
+smtp = arbiter_smtp:plugin

arbiter_smtp-0.9.1.dev2/src/arbiter_smtp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+arbiter-server<0.10.0,>=0.9.1.dev2
+diskcache<6.0,>=5.6

arbiter_smtp-0.9.1.dev2/src/arbiter_smtp.egg-info/top_level.txt

@@ -0,0 +1 @@
+arbiter_smtp

arbiter_smtp-0.9.0.dev1/src/agent_arbiter_smtp/client.py

@@ -1,55 +0,0 @@
-from __future__ import annotations
-
-from email.message import EmailMessage
-import smtplib
-import ssl
-
-from .config import MailTlsMode, SMTPConfig
-
-
-class SMTPSubmissionClient:
-    def __init__(self, config: SMTPConfig) -> None:
-        self._config = config
-
-    def send(self, message: EmailMessage, sender: str, recipients: list[str]) -> None:
-        ssl_context = self._build_ssl_context()
-        smtp_client: smtplib.SMTP | smtplib.SMTP_SSL
-        if self._config.tls == MailTlsMode.implicit:
-            smtp_client = smtplib.SMTP_SSL(
-                self._config.host,
-                self._config.port,
-                timeout=self._config.timeout_seconds,
-                context=ssl_context,
-            )
-        else:
-            smtp_client = smtplib.SMTP(
-                self._config.host,
-                self._config.port,
-                timeout=self._config.timeout_seconds,
-            )
-
-        with smtp_client as server:
-            server.ehlo()
-            if self._config.tls == MailTlsMode.starttls:
-                server.starttls(context=ssl_context)
-                server.ehlo()
-
-            if self._config.authenticate:
-                server.login(self._config.username, self._config.password)
-
-            refused_recipients = server.send_message(
-                message,
-                from_addr=sender,
-                to_addrs=recipients,
-            )
-            if refused_recipients:
-                raise smtplib.SMTPRecipientsRefused(refused_recipients)
-
-    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

arbiter_smtp-0.9.0.dev1/src/arbiter_smtp.egg-info/entry_points.txt

@@ -1,2 +0,0 @@
-[agent_arbiter.services]
-smtp = agent_arbiter_smtp:plugin

arbiter_smtp-0.9.0.dev1/src/arbiter_smtp.egg-info/requires.txt

@@ -1,2 +0,0 @@
-arbiter-core<0.10.0,>=0.9.0.dev1
-diskcache<6.0,>=5.6

arbiter_smtp-0.9.0.dev1/src/arbiter_smtp.egg-info/top_level.txt

@@ -1 +0,0 @@
-agent_arbiter_smtp