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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arbiter-imap
-Version: 0.9.0.dev1
+Version: 0.9.1.dev2
 Summary: IMAP service plugin for Arbiter
 Author-email: Omry Yadan <omry@yadan.net>
 Maintainer-email: Omry Yadan <omry@yadan.net>
@@ -20,6 +20,6 @@ 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
 
 IMAP service plugin for Arbiter.

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

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

{arbiter_imap-0.9.0.dev1/src/agent_arbiter_imap → arbiter_imap-0.9.1.dev2/src/arbiter_imap}/__init__.py

@@ -1,37 +1,50 @@
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
 from typing import Callable, Protocol, cast
 
 from hydra.core.config_store import ConfigStore
 
-from agent_arbiter.services import (
+from arbiter_server.artifacts import PluginArtifactStore
+from arbiter_server.services import (
     CapabilityDescriptor,
     OperationDescriptor,
     ServicePluginContext,
     ServiceRuntimeContext,
 )
-from agent_arbiter.version import distribution_version
+from arbiter_server.version import distribution_version
 
 from .config import (
     IMAPAccessPolicyConfig,
     IMAPConfig,
     IMAPFlagMode,
+    IMAPFolderConfig,
     register_configs as register_imap_configs,
     resolve_imap_flag_mode,
     resolve_system_flag_key,
 )
 
-from .client import FetchedIMAPMessage
+from .client import FetchedIMAPMessage, IMAPAttachmentContent
 
-CORE_API_VERSION = "0.9"
+SERVER_API_VERSION = "0.9"
 
 
 class IMAPClientProtocol(Protocol):
+    def test_connection(self, *, folders: Sequence[str]) -> None: ...
+
     def list_messages(self, *, folder: str, limit: int) -> list[FetchedIMAPMessage]: ...
 
     def get_message(self, *, folder: str, uid: str) -> FetchedIMAPMessage: ...
 
+    def get_attachment(
+        self,
+        *,
+        folder: str,
+        uid: str,
+        attachment_id: str,
+    ) -> IMAPAttachmentContent: ...
+
     def search_messages(
         self,
         *,
@@ -52,6 +65,14 @@ class IMAPClientProtocol(Protocol):
 
     def delete_message(self, *, folder: str, uid: str) -> None: ...
 
+    def append_message(
+        self,
+        *,
+        folder: str,
+        message_bytes: bytes,
+        flags: Sequence[str] = (r"\Seen",),
+    ) -> None: ...
+
 
 IMAPClientFactory = Callable[[IMAPConfig], IMAPClientProtocol]
 
@@ -76,18 +97,57 @@ FOLDER_PROPERTY = {
     "type": "string",
     "description": "Configured IMAP folder name. Defaults to the account default folder.",
 }
+ROOT_FOLDER_PROPERTY = {
+    "type": "string",
+    "description": (
+        "Optional configured folder prefix to browse or search beneath. "
+        "Omit to start at the account root."
+    ),
+}
+FOLDER_LIMIT_PROPERTY = {
+    "type": "integer",
+    "minimum": 1,
+    "maximum": 100,
+    "description": (
+        "Maximum number of folders to return. Results include truncated=true "
+        "when more folders match."
+    ),
+}
+RECURSIVE_PROPERTY = {
+    "type": "boolean",
+    "description": "Whether to include all configured descendants under root.",
+}
 MESSAGE_ID_PROPERTY = {
     "type": "string",
     "description": "IMAP UID scoped to the selected account and folder.",
 }
+ATTACHMENT_ID_PROPERTY = {
+    "type": "string",
+    "description": "Attachment MIME-part id returned by imap:get_message.",
+}
 LIMIT_PROPERTY = {
     "type": "integer",
     "minimum": 1,
     "maximum": 100,
     "description": "Maximum number of messages to return.",
 }
-
 IMAP_OPERATION_DESCRIPTORS = (
+    OperationDescriptor(
+        name="list_folders",
+        description=(
+            "List configured IMAP folders for the selected account, optionally "
+            "beneath a folder prefix."
+        ),
+        input_schema=_object_schema(
+            {
+                "account": ACCOUNT_PROPERTY,
+                "root": ROOT_FOLDER_PROPERTY,
+                "recursive": RECURSIVE_PROPERTY,
+                "limit": FOLDER_LIMIT_PROPERTY,
+            },
+            ["account"],
+        ),
+    ),
     OperationDescriptor(
         name="list_messages",
         description=(
@@ -118,6 +178,24 @@ IMAP_OPERATION_DESCRIPTORS = (
             ["account", "message_id"],
         ),
     ),
+    OperationDescriptor(
+        name="get_attachment",
+        description=(
+            "Create a one-time server artifact URL for one attachment by message "
+            "UID and attachment id. The attachment bytes are not returned in the "
+            "tool result. Use local file save only when the user explicitly asks "
+            "to save the attachment."
+        ),
+        input_schema=_object_schema(
+            {
+                "account": ACCOUNT_PROPERTY,
+                "message_id": MESSAGE_ID_PROPERTY,
+                "attachment_id": ATTACHMENT_ID_PROPERTY,
+                "folder": FOLDER_PROPERTY,
+            },
+            ["account", "message_id", "attachment_id"],
+        ),
+    ),
     OperationDescriptor(
         name="search_messages",
         description=(
@@ -171,6 +249,26 @@ IMAP_OPERATION_DESCRIPTORS = (
             ["account", "message_id"],
         ),
     ),
+    OperationDescriptor(
+        name="search_folders",
+        description=(
+            "Search configured IMAP folders for the selected account by folder "
+            "name, description, or kind."
+        ),
+        input_schema=_object_schema(
+            {
+                "account": ACCOUNT_PROPERTY,
+                "query": {
+                    "type": "string",
+                    "description": "Text to match against configured folder metadata.",
+                },
+                "root": ROOT_FOLDER_PROPERTY,
+                "recursive": RECURSIVE_PROPERTY,
+                "limit": FOLDER_LIMIT_PROPERTY,
+            },
+            ["account", "query"],
+        ),
+    ),
     OperationDescriptor(
         name="delete_message",
         description=(
@@ -189,6 +287,12 @@ IMAP_OPERATION_DESCRIPTORS = (
 )
 
 
+@dataclass(frozen=True)
+class _FolderItems:
+    items: list[dict[str, object]]
+    truncated: bool
+
+
 class IMAPRuntime:
     service_name = "imap"
 
@@ -197,6 +301,7 @@ class IMAPRuntime:
         accounts: Mapping[str, object],
         policies: Mapping[str, object],
         imap_client_factory: IMAPClientFactory | None = None,
+        artifact_store: PluginArtifactStore | None = None,
     ) -> None:
         self._accounts = cast(Mapping[str, IMAPConfig], accounts)
         self._policies = cast(
@@ -204,6 +309,7 @@ class IMAPRuntime:
             policies,
         )
         self._imap_client_factory = imap_client_factory
+        self._artifact_store = artifact_store
         self._validate_policy_references()
 
     def account_summaries(self) -> dict[str, object]:
@@ -212,6 +318,7 @@ class IMAPRuntime:
             imap_policy = self._policies[account.policy]
             summaries[account_name] = {
                 "description": account.description,
+                "guidance": account.guidance,
                 "policy": account.policy,
                 "enabled": True,
                 "confirmation_required": [
@@ -221,6 +328,37 @@ class IMAPRuntime:
             }
         return summaries
 
+    def test_accounts(self) -> dict[str, object]:
+        results: dict[str, object] = {}
+        for account_name, imap_config in sorted(self._accounts.items()):
+            folders = self._test_folders(imap_config)
+            try:
+                self._make_client(imap_config).test_connection(folders=folders)
+            except Exception as exc:
+                results[account_name] = {
+                    "status": "failed",
+                    "stage": "connect_auth_noop_examine",
+                    "folders": folders,
+                    "error_type": type(exc).__name__,
+                    "message": str(exc),
+                }
+                continue
+            if not folders:
+                results[account_name] = {
+                    "status": "skipped",
+                    "stage": "connect_auth_noop",
+                    "checks": ["connect", "noop"],
+                    "reason": "no configured IMAP folders to examine read-only",
+                }
+                continue
+            results[account_name] = {
+                "status": "ok",
+                "stage": "connect_auth_noop_examine",
+                "checks": ["connect", "noop", "examine"],
+                "folders": folders,
+            }
+        return results
+
     def list_messages(
         self,
         account: str,
@@ -247,6 +385,31 @@ class IMAPRuntime:
             ],
         }
 
+    def list_folders(
+        self,
+        account: str,
+        root: str | None = None,
+        recursive: bool = False,
+        limit: int = 50,
+    ) -> dict[str, object]:
+        imap_config = self._resolve_account_config("list_folders", account)
+        normalized_root = self._normalize_folder_root(root)
+        normalized_limit = self._normalize_folder_limit(limit)
+        folder_items = self._folder_items(
+            imap_config,
+            root=normalized_root,
+            recursive=recursive,
+            limit=normalized_limit,
+        )
+        return {
+            "account": account,
+            "root": normalized_root,
+            "recursive": recursive,
+            "limit": normalized_limit,
+            "truncated": folder_items.truncated,
+            "folders": folder_items.items,
+        }
+
     def get_message(
         self,
         account: str,
@@ -274,6 +437,88 @@ class IMAPRuntime:
             ),
         }
 
+    def get_attachment(
+        self,
+        account: str,
+        message_id: str,
+        attachment_id: str,
+        folder: str | None = None,
+    ) -> dict[str, object]:
+        imap_config, imap_policy, folder_name = self._resolve_context(
+            "get_attachment", account, folder
+        )
+        if not imap_policy.allow_read:
+            raise ValueError(f"get_attachment is not allowed for account: {account}")
+        if self._artifact_store is None:
+            raise ValueError(
+                "get_attachment requires server artifact storage; "
+                "HTTP artifact delivery is unavailable"
+            )
+
+        uid = self._normalize_message_uid(message_id)
+        normalized_attachment_id = self._normalize_attachment_id(attachment_id)
+        attachment_content = self._make_client(imap_config).get_attachment(
+            folder=folder_name,
+            uid=uid,
+            attachment_id=normalized_attachment_id,
+        )
+        attachment = attachment_content.attachment
+        artifact = self._artifact_store.create(
+            content=attachment_content.content,
+            filename=attachment.filename,
+            content_type=attachment.content_type,
+            source={
+                "account": account,
+                "folder": folder_name,
+                "message_id": uid,
+                "attachment_id": attachment.id,
+            },
+        )
+        return {
+            "account": account,
+            "folder": folder_name,
+            "message_id": uid,
+            "attachment": {
+                "id": attachment.id,
+                "filename": attachment.filename,
+                "content_type": attachment.content_type,
+                "size": attachment.size,
+                "disposition": attachment.disposition,
+                "content_id": attachment.content_id,
+                "inline": attachment.inline,
+            },
+            "delivery": "arbiter_artifact",
+            "artifact": {
+                **artifact.to_dict(),
+                "handling": {
+                    "prefer_inline": False,
+                    "execute_locally": True,
+                    "requires_explicit_user_request": True,
+                    "path_interface": (
+                        "arbiter artifact with-temp <url> -- <argv...{}...>"
+                    ),
+                    "stdin_interface": "arbiter artifact with-stdin <url> -- <argv...>",
+                    "save_interface": "arbiter artifact save <url> <path>",
+                    "save_requires_explicit_user_request": True,
+                    "instructions": (
+                        "Use the one-time URL only through an explicit artifact "
+                        "reader such as `arbiter artifact get --stdout` for small "
+                        "textual attachments. For binary attachments, prefer "
+                        "`arbiter artifact with-temp <url> -- <argv...{}...>` "
+                        "for path-based tools or "
+                        "`arbiter artifact with-stdin <url> -- <argv...>` for "
+                        "stdin-based tools. If the user explicitly asks to save "
+                        "the attachment, use "
+                        "`arbiter artifact save <url> <path>`. Do not "
+                        "otherwise save, copy, or persist the file."
+                    ),
+                },
+            },
+        }
+
+    def artifact_delivery_available(self) -> bool:
+        return self._artifact_store is not None
+
     def search_messages(
         self,
         account: str,
@@ -307,6 +552,38 @@ class IMAPRuntime:
             ],
         }
 
+    def search_folders(
+        self,
+        account: str,
+        query: str,
+        root: str | None = None,
+        recursive: bool = True,
+        limit: int = 20,
+    ) -> dict[str, object]:
+        imap_config = self._resolve_account_config("search_folders", account)
+        normalized_query = query.strip()
+        if not normalized_query:
+            raise ValueError("search_folders requires a non-empty query")
+        normalized_root = self._normalize_folder_root(root)
+        normalized_limit = self._normalize_folder_limit(limit)
+        query_text = normalized_query.casefold()
+        folder_items = self._folder_items(
+            imap_config,
+            root=normalized_root,
+            recursive=recursive,
+            limit=normalized_limit,
+            query=query_text,
+        )
+        return {
+            "account": account,
+            "query": normalized_query,
+            "root": normalized_root,
+            "recursive": recursive,
+            "limit": normalized_limit,
+            "truncated": folder_items.truncated,
+            "folders": folder_items.items,
+        }
+
     def move_message(
         self,
         account: str,
@@ -390,18 +667,32 @@ class IMAPRuntime:
             "message_id": uid,
         }
 
+    def append_sent_message(
+        self,
+        *,
+        account: str,
+        folder: str,
+        message_bytes: bytes,
+    ) -> None:
+        imap_config = self._resolve_account_config("append_sent_message", account)
+        folder_name = self._resolve_folder(
+            "append_sent_message",
+            imap_config,
+            folder,
+        )
+        self._make_client(imap_config).append_message(
+            folder=folder_name,
+            message_bytes=message_bytes,
+            flags=(r"\Seen",),
+        )
+
     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}"
-            )
-
+        imap_config = self._resolve_account_config(tool_name, 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:
@@ -410,6 +701,14 @@ class IMAPRuntime:
             )
         return imap_config, imap_policy, folder_name
 
+    def _resolve_account_config(self, tool_name: str, account_name: str) -> IMAPConfig:
+        imap_config = self._accounts.get(account_name)
+        if imap_config is None:
+            raise ValueError(
+                f"{tool_name} requires an IMAP-enabled account: {account_name}"
+            )
+        return imap_config
+
     def _validate_policy_references(self) -> None:
         for account_name, imap_config in sorted(self._accounts.items()):
             if imap_config.policy not in self._policies:
@@ -449,6 +748,12 @@ class IMAPRuntime:
             raise RuntimeError("IMAP client factory is not configured")
         return self._imap_client_factory(imap_config)
 
+    def _test_folders(self, imap_config: IMAPConfig) -> list[str]:
+        folders = sorted(imap_config.folders)
+        if imap_config.default_folder and imap_config.default_folder not in folders:
+            folders.append(imap_config.default_folder)
+        return folders
+
     def _message_summary(
         self,
         imap_policy: IMAPAccessPolicyConfig,
@@ -493,6 +798,87 @@ class IMAPRuntime:
             raise ValueError("IMAP message limit must be at most 100")
         return limit
 
+    def _normalize_folder_limit(self, limit: int) -> int:
+        if limit < 1:
+            raise ValueError("IMAP folder limit must be at least 1")
+        if limit > 100:
+            raise ValueError("IMAP folder limit must be at most 100")
+        return limit
+
+    def _normalize_folder_root(self, root: str | None) -> str | None:
+        if root is None:
+            return None
+        normalized = root.strip().strip("/")
+        return normalized or None
+
+    def _folder_items(
+        self,
+        imap_config: IMAPConfig,
+        *,
+        root: str | None,
+        recursive: bool,
+        limit: int,
+        query: str | None = None,
+    ) -> _FolderItems:
+        items: list[dict[str, object]] = []
+        for folder_name, folder_config in sorted(imap_config.folders.items()):
+            if not self._folder_matches_root(folder_name, root, recursive=recursive):
+                continue
+            item = self._folder_to_dict(
+                folder_name,
+                folder_config,
+                default_folder=imap_config.default_folder,
+            )
+            if query is not None and not self._folder_matches_query(item, query):
+                continue
+            items.append(item)
+            if len(items) > limit:
+                return _FolderItems(items=items[:limit], truncated=True)
+        return _FolderItems(items=items, truncated=False)
+
+    def _folder_matches_root(
+        self,
+        folder_name: str,
+        root: str | None,
+        *,
+        recursive: bool,
+    ) -> bool:
+        if root is None:
+            relative = folder_name
+        elif folder_name == root:
+            return False
+        elif folder_name.startswith(f"{root}/"):
+            relative = folder_name[len(root) + 1 :]
+        else:
+            return False
+        if recursive:
+            return True
+        return "/" not in relative
+
+    def _folder_to_dict(
+        self,
+        folder_name: str,
+        folder_config: IMAPFolderConfig,
+        *,
+        default_folder: str | None,
+    ) -> dict[str, object]:
+        return {
+            "name": folder_name,
+            "description": folder_config.description,
+            "kind": (
+                folder_config.kind.value if folder_config.kind is not None else None
+            ),
+            "default": folder_name == default_folder,
+        }
+
+    def _folder_matches_query(self, folder: dict[str, object], query: str) -> bool:
+        searchable = [
+            cast(str, folder["name"]),
+            cast(str, folder["description"]),
+            cast(str | None, folder["kind"]) or "",
+        ]
+        return any(query in value.casefold() for value in searchable)
+
     def _normalize_message_uid(self, message_id: str) -> str:
         uid = message_id.strip()
         if not uid:
@@ -501,6 +887,12 @@ class IMAPRuntime:
             raise ValueError("IMAP message_id must be an IMAP UID")
         return uid
 
+    def _normalize_attachment_id(self, attachment_id: str) -> str:
+        normalized = attachment_id.strip()
+        if not normalized:
+            raise ValueError("IMAP attachment_id must be non-empty")
+        return normalized
+
     def _message_to_dict(
         self,
         message: FetchedIMAPMessage,
@@ -525,6 +917,18 @@ class IMAPRuntime:
         if include_body:
             message_dict["text_body"] = message.text_body
             message_dict["html_body"] = message.html_body
+            message_dict["attachments"] = [
+                {
+                    "id": attachment.id,
+                    "filename": attachment.filename,
+                    "content_type": attachment.content_type,
+                    "size": attachment.size,
+                    "disposition": attachment.disposition,
+                    "content_id": attachment.content_id,
+                    "inline": attachment.inline,
+                }
+                for attachment in message.attachments
+            ]
         return message_dict
 
     def _visible_flags(
@@ -541,15 +945,96 @@ class IMAPRuntime:
         return visible_flags
 
 
+def _imap_account_bootstrap_template(
+    *,
+    name: str,
+    policy_name: str,
+    env_suffix: str,
+) -> str:
+    return f"""# @package arbiter.account.imap.{name}
+defaults:
+  # Extend the plugin-owned structured schema, then override values below.
+  - schema@_here_
+  - _self_
+
+# Human-facing summary shown by account listing tools.
+description: IMAP account for (${{.username}})
+
+# Operator guidance shown to agents during discovery.
+guidance: ""
+
+# Matching policy generated alongside this account.
+policy: {policy_name}
+
+# IMAP mailbox endpoint.
+host: imap.example.com
+port: 993
+
+# Credentials are read from the Arbiter process environment.
+username: ${{oc.env:IMAP_{env_suffix}_USERNAME}}
+password: ${{oc.env:IMAP_{env_suffix}_PASSWORD}}
+
+# TLS mode: implicit, starttls, or none.
+tls: implicit
+verify_peer: true
+timeout_seconds: 30
+
+# Default mailbox folder for tools that accept an optional folder.
+default_folder: INBOX
+folders:
+  INBOX:
+    description: Primary inbox.
+    # Optional folder kind: all, archive, drafts, flagged, junk, sent, or trash.
+    # These map to IMAP special-use mailbox attributes.
+    kind:
+"""
+
+
+def _imap_policy_bootstrap_template(*, name: str) -> str:
+    return f"""# @package arbiter.policy.imap.{name}
+defaults:
+  # Extend the plugin-owned structured schema, then override values below.
+  - schema@_here_
+  - _self_
+
+# Read/search are enabled by default; mutating mailbox actions are disabled.
+allow_read: true
+allow_search: true
+allow_move: false
+allow_delete: false
+confirmation_required: []
+
+# System flags remain visible but read-only unless deliberately opened up.
+system_flags:
+  seen: read_only
+  flagged: read_only
+  answered: read_only
+  deleted: read_only
+  draft: read_only
+user_flags: {{}}
+"""
+
+
 class IMAPServicePlugin:
     name = "imap"
     version = distribution_version("arbiter-imap", package_file=__file__)
-    core_api_version = CORE_API_VERSION
+    server_api_version = SERVER_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:
+        if kind == "account":
+            env_suffix = name.upper().replace("-", "_")
+            if not env_suffix.endswith("_ACCOUNT"):
+                env_suffix = f"{env_suffix}_ACCOUNT"
+            return _imap_account_bootstrap_template(
+                name=name,
+                policy_name=f"{name}_policy",
+                env_suffix=env_suffix,
+            )
+        if kind == "policy":
+            return _imap_policy_bootstrap_template(name=name)
         return None
 
     def build_runtime(
@@ -564,10 +1049,15 @@ class IMAPServicePlugin:
             IMAPClientFactory,
             context.dependencies.get("imap_client_factory", IMAPClient),
         )
+        artifact_store = cast(
+            PluginArtifactStore | None,
+            context.dependencies.get("artifact_store"),
+        )
         return IMAPRuntime(
             accounts=accounts,
             policies=policies,
             imap_client_factory=imap_client_factory,
+            artifact_store=artifact_store,
         )
 
     def describe_capability(
@@ -583,7 +1073,14 @@ class IMAPServicePlugin:
         self,
         context: ServicePluginContext,
     ) -> tuple[OperationDescriptor, ...]:
-        return IMAP_OPERATION_DESCRIPTORS
+        runtime = context.runtimes.require(self.name, IMAPRuntime)
+        if runtime.artifact_delivery_available():
+            return IMAP_OPERATION_DESCRIPTORS
+        return tuple(
+            descriptor
+            for descriptor in IMAP_OPERATION_DESCRIPTORS
+            if descriptor.name != "get_attachment"
+        )
 
     def invoke_operation(
         self,
@@ -598,12 +1095,26 @@ class IMAPServicePlugin:
                 folder=cast(str | None, arguments.get("folder")),
                 limit=cast(int, arguments.get("limit", 20)),
             )
+        if operation == "list_folders":
+            return runtime.list_folders(
+                account=cast(str, arguments.get("account")),
+                root=cast(str | None, arguments.get("root")),
+                recursive=cast(bool, arguments.get("recursive", False)),
+                limit=cast(int, arguments.get("limit", 50)),
+            )
         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 == "get_attachment":
+            return runtime.get_attachment(
+                account=cast(str, arguments.get("account")),
+                message_id=cast(str, arguments.get("message_id")),
+                attachment_id=cast(str, arguments.get("attachment_id")),
+                folder=cast(str | None, arguments.get("folder")),
+            )
         if operation == "search_messages":
             return runtime.search_messages(
                 account=cast(str, arguments.get("account")),
@@ -611,6 +1122,14 @@ class IMAPServicePlugin:
                 folder=cast(str | None, arguments.get("folder")),
                 limit=cast(int, arguments.get("limit", 20)),
             )
+        if operation == "search_folders":
+            return runtime.search_folders(
+                account=cast(str, arguments.get("account")),
+                query=cast(str, arguments.get("query")),
+                root=cast(str | None, arguments.get("root")),
+                recursive=cast(bool, arguments.get("recursive", True)),
+                limit=cast(int, arguments.get("limit", 20)),
+            )
         if operation == "move_message":
             return runtime.move_message(
                 account=cast(str, arguments.get("account")),

{arbiter_imap-0.9.0.dev1/src/agent_arbiter_imap → arbiter_imap-0.9.1.dev2/src/arbiter_imap}/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from collections.abc import Sequence
 from email import policy
 from email.message import EmailMessage
 from email.parser import BytesParser
@@ -8,11 +9,28 @@ from email.utils import formataddr, getaddresses
 import imaplib
 import re
 import ssl
-from typing import Any
+from typing import Any, cast
 
 from .config import IMAPConfig, MailTlsMode
 
 
+@dataclass(frozen=True)
+class IMAPAttachment:
+    id: str
+    filename: str | None
+    content_type: str
+    size: int
+    disposition: str | None
+    content_id: str | None
+    inline: bool
+
+
+@dataclass(frozen=True)
+class IMAPAttachmentContent:
+    attachment: IMAPAttachment
+    content: bytes
+
+
 @dataclass(frozen=True)
 class FetchedIMAPMessage:
     uid: str
@@ -26,6 +44,7 @@ class FetchedIMAPMessage:
     text_body: str | None
     html_body: str | None
     snippet: str
+    attachments: list[IMAPAttachment] = field(default_factory=list)
 
 
 class IMAPOperationError(RuntimeError):
@@ -36,6 +55,13 @@ class IMAPClient:
     def __init__(self, config: IMAPConfig) -> None:
         self._config = config
 
+    def test_connection(self, *, folders: Sequence[str]) -> None:
+        with self._session() as server:
+            status, data = server.noop()
+            self._expect_ok(status, data, "NOOP")
+            for folder in folders:
+                self._select_folder(server, folder, readonly=True)
+
     def list_messages(self, *, folder: str, limit: int) -> list[FetchedIMAPMessage]:
         with self._session() as server:
             self._select_folder(server, folder, readonly=True)
@@ -48,6 +74,22 @@ class IMAPClient:
             self._select_folder(server, folder, readonly=True)
             return self._fetch_message(server, uid)
 
+    def get_attachment(
+        self,
+        *,
+        folder: str,
+        uid: str,
+        attachment_id: str,
+    ) -> IMAPAttachmentContent:
+        with self._session() as server:
+            self._select_folder(server, folder, readonly=True)
+            message_bytes = self._fetch_message_bytes(server, uid)
+        email_message = BytesParser(policy=policy.default).parsebytes(message_bytes)
+        return self._extract_attachment_content(
+            email_message,
+            attachment_id=attachment_id,
+        )
+
     def search_messages(
         self, *, folder: str, query: str, limit: int
     ) -> list[FetchedIMAPMessage]:
@@ -84,6 +126,20 @@ class IMAPClient:
             self._mark_deleted(server, uid)
             self._expunge_uid(server, uid, "expunge deleted message")
 
+    def append_message(
+        self,
+        *,
+        folder: str,
+        message_bytes: bytes,
+        flags: Sequence[str] = (r"\Seen",),
+    ) -> None:
+        with self._session() as server:
+            date_time: Any = None
+            status, data = server.append(
+                folder, f"({' '.join(flags)})", date_time, message_bytes
+            )
+            self._expect_ok(status, cast(list[Any], data), "append message")
+
     def _session(self) -> IMAPSession:
         return IMAPSession(self._connect())
 
@@ -155,6 +211,7 @@ class IMAPClient:
         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)
+        attachments = self._extract_attachments(email_message)
         snippet = self._snippet_from_body(text_body or html_body or "")
         return FetchedIMAPMessage(
             uid=uid,
@@ -168,6 +225,7 @@ class IMAPClient:
             text_body=text_body,
             html_body=html_body,
             snippet=snippet,
+            attachments=attachments,
         )
 
     def _fetch_flags(
@@ -320,6 +378,79 @@ class IMAPClient:
             )
         return str(content)
 
+    def _extract_attachments(self, message: EmailMessage) -> list[IMAPAttachment]:
+        attachments: list[IMAPAttachment] = []
+        for index, part in enumerate(self._iter_leaf_parts(message), start=1):
+            attachment = self._attachment_metadata(part, index)
+            if attachment is None:
+                continue
+            attachments.append(attachment)
+        return attachments
+
+    def _extract_attachment_content(
+        self,
+        message: EmailMessage,
+        *,
+        attachment_id: str,
+    ) -> IMAPAttachmentContent:
+        for index, part in enumerate(self._iter_leaf_parts(message), start=1):
+            attachment = self._attachment_metadata(part, index)
+            if attachment is None or attachment.id != attachment_id:
+                continue
+            content = self._part_payload_bytes(part)
+            return IMAPAttachmentContent(
+                attachment=attachment,
+                content=content,
+            )
+        raise IMAPOperationError(f"attachment not found: {attachment_id}")
+
+    def _attachment_metadata(
+        self,
+        part: EmailMessage,
+        index: int,
+    ) -> IMAPAttachment | None:
+        disposition = part.get_content_disposition()
+        filename = part.get_filename()
+        content_id = part.get("Content-ID")
+        if (
+            disposition not in {"attachment", "inline"}
+            and filename is None
+            and content_id is None
+        ):
+            return None
+        return IMAPAttachment(
+            id=f"part-{index}",
+            filename=filename,
+            content_type=part.get_content_type(),
+            size=len(self._part_payload_bytes(part)),
+            disposition=disposition,
+            content_id=content_id,
+            inline=disposition == "inline",
+        )
+
+    def _iter_leaf_parts(self, message: EmailMessage) -> list[EmailMessage]:
+        if message.is_multipart():
+            return [
+                part
+                for part in message.walk()
+                if isinstance(part, EmailMessage) and not part.is_multipart()
+            ]
+        return [message]
+
+    def _part_payload_size(self, part: EmailMessage) -> int:
+        return len(self._part_payload_bytes(part))
+
+    def _part_payload_bytes(self, part: EmailMessage) -> bytes:
+        payload = part.get_payload(decode=True)
+        if isinstance(payload, bytes):
+            return payload
+        content = part.get_content()
+        if isinstance(content, str):
+            return content.encode(part.get_content_charset() or "utf-8")
+        if isinstance(content, bytes):
+            return content
+        return b""
+
     def _snippet_from_body(self, body: str) -> str:
         compact = " ".join(body.split())
         return compact[:240]

{arbiter_imap-0.9.0.dev1/src/agent_arbiter_imap → arbiter_imap-0.9.1.dev2/src/arbiter_imap}/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
 
 
@@ -27,15 +27,27 @@ class IMAPConfirmationAction(str, Enum):
     delete = "delete"
 
 
+class IMAPFolderKind(str, Enum):
+    all = "all"
+    archive = "archive"
+    drafts = "drafts"
+    flagged = "flagged"
+    junk = "junk"
+    sent = "sent"
+    trash = "trash"
+
+
 @dataclass
 class IMAPFolderConfig:
     description: str = ""
+    kind: IMAPFolderKind | None = None
 
 
 @dataclass
 class IMAPConfig(Policy):
     policy: str = "bot"
     description: str = ""
+    guidance: str = ""
     host: str = "localhost"
     port: int = 993
     username: str = ""

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arbiter-imap
-Version: 0.9.0.dev1
+Version: 0.9.1.dev2
 Summary: IMAP service plugin for Arbiter
 Author-email: Omry Yadan <omry@yadan.net>
 Maintainer-email: Omry Yadan <omry@yadan.net>
@@ -20,6 +20,6 @@ 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
 
 IMAP service plugin for Arbiter.

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

@@ -1,8 +1,8 @@
 pyproject.toml
-src/agent_arbiter_imap/__init__.py
-src/agent_arbiter_imap/client.py
-src/agent_arbiter_imap/config.py
-src/agent_arbiter_imap/py.typed
+src/arbiter_imap/__init__.py
+src/arbiter_imap/client.py
+src/arbiter_imap/config.py
+src/arbiter_imap/py.typed
 src/arbiter_imap.egg-info/PKG-INFO
 src/arbiter_imap.egg-info/SOURCES.txt
 src/arbiter_imap.egg-info/dependency_links.txt

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

@@ -0,0 +1,2 @@
+[arbiter.services]
+imap = arbiter_imap:plugin

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

@@ -0,0 +1 @@
+arbiter-server<0.10.0,>=0.9.1.dev2

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

@@ -0,0 +1 @@
+arbiter_imap

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

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

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

@@ -1 +0,0 @@
-arbiter-core<0.10.0,>=0.9.0.dev1

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

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