imap-agent-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{imap_agent_cli-0.1.0 → imap_agent_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imap-agent-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation
 Project-URL: Homepage, https://github.com/pseudosavant/imap-agent-cli
 Project-URL: Repository, https://github.com/pseudosavant/imap-agent-cli
@@ -104,6 +104,32 @@ Config path:
 
 Secrets should stay in environment variables, not the config file.
 
+## Codex Skill
+
+Install or update the user-scoped Codex skill:
+
+```text
+imap-agent-cli install-skill
+```
+
+This writes:
+
+```text
+~/.agents/skills/imap/SKILL.md
+```
+
+Remove the managed skill:
+
+```text
+imap-agent-cli remove-skill
+```
+
+Use `--skills-dir PATH` to install into a nonstandard skills directory, for example:
+
+```text
+imap-agent-cli install-skill --skills-dir C:\Users\PaulEllis\.agents\skills
+```
+
 ## Safety Boundary
 
 Allowed:

{imap_agent_cli-0.1.0 → imap_agent_cli-0.1.2}/README.md

@@ -71,6 +71,32 @@ Config path:
 
 Secrets should stay in environment variables, not the config file.
 
+## Codex Skill
+
+Install or update the user-scoped Codex skill:
+
+```text
+imap-agent-cli install-skill
+```
+
+This writes:
+
+```text
+~/.agents/skills/imap/SKILL.md
+```
+
+Remove the managed skill:
+
+```text
+imap-agent-cli remove-skill
+```
+
+Use `--skills-dir PATH` to install into a nonstandard skills directory, for example:
+
+```text
+imap-agent-cli install-skill --skills-dir C:\Users\PaulEllis\.agents\skills
+```
+
 ## Safety Boundary
 
 Allowed:

{imap_agent_cli-0.1.0 → imap_agent_cli-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "imap-agent-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation"
 readme = "README.md"
 license = "MIT"

{imap_agent_cli-0.1.0 → imap_agent_cli-0.1.2}/src/imap_agent_cli/__init__.py

@@ -1,3 +1,3 @@
 """Agent-first IMAP CLI."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{imap_agent_cli-0.1.0 → imap_agent_cli-0.1.2}/src/imap_agent_cli/cli.py

@@ -10,8 +10,9 @@ from . import __version__
 from .config import add_profile, config_status, init_config, load_config, remove_profile, resolve_profile, set_default_profile
 from .errors import AppError, ConfigError
 from .imap_client import ImapSession
-from .mime import create_draft_message, parse_message
+from .mime import create_draft_message, header_value, parse_message
 from .render import write_error, write_json
+from .skill import install_skill, remove_skill
 
 
 def _read_json_arg(value: str) -> dict[str, Any]:
@@ -138,6 +139,16 @@ def cmd_profiles(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_install_skill(args: argparse.Namespace) -> int:
+    write_json(install_skill(Path(args.skills_dir) if args.skills_dir else None))
+    return 0
+
+
+def cmd_remove_skill(args: argparse.Namespace) -> int:
+    write_json(remove_skill(Path(args.skills_dir) if args.skills_dir else None, force=args.force))
+    return 0
+
+
 def cmd_folders(args: argparse.Namespace) -> int:
     with _session(args) as session:
         write_json(session.folders())
@@ -256,15 +267,15 @@ def cmd_draft_reply(args: argparse.Namespace) -> int:
         raw = session._fetch_raw(str(folder), int(uid))
         source_message = parse_message(raw)
         to = _parse_repeated_addresses(args.to) or _string_list(payload.get("to")) or _reply_recipients(source_message)
-        source_message_id = str(source_message.get("message-id", ""))
-        source_refs = str(source_message.get("references", "")).strip()
+        source_message_id = header_value(source_message, "message-id")
+        source_refs = header_value(source_message, "references").strip()
         references = f"{source_refs} {source_message_id}".strip()
         message = create_draft_message(
             sender=session.profile.username,
             to=to,
             cc=_parse_repeated_addresses(args.cc) or _string_list(payload.get("cc")),
             bcc=_parse_repeated_addresses(args.bcc) or _string_list(payload.get("bcc")),
-            subject=args.subject or payload.get("subject") or _reply_subject(str(source_message.get("subject", ""))),
+            subject=args.subject or payload.get("subject") or _reply_subject(header_value(source_message, "subject")),
             body=body,
             body_format=str(body_format),
             attachments=attachments,
@@ -308,6 +319,15 @@ def build_parser() -> argparse.ArgumentParser:
     profiles = sub.add_parser("profiles")
     profiles.set_defaults(func=cmd_profiles)
 
+    install_skill_parser = sub.add_parser("install-skill")
+    install_skill_parser.add_argument("--skills-dir")
+    install_skill_parser.set_defaults(func=cmd_install_skill)
+
+    remove_skill_parser = sub.add_parser("remove-skill")
+    remove_skill_parser.add_argument("--skills-dir")
+    remove_skill_parser.add_argument("--force", action="store_true")
+    remove_skill_parser.set_defaults(func=cmd_remove_skill)
+
     folders = sub.add_parser("folders")
     _common_profile_args(folders)
     folders.set_defaults(func=cmd_folders)

{imap_agent_cli-0.1.0 → imap_agent_cli-0.1.2}/src/imap_agent_cli/imap_client.py

@@ -6,7 +6,7 @@ from pathlib import Path
 from typing import Any
 
 from .errors import AppError
-from .mime import attachment_infos, message_headers, parse_message, render_body, save_attachments
+from .mime import attachment_infos, header_value, message_headers, parse_message, render_body, save_attachments
 from .models import Defaults, Profile
 from .search import build_criteria
 
@@ -172,8 +172,8 @@ class ImapSession(AbstractContextManager["ImapSession"]):
         return {
             "folder": folder,
             "uid": uid,
-            "message_id": str(message.get("message-id", "")),
-            "date": str(message.get("date", "")),
+            "message_id": header_value(message, "message-id"),
+            "date": header_value(message, "date"),
             "from": headers["from"],
             "to": headers["to"],
             "cc": headers["cc"],
@@ -295,8 +295,8 @@ def message_payload(
         "profile": profile,
         "folder": folder,
         "uid": uid,
-        "message_id": str(message.get("message-id", "")),
-        "date": str(message.get("date", "")),
+        "message_id": header_value(message, "message-id"),
+        "date": header_value(message, "date"),
         "headers": message_headers(message),
         "body": render_body(message, body_format, max_body_chars),
         "attachments": [info for info in attachment_infos(message)],

{imap_agent_cli-0.1.0 → imap_agent_cli-0.1.2}/src/imap_agent_cli/mime.py

@@ -28,6 +28,21 @@ def parse_message(raw: bytes) -> EmailMessage:
     return parsed
 
 
+def header_value(message: Message, name: str, default: str = "") -> str:
+    target = name.lower()
+    try:
+        for key, value in message.raw_items():
+            if key.lower() == target:
+                return str(value)
+    except Exception:
+        pass
+    try:
+        value = message.get(name, default)
+    except Exception:
+        return default
+    return str(value) if value is not None else default
+
+
 def addresses(header_values: Iterable[str | None]) -> list[dict[str, str]]:
     raw = [value for value in header_values if value]
     return [{"name": name, "email": email} for name, email in getaddresses(raw)]
@@ -35,7 +50,7 @@ def addresses(header_values: Iterable[str | None]) -> list[dict[str, str]]:
 
 def message_headers(message: Message) -> dict[str, Any]:
     return {
-        "subject": str(message.get("subject", "")),
+        "subject": header_value(message, "subject"),
         "from": addresses(message.get_all("from", [])),
         "to": addresses(message.get_all("to", [])),
         "cc": addresses(message.get_all("cc", [])),

imap_agent_cli-0.1.2/src/imap_agent_cli/skill.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from .errors import AppError
+
+
+SKILL_NAME = "imap"
+MANAGED_MARKER = "<!-- managed-by: imap-agent-cli -->"
+
+
+SKILL_MD = f"""---
+name: imap
+description: Use when the user asks Codex to search, read, summarize, inspect, or draft email using the local imap-agent-cli tool. Covers safe IMAP-only email access, folder enumeration, attachment download, and draft creation; must not send, delete, move, archive, flag, label, or mark messages read/unread.
+---
+
+{MANAGED_MARKER}
+
+# IMAP Email Access
+
+Use `imap-agent-cli` for safe agentic email workflows over IMAP. The tool can search and read email, list folders, inspect/download attachments, and create drafts. It cannot send email and must not be used for destructive or metadata-mutating mailbox actions.
+
+## Safety Rules
+
+- Never send email. There is no SMTP support.
+- Never delete, move, archive, label, flag, star, mark read, or mark unread messages.
+- Prefer metadata/search before reading message bodies.
+- Do not print large or sensitive email bodies unless the user asks to see the content.
+- Use `--body-format metadata` when you only need headers and attachment metadata.
+- Use `--body-format plain` for summaries unless HTML structure matters.
+- Download attachments only when the user asks and provides or accepts an output directory.
+- Create drafts only with `draft create` or `draft reply`.
+
+## Command Form
+
+Prefer the published CLI:
+
+```powershell
+$env:UV_LINK_MODE = "copy"
+uvx --refresh-package imap-agent-cli imap-agent-cli <command>
+```
+
+If working inside the `imap-agent-cli` repository, this local form is also valid:
+
+```powershell
+uv run ./imap_agent_cli.py <command>
+```
+
+The CLI uses these environment variables for the default profile:
+
+```text
+IMAP_AGENT_CLI_HOST
+IMAP_AGENT_CLI_PORT
+IMAP_AGENT_CLI_USERNAME
+IMAP_AGENT_CLI_PASSWORD
+IMAP_AGENT_CLI_TLS
+IMAP_AGENT_CLI_DRAFTS_FOLDER
+```
+
+## Folder Listing
+
+Use this to discover folder names and Drafts naming:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli folders
+```
+
+Return only relevant folder names/counts to the user unless they ask for the full list.
+
+## Search
+
+Search defaults to `INBOX` when no folder is provided:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder INBOX --max-results 10
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder INBOX --from "Justin" --max-results 10
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder INBOX --since 2026-01-01 --before 2026-02-01 --max-results 10
+```
+
+If a server-side `--from` search times out, enumerate recent messages with a bounded `--max-results` and filter locally by the returned `from` metadata.
+
+For child folders:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli search --folder Projects --recursive --max-results 25
+```
+
+For all folders, use sparingly because large mailboxes can be slow:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli search --all-folders --subject "contract" --max-results 25
+```
+
+## Read
+
+Read a message by folder and UID from search results:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli read --folder INBOX --uid 12345 --body-format metadata
+uvx --refresh-package imap-agent-cli imap-agent-cli read --folder INBOX --uid 12345 --body-format plain --max-body-chars 12000
+uvx --refresh-package imap-agent-cli imap-agent-cli read --folder INBOX --uid 12345 --body-format html
+```
+
+Use `metadata` first when confirming identity, attachments, or headers. Use `plain` when summarizing. Use `html` only when formatting or links matter.
+
+## Attachments
+
+List attachment metadata:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli attachments --folder INBOX --uid 12345
+```
+
+Download requires an explicit output directory:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 1 --output-dir C:\\tmp\\email-attachments
+uvx --refresh-package imap-agent-cli imap-agent-cli attachments download --folder INBOX --uid 12345 --all --output-dir C:\\tmp\\email-attachments
+```
+
+Report saved paths to the user.
+
+## Drafts
+
+Create a new draft:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli draft create --to person@example.com --subject "Subject" --body "Draft body"
+```
+
+Create a reply draft from an existing message:
+
+```powershell
+uvx --refresh-package imap-agent-cli imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Draft reply body"
+```
+
+For longer draft bodies, write a temporary body file and pass `--body-file`. Tell the user a draft was created; do not imply it was sent.
+
+## Output Handling
+
+All CLI payloads are JSON on stdout. Diagnostics and errors are on stderr. Parse JSON before deciding what to show the user, and summarize high-signal fields instead of dumping raw output.
+"""
+
+
+def default_skills_dir() -> Path:
+    return Path.home() / ".agents" / "skills"
+
+
+def skill_dir(skills_dir: Path | None = None) -> Path:
+    return (skills_dir or default_skills_dir()) / SKILL_NAME
+
+
+def install_skill(skills_dir: Path | None = None) -> dict[str, Any]:
+    target = skill_dir(skills_dir)
+    target.mkdir(parents=True, exist_ok=True)
+    skill_path = target / "SKILL.md"
+    previous = skill_path.read_text(encoding="utf-8") if skill_path.exists() else ""
+    updated = previous != SKILL_MD
+    skill_path.write_text(SKILL_MD, encoding="utf-8")
+    return {
+        "installed": True,
+        "updated": updated,
+        "skill": SKILL_NAME,
+        "path": str(skill_path),
+    }
+
+
+def remove_skill(skills_dir: Path | None = None, *, force: bool = False) -> dict[str, Any]:
+    target = skill_dir(skills_dir)
+    skill_path = target / "SKILL.md"
+    if not target.exists():
+        return {"removed": False, "skill": SKILL_NAME, "path": str(target), "reason": "not_installed"}
+    if not skill_path.exists():
+        raise AppError("invalid_request", f"refusing to remove '{target}' because SKILL.md is missing.")
+    content = skill_path.read_text(encoding="utf-8")
+    if MANAGED_MARKER not in content and not force:
+        raise AppError(
+            "invalid_request",
+            f"refusing to remove '{target}' because it is not marked as managed by imap-agent-cli; use --force to override.",
+        )
+    shutil.rmtree(target)
+    return {"removed": True, "skill": SKILL_NAME, "path": str(target)}

{imap_agent_cli-0.1.0 → imap_agent_cli-0.1.2}/tests/test_mime.py

@@ -10,6 +10,7 @@ from tests import _bootstrap  # noqa: F401
 from imap_agent_cli.mime import (
     attachment_infos,
     create_draft_message,
+    header_value,
     parse_message,
     render_body,
     safe_filename,
@@ -71,6 +72,17 @@ class MimeTests(unittest.TestCase):
         self.assertEqual(safe_filename("../x:y?.txt"), "x_y_.txt")
         self.assertEqual(safe_filename(".."), "attachment")
 
+    def test_header_value_handles_malformed_message_id(self) -> None:
+        raw = (
+            b"Message-ID: <[8e15e2eaf6e3479a8a1c3d8230af2e58-JFZGS42DN5WW25LONFRWC5DJN5XFA3DBORTG64TNFVIHE33EFVGVOMKQPRAXU5LSMVCGK5SPOBZXYRLNMFUWY7CFPBXVG3LUOA======@microsoft.com]>\r\n"
+            b"Subject: Test\r\n"
+            b"\r\n"
+            b"Body\r\n"
+        )
+        message = parse_message(raw)
+        self.assertIn("@microsoft.com", header_value(message, "message-id"))
+        self.assertEqual(header_value(message, "subject"), "Test")
+
 
 if __name__ == "__main__":
     unittest.main()

imap_agent_cli-0.1.2/tests/test_skill.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from io import StringIO
+from pathlib import Path
+from unittest.mock import patch
+
+from tests import _bootstrap  # noqa: F401
+
+from imap_agent_cli.cli import main
+from imap_agent_cli.errors import AppError
+from imap_agent_cli.skill import MANAGED_MARKER, install_skill, remove_skill
+
+
+class SkillTests(unittest.TestCase):
+    def test_install_skill_creates_and_updates_managed_skill(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            first = install_skill(root)
+            self.assertTrue(first["installed"])
+            self.assertTrue(first["updated"])
+            skill_path = root / "imap" / "SKILL.md"
+            self.assertTrue(skill_path.exists())
+            content = skill_path.read_text(encoding="utf-8")
+            self.assertIn("name: imap", content)
+            self.assertIn(MANAGED_MARKER, content)
+            self.assertIn("draft reply", content)
+
+            second = install_skill(root)
+            self.assertTrue(second["installed"])
+            self.assertFalse(second["updated"])
+
+    def test_remove_skill_removes_only_managed_skill(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            install_skill(root)
+            removed = remove_skill(root)
+            self.assertTrue(removed["removed"])
+            self.assertFalse((root / "imap").exists())
+
+    def test_remove_skill_refuses_unmanaged_skill_without_force(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            skill_dir = root / "imap"
+            skill_dir.mkdir(parents=True)
+            (skill_dir / "SKILL.md").write_text("---\nname: imap\n---\ncustom\n", encoding="utf-8")
+            with self.assertRaises(AppError):
+                remove_skill(root)
+            removed = remove_skill(root, force=True)
+            self.assertTrue(removed["removed"])
+
+    def test_cli_install_skill_outputs_json(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            stdout = StringIO()
+            with patch("sys.stdout", stdout):
+                code = main(["install-skill", "--skills-dir", tmp])
+            self.assertEqual(code, 0)
+            payload = json.loads(stdout.getvalue())
+            self.assertEqual(payload["skill"], "imap")
+            self.assertTrue((Path(tmp) / "imap" / "SKILL.md").exists())
+
+    def test_cli_remove_skill_outputs_json(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            install_skill(Path(tmp))
+            stdout = StringIO()
+            with patch("sys.stdout", stdout):
+                code = main(["remove-skill", "--skills-dir", tmp])
+            self.assertEqual(code, 0)
+            payload = json.loads(stdout.getvalue())
+            self.assertTrue(payload["removed"])
+
+
+if __name__ == "__main__":
+    unittest.main()