source-package.json — Desktop Mail Assistant

{
  "schema_version": 1,
  "runtimes": [
    {
      "name": "python",
      "versions": [
        "3.10"
      ]
    }
  ],
  "dependencies": [],
  "operations": [
    {
      "kind": "list",
      "description": "List configured Mail accounts and mailboxes in a caller-selected account.",
      "target_restrictions": [
        "Only the local user's configured Mail app",
        "Mailboxes are scoped to the exact --account value"
      ]
    },
    {
      "kind": "read",
      "description": "Enumerate every message in the exact chosen mailbox; search reads every subject or sender before filtering and sorting. Only returned summaries and displayed body are bounded.",
      "target_restrictions": [
        "Exact --account and --mailbox; --limit bounds output only, not reads",
        "read enumerates the mailbox to find the ID and fetches its complete body before display truncation"
      ]
    },
    {
      "kind": "read",
      "description": "Read a caller-selected UTF-8 message body file for send or draft, including dry-run.",
      "target_restrictions": [
        "Exact caller-selected --body-file; at most 400000 bytes read plus one overflow byte and 100000 decoded characters"
      ]
    },
    {
      "kind": "send",
      "description": "Send approved message through Mail; correlate against the first 100 Sent entries exposed by Mail, without delivery proof.",
      "target_restrictions": [
        "Only the exact sender, recipients, subject and body bound by the dry-run digest",
        "Requires --approve with the matching digest"
      ]
    },
    {
      "kind": "create",
      "description": "Create a draft in Mail from a previewed full message.",
      "target_restrictions": [
        "Only the exact sender, recipients, subject and body bound by the dry-run digest",
        "Requires --approve with the matching digest"
      ]
    },
    {
      "kind": "read",
      "description": "Test only: read a synthetic fixture selected by DESKTOP_MAIL_FAKE_RESPONSES instead of launching Mail.",
      "target_restrictions": [
        "Requires DESKTOP_MAIL_FAKE_TRANSPORT_TEST_ACK=1 as a second gate",
        "Warns on stderr; uses only the selected fixture file",
        "At most 2097152 bytes plus one overflow byte; schema validation before use"
      ]
    }
  ],
  "authorization": {
    "mode": "user_session",
    "scopes": [],
    "credential_requirements": [
      "The user's configured Mail accounts and macOS Automation grant for the calling terminal or agent harness; the CLI reads no account secret"
    ]
  },
  "network": {
    "domains": [],
    "destinations": [
      "CLI has no network request; macOS Mail uses configured provider hosts, varying by account, for mailbox sync and sends approved sender, To/Cc/Bcc, subject and body",
      "Local /usr/bin/osascript receives operation, chosen account/mailbox/ID/search text or complete message; verified message fields are passed again for Sent correlation"
    ]
  },
  "safety": {
    "read_only_by_default": true,
    "dry_run_supported": true,
    "consequential_writes_require_authorization": true,
    "validation_controls": [
      "send and draft --dry-run show the complete message and digest; no Mail write occurs",
      "Live send or draft recomputes the content digest and refuses missing or mismatched --approve before any Mail write",
      "The digest covers sender, all recipients, subject and body content",
      "All Mail operations invoke /usr/bin/osascript via list-form subprocess.run with fixed JXA source and user data only in argv",
      "Each osascript call has a timeout; send verifies against the selected account's Sent mailbox",
      "Human-readable untrusted output is escaped onto one line; bounded read limits body characters",
      "Partial results state incomplete, list skipped items and exit 2 unless --allow-partial",
      "The fake runner requires DESKTOP_MAIL_FAKE_RESPONSES and DESKTOP_MAIL_FAKE_TRANSPORT_TEST_ACK=1, warns on stderr and never launches Mail",
      "macOS only: unsupported systems are refused before file or Mail I/O",
      "Body files: 400000-byte and 100000-character limits; fixture files: 2097152-byte limit",
      "Required automation properties and malformed response shapes fail explicitly",
      "Sent correlation compares fields and dateSent >= started_at minus five seconds; no unique identifier, upper time bound or delivery receipt",
      "Automation stdout is captured without a byte cap; body display and result limits do not bound capture",
      "Optional subject, sender, dates and account email-address properties use empty fallbacks on errors; IDs, selected account/mailbox, bodies and Sent recipients remain required"
    ],
    "target_restrictions": [
      "Only configured local Mail accounts and caller-selected mailboxes",
      "Writes only the approved message in Mail; reads only the selected body file and test fixture"
    ]
  },
  "tests": {
    "files": [
      "tests/test_desktop_mail_assistant.py",
      "tests/test_hygiene.py"
    ],
    "fixtures": "synthetic_only",
    "provenance": "creator",
    "evidence": [
      "Creator-authored unittest suite uses a gated fake osascript runner; tests never launch Mail",
      "Tests inspect argv versus fixed script source, approval failures, body bounds and escaped output",
      "Hygiene reads package files only; tests cover platform refusal, bounded input and malformed response rejection",
      "Node.js on PATH runs fixed JXA against a synthetic Application to test optional property tolerance and strict required properties without desktop access"
    ]
  }
}

License: MIT (read it).

Back to the listing