Skip to content

A tiny friend in your Mac's notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.

18.5 KB
Raw Blame
import Foundation

// The chat's mail actions: the plan the AI writes (a ```coucou-mail JSON block in its answer),
// what Coucou tells the AI, the matching of PDF pages to recipients and the scripts that send.
// Pure Foundation, tested on any machine (scripts/test-mail-triage.sh). Nothing in a plan
// happens until the user clicks Run on its card (MailAgent.swift).

struct MailOutgoing: Equatable, Sendable {
    var to: [String]
    var cc: [String] = []
    var subject: String
    var body: String
    /// Forward the attachments of this message (its number in the list sent to the AI).
    var attachmentsFrom: Int? = nil
    /// Files on the Mac.
    var files: [String] = []
}

struct MailMergeRecipient: Equatable, Sendable {
    var email: String
    var name: String
    /// What the recipient's page holds ("Bordeaux"), and the {key} of the templates.
    var key: String
}

/// One message per recipient, each with its own page of a PDF.
struct MailMerge: Equatable, Sendable {
    var fromMessage: Int?
    /// The PDF among that message's attachments (nil: the first PDF).
    var attachment: String?
    var splitPages: Bool
    /// Pages go to the recipient whose key they contain; false: in order.
    var matchByKey: Bool
    var recipients: [MailMergeRecipient]
    var subject: String
    var body: String
    /// Files on the Mac, instead of a message's PDF.
    var file: String? = nil
}

enum MailPlanAction: Equatable, Sendable {
    case sort(MailRuleAction, messages: [Int])
    case reply(message: Int, body: String)
    case send(MailOutgoing)
    case merge(MailMerge)
    case saveAttachments(message: Int, folder: String)
}

struct MailPlan: Equatable, Sendable {
    var summary: String
    var actions: [MailPlanAction]

    /// How many mails the plan sends.
    var sendCount: Int {
        actions.reduce(0) { n, a in
            switch a {
            case .send: return n + 1
            case .merge(let m): return n + m.recipients.count
            default: return n
            }
        }
    }
}

enum MailPlanParser {
    static let fence = "```coucou-mail"

    /// The answer without its plan block, the plan, and why the block could not be read.
    static func extract(_ text: String) -> (prose: String, plan: MailPlan?, error: String?) {
        guard let start = text.range(of: fence) else { return (text, nil, nil) }
        let afterFence = text[start.upperBound...]
        let end = afterFence.range(of: "```")
        let json = String(end.map { afterFence[..<$0.lowerBound] } ?? afterFence)
        var prose = String(text[..<start.lowerBound])
        if let end { prose += afterFence[end.upperBound...] }
        prose = prose.trimmingCharacters(in: .whitespacesAndNewlines)
        // Still streaming: no closing fence yet.
        guard end != nil else { return (prose, nil, nil) }
        do {
            return (prose, try decode(json), nil)
        } catch {
            return (prose, nil, "\(error)")
        }
    }

    struct Failure: Error, CustomStringConvertible {
        let description: String
    }

    static func decode(_ json: String) throws -> MailPlan {
        guard let data = json.trimmingCharacters(in: .whitespacesAndNewlines).data(using: .utf8),
              let root = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
            throw Failure(description: "not a JSON object")
        }
        let list = root["actions"] as? [[String: Any]] ?? []
        var actions: [MailPlanAction] = []
        for (i, a) in list.enumerated() {
            guard let type = a["type"] as? String else { throw Failure(description: "action \(i + 1) has no type") }
            actions.append(try action(type.lowercased(), a, index: i + 1))
        }
        guard !actions.isEmpty else { throw Failure(description: "no actions") }
        return MailPlan(summary: root["summary"] as? String ?? "", actions: actions)
    }

    private static func ints(_ v: Any?) -> [Int] {
        if let n = int(v) { return [n] }
        return (v as? [Any] ?? []).compactMap(int)
    }

    private static func int(_ v: Any?) -> Int? {
        if let n = v as? Int { return n }
        if let d = v as? Double { return Int(d) }
        if let s = v as? String { return Int(s.trimmingCharacters(in: CharacterSet(charactersIn: "[] "))) }
        return nil
    }

    private static func strings(_ v: Any?) -> [String] {
        if let s = v as? String { return s.split(separator: ",").map { $0.trimmingCharacters(in: .whitespaces) }.filter { !$0.isEmpty } }
        return (v as? [Any] ?? []).compactMap { $0 as? String }.filter { !$0.isEmpty }
    }

    private static func action(_ type: String, _ a: [String: Any], index: Int) throws -> MailPlanAction {
        func need(_ key: String) throws -> String {
            guard let s = a[key] as? String, !s.trimmingCharacters(in: .whitespaces).isEmpty else {
                throw Failure(description: "action \(index) (\(type)) needs \"\(key)\"")
            }
            return s
        }
        func message() throws -> Int {
            guard let n = int(a["message"]) else { throw Failure(description: "action \(index) (\(type)) needs \"message\"") }
            return n
        }
        switch type {
        case "flag", "important", "junk", "read", "mark_read", "move":
            let messages = ints(a["messages"] ?? a["message"])
            guard !messages.isEmpty else { throw Failure(description: "action \(index) (\(type)) needs \"messages\"") }
            let act: MailRuleAction
            switch type {
            case "junk": act = .junk
            case "read", "mark_read": act = .markRead
            case "move": act = .move(try need("mailbox"))
            default: act = .important
            }
            return .sort(act, messages: messages)
        case "reply":
            return .reply(message: try message(), body: try need("body"))
        case "send":
            let to = strings(a["to"])
            guard !to.isEmpty else { throw Failure(description: "action \(index) (send) needs \"to\"") }
            return .send(MailOutgoing(to: to, cc: strings(a["cc"]), subject: a["subject"] as? String ?? "",
                                      body: a["body"] as? String ?? "", attachmentsFrom: int(a["attachments_from"]),
                                      files: strings(a["files"])))
        case "merge", "mail_merge":
            let recipients = (a["recipients"] as? [[String: Any]] ?? []).compactMap { r -> MailMergeRecipient? in
                guard let email = r["email"] as? String, !email.isEmpty else { return nil }
                return MailMergeRecipient(email: email, name: r["name"] as? String ?? "",
                                          key: (r["key"] as? String) ?? (r["city"] as? String) ?? "")
            }
            guard !recipients.isEmpty else { throw Failure(description: "action \(index) (merge) needs \"recipients\"") }
            let match = (a["match"] as? String ?? "key").lowercased()
            return .merge(MailMerge(fromMessage: int(a["from_message"] ?? a["message"]),
                                    attachment: a["attachment"] as? String,
                                    splitPages: a["split_pages"] as? Bool ?? true,
                                    matchByKey: match != "order",
                                    recipients: recipients,
                                    subject: a["subject"] as? String ?? "",
                                    body: a["body"] as? String ?? "",
                                    file: a["file"] as? String))
        case "save_attachments", "save":
            return .saveAttachments(message: try message(), folder: try need("folder"))
        default:
            throw Failure(description: "action \(index) has an unknown type \"\(type)\"")
        }
    }
}

// MARK: - Mail merge

enum MailMergeMatching {
    struct Assignment: Equatable, Sendable {
        let recipient: MailMergeRecipient
        /// The page (0-based) for this recipient, nil when none was found.
        let page: Int?
        /// More than one page held the key: the first free one was taken.
        let ambiguous: Bool
    }

    /// Gives each recipient a page: the one whose text holds its key as a whole word, or the
    /// page in the same order. A page goes to one recipient only.
    static func assign(pages: [String], recipients: [MailMergeRecipient], byKey: Bool) -> [Assignment] {
        guard byKey else {
            return recipients.enumerated().map { i, r in
                Assignment(recipient: r, page: i < pages.count ? i : nil, ambiguous: false)
            }
        }
        var taken = Set<Int>()
        return recipients.map { r in
            let key = r.key.trimmingCharacters(in: .whitespaces)
            guard !key.isEmpty else { return Assignment(recipient: r, page: nil, ambiguous: false) }
            let hits = pages.indices.filter { MailTriage.containsWord(pages[$0], key) }
            let free = hits.filter { !taken.contains($0) }
            guard let page = free.first else { return Assignment(recipient: r, page: nil, ambiguous: false) }
            taken.insert(page)
            return Assignment(recipient: r, page: page, ambiguous: hits.count > 1)
        }
    }

    /// {name}, {key} (and {city}, {email}) filled in.
    static func fill(_ template: String, _ r: MailMergeRecipient) -> String {
        template
            .replacingOccurrences(of: "{name}", with: r.name)
            .replacingOccurrences(of: "{key}", with: r.key)
            .replacingOccurrences(of: "{city}", with: r.key)
            .replacingOccurrences(of: "{email}", with: r.email)
    }

    /// A file name for a recipient's page: "Plans - Bordeaux.pdf".
    static func pageFileName(base: String, key: String, page: Int) -> String {
        let stem = (base as NSString).deletingPathExtension
        let label = key.isEmpty ? "p\(page + 1)" : key
        let safe = (stem + " - " + label).replacingOccurrences(of: "/", with: "-").replacingOccurrences(of: ":", with: "-")
        return safe + ".pdf"
    }
}

enum MailAddress {
    /// A plain address check: [email protected], no spaces.
    static func isValid(_ s: String) -> Bool {
        let t = s.trimmingCharacters(in: .whitespaces)
        guard !t.contains(" "), let at = t.firstIndex(of: "@"), at != t.startIndex else { return false }
        let domain = t[t.index(after: at)...]
        return domain.contains(".") && !domain.hasPrefix(".") && !domain.hasSuffix(".") && !domain.contains("@")
    }
}

// MARK: - What the AI is told

enum MailAgentPrompt {
    /// Added to the chat's system prompt while the chat's Mail switch is on.
    static let instructions = """


    The user turned on Mail: you can act on their Apple Mail through Coucou. Their latest messages are listed under their request, each with a number [n]; some come with their text and attachments.
    When they ask you to DO something with their mail, answer in one or two short sentences, then give ONE plan in a fenced code block tagged coucou-mail, holding JSON:
    {"summary": "what the plan does, in the user's language", "actions": [ ... ]}
    Actions:
    - {"type": "flag" | "junk" | "read" | "move", "messages": [n, ...], "mailbox": "only for move"}
    - {"type": "reply", "message": n, "body": "..."} : a reply draft opened in Mail, not sent
    - {"type": "send", "to": ["address"], "cc": [], "subject": "...", "body": "...", "attachments_from": n (optional: that message's attachments), "files": ["/path"] (optional)}
    - {"type": "merge", "from_message": n, "attachment": "name of a PDF in that message", "split_pages": true, "match": "key" or "order", "recipients": [{"email": "...", "name": "...", "key": "what is written on their page, like a city"}], "subject": "... {key} ...", "body": "Hello {name}, ..."} : one mail per recipient, each with the PDF page that contains their key (or the page in the same order)
    - {"type": "save_attachments", "message": n, "folder": "~/Documents/..."}
    Rules: nothing happens until the user clicks Run under your plan, so never say it is done. Never invent an address: use only addresses the user gave, found in their messages, or in a file they shared. If something is missing (the recipients' addresses, which message), ask instead of writing a plan. A question about their mail gets an answer, without a plan. Plain text bodies, in the user's language.
    """

    struct Line: Sendable {
        let number: Int
        let sender: String
        let subject: String
        let date: Date
        let isRead: Bool
        let account: String
        var attachments: [String] = []
        var text: String? = nil
    }

    /// The list sent under the user's request.
    static func snapshot(_ lines: [Line], accounts: [(name: String, address: String)], now: Date = Date()) -> String {
        let df = DateFormatter()
        df.locale = Locale(identifier: "en_US_POSIX")
        df.dateFormat = "yyyy-MM-dd HH:mm"
        var out = "\n\n<mail>\n"
        if !accounts.isEmpty {
            out += "Accounts: " + accounts.map { "\($0.name) <\($0.address)>" }.joined(separator: ", ") + "\n"
        }
        for l in lines {
            out += "[\(l.number)] \(df.string(from: l.date)) · \(l.isRead ? "read" : "unread") · \(l.account) · from \(l.sender) · \"\(l.subject)\""
            if !l.attachments.isEmpty { out += " · attachments: " + l.attachments.joined(separator: ", ") }
            out += "\n"
            if let t = l.text, !t.isEmpty {
                out += "    text: " + t.replacingOccurrences(of: "\n", with: " ").prefix(3000) + "\n"
            }
        }
        out += "</mail>"
        return out
    }

    /// The messages a request names (a sender or a subject word of four letters or more),
    /// best first: their text goes to the AI.
    static func mentioned(in query: String, senders: [String], subjects: [String], limit: Int = 3) -> [Int] {
        let words = query.split { !$0.isLetter && !$0.isNumber && $0 != "@" && $0 != "." }
            .map { MailTriage.normalize(String($0)) }
            .filter { $0.count >= 4 }
        guard !words.isEmpty else { return [] }
        var scored: [(Int, Int)] = []
        for i in senders.indices {
            let s = MailTriage.normalize(senders[i]), sub = MailTriage.normalize(subjects[i])
            let score = words.reduce(0) { $0 + (s.contains($1) ? 2 : 0) + (sub.contains($1) ? 1 : 0) }
            if score > 0 { scored.append((i, score)) }
        }
        return scored.sorted { $0.1 != $1.1 ? $0.1 > $1.1 : $0.0 < $1.0 }.prefix(limit).map(\.0)
    }
}

// MARK: - Scripts

extension MailScript {
    /// Sends one message from Mail. `from` picks the sending address; attachments are POSIX paths.
    static func sendScript(from: String?, to: [String], cc: [String], subject: String, body: String,
                           attachments: [String]) -> String {
        var s = """
        tell application id "com.apple.mail"
            set m to make new outgoing message with properties {subject:\(quote(subject)), content:\(quote(body)), visible:false}

        """
        if let from, !from.isEmpty { s += "    set sender of m to \(quote(from))\n" }
        s += "    tell m\n"
        for a in to { s += "        make new to recipient at end of to recipients with properties {address:\(quote(a))}\n" }
        for a in cc { s += "        make new cc recipient at end of cc recipients with properties {address:\(quote(a))}\n" }
        for p in attachments {
            s += "        make new attachment with properties {file name:(POSIX file \(quote(p)))} at after the last paragraph of content\n"
        }
        s += "    end tell\n"
        if !attachments.isEmpty { s += "    delay 1\n" }
        s += """
            send m
            return "ok"
        end tell
        """
        return s
    }

    /// Saves a message's attachments (only `onlyName` when given) into `folder`, returns the
    /// saved file names, one per line.
    static func saveAttachmentsScript(account: String, mailbox: String, messageId: Int, folder: String,
                                      onlyName: String? = nil) -> String {
        let test = onlyName.map { "(name of a) is \(quote($0))" } ?? "true"
        return """
        tell application id "com.apple.mail"
            \(MailScript.findMessage(messageId, in: "mailbox \(quote(mailbox)) of account \(quote(account))"))
            set out to ""
            repeat with a in mail attachments of m
                if \(test) then
                    set p to \(quote(folder.hasSuffix("/") ? folder : folder + "/")) & (name of a)
                    save a in (POSIX file p)
                    set out to out & (name of a) & linefeed
                end if
            end repeat
            return out
        end tell
        """
    }

    /// Opens Mail's reply window for a message with `body` above the quoted text. Not sent.
    static func replyDraftScript(account: String, mailbox: String, messageId: Int, body: String) -> String {
        """
        tell application id "com.apple.mail"
            \(MailScript.findMessage(messageId, in: "mailbox \(quote(mailbox)) of account \(quote(account))"))
            set r to reply m with opening window
            try
                set content of r to \(quote(body)) & return & return & (content of r)
            end try
            activate
            return "ok"
        end tell
        """
    }

    /// The names of a message's attachments and the start of its text: names one per line,
    /// then a record separator, then the text.
    static func detailsScript(account: String, mailbox: String, messageId: Int, textLimit: Int) -> String {
        """
        tell application id "com.apple.mail"
            \(MailScript.findMessage(messageId, in: "mailbox \(quote(mailbox)) of account \(quote(account))"))
            set out to ""
            try
                repeat with a in mail attachments of m
                    set out to out & (name of a) & linefeed
                end repeat
            end try
            set c to ""
            try
                set c to content of m
            end try
            if (length of c) > \(textLimit) then set c to text 1 thru \(textLimit) of c
            return out & (character id 30) & c
        end tell
        """
    }

    /// Every enabled account: name, a unit separator, its first address; one per line.
    static let accountsScript = """
    tell application id "com.apple.mail"
        set out to ""
        repeat with acc in (every account whose enabled is true)
            set addr to ""
            try
                set addr to item 1 of (email addresses of acc)
            end try
            set out to out & (name of acc) & (character id 31) & addr & linefeed
        end repeat
        return out
    end tell
    """
}