iris-chatbot 0.2.4

package/template/src/lib/tooling/tools/communication.ts

@@ -0,0 +1,883 @@
+import { assertAllowedPath, ensureMacOS } from "../safety";
+import { runCommandSafe } from "../runtime";
+import type { ToolDefinition, ToolExecutionContext } from "../types";
+
+type MailInput = {
+  to?: string[];
+  subject?: string;
+  body?: string;
+  cc?: string[];
+  attachments?: string[];
+};
+
+type MessageDraftInput = {
+  to?: string[];
+  body?: string;
+};
+
+type MessageSendInput = MessageDraftInput;
+
+type ContactRecord = {
+  fullName: string;
+  firstName: string;
+  lastName: string;
+  phones: string[];
+  emails: string[];
+};
+
+type ContactMatch = {
+  contact: ContactRecord;
+  score: number;
+  exactName: boolean;
+  exactCompact: boolean;
+};
+
+type ResolvedMessageRecipient = {
+  input: string;
+  name: string | null;
+  handle: string;
+  source: "contact" | "direct";
+};
+
+const APPLESCRIPT_TIMEOUT_MS = 45_000;
+const CONTACT_RECORD_DELIMITER = String.fromCharCode(30);
+const CONTACT_FIELD_DELIMITER = String.fromCharCode(31);
+const CONTACT_VALUE_DELIMITER = String.fromCharCode(29);
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const PHONE_HANDLE_REGEX = /^[+]?[\d().\-\s]{7,}$/;
+const CONTACT_LOOKUP_TIMEOUT_MS = 12_000;
+const CONTACT_QUERY_CACHE_TTL_MS = 5 * 60 * 1000;
+const contactQueryCache = new Map<string, { expiresAt: number; contacts: ContactRecord[] }>();
+
+function asObject(input: unknown): Record<string, unknown> {
+  if (!input || typeof input !== "object") {
+    throw new Error("Tool input must be an object.");
+  }
+  return input as Record<string, unknown>;
+}
+
+function asString(input: unknown, field: string): string {
+  if (typeof input !== "string" || !input.trim()) {
+    throw new Error(`Missing required string field: ${field}`);
+  }
+  return input.trim();
+}
+
+function asStringArray(input: unknown, field: string): string[] {
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new Error(`Missing required array field: ${field}`);
+  }
+  const values = input
+    .map((item) => (typeof item === "string" ? item.trim() : ""))
+    .filter(Boolean);
+  if (values.length === 0) {
+    throw new Error(`Missing required array field: ${field}`);
+  }
+  return values;
+}
+
+function dedupeList(values: string[]): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const value of values) {
+    const trimmed = value.trim();
+    if (!trimmed || seen.has(trimmed)) {
+      continue;
+    }
+    seen.add(trimmed);
+    out.push(trimmed);
+  }
+  return out;
+}
+
+function readContactQueryCache(query: string): ContactRecord[] | null {
+  const key = normalizeNameForMatch(query);
+  if (!key) {
+    return null;
+  }
+  const cached = contactQueryCache.get(key);
+  if (!cached) {
+    return null;
+  }
+  if (cached.expiresAt <= Date.now()) {
+    contactQueryCache.delete(key);
+    return null;
+  }
+  return cached.contacts;
+}
+
+function writeContactQueryCache(query: string, contacts: ContactRecord[]): void {
+  const key = normalizeNameForMatch(query);
+  if (!key) {
+    return;
+  }
+  contactQueryCache.set(key, {
+    expiresAt: Date.now() + CONTACT_QUERY_CACHE_TTL_MS,
+    contacts,
+  });
+
+  if (contactQueryCache.size > 200) {
+    const now = Date.now();
+    for (const [cacheKey, value] of contactQueryCache) {
+      if (value.expiresAt <= now) {
+        contactQueryCache.delete(cacheKey);
+      }
+      if (contactQueryCache.size <= 160) {
+        break;
+      }
+    }
+  }
+}
+
+function normalizeNameForMatch(value: string): string {
+  return value
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+}
+
+function compactName(value: string): string {
+  return value.replace(/\s+/g, "");
+}
+
+function normalizePhoneHandle(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "";
+  }
+  const hasPlusPrefix = trimmed.startsWith("+");
+  const digits = trimmed.replace(/[^\d]/g, "");
+  if (!digits) {
+    return "";
+  }
+  return hasPlusPrefix ? `+${digits}` : digits;
+}
+
+function parseDelimitedValues(value: string | undefined): string[] {
+  if (!value) {
+    return [];
+  }
+  return dedupeList(
+    value
+      .split(CONTACT_VALUE_DELIMITER)
+      .map((entry) => entry.trim())
+      .filter(Boolean),
+  );
+}
+
+function contactDisplayName(contact: ContactRecord): string {
+  const primary = contact.fullName.trim();
+  if (primary) {
+    return primary;
+  }
+  const fallback = [contact.firstName.trim(), contact.lastName.trim()]
+    .filter(Boolean)
+    .join(" ")
+    .trim();
+  return fallback || "Unnamed contact";
+}
+
+function maybeDirectMessageHandle(input: string): string | null {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (EMAIL_REGEX.test(trimmed)) {
+    return trimmed;
+  }
+  if (!PHONE_HANDLE_REGEX.test(trimmed)) {
+    return null;
+  }
+  const digits = trimmed.replace(/[^\d]/g, "");
+  if (!digits || digits.length < 7) {
+    return null;
+  }
+  return normalizePhoneHandle(trimmed);
+}
+
+function selectPreferredMessageHandle(contact: ContactRecord): string | null {
+  const phones = dedupeList(contact.phones.map(normalizePhoneHandle).filter(Boolean));
+  if (phones.length > 0) {
+    return phones[0];
+  }
+  const emails = dedupeList(
+    contact.emails
+      .map((value) => value.trim())
+      .filter((value) => EMAIL_REGEX.test(value)),
+  );
+  if (emails.length > 0) {
+    return emails[0];
+  }
+  return null;
+}
+
+function formatContactOption(contact: ContactRecord): string {
+  const name = contactDisplayName(contact);
+  const handle = selectPreferredMessageHandle(contact);
+  return handle ? `${name} (${handle})` : name;
+}
+
+function findContactMatches(query: string, contacts: ContactRecord[]): ContactMatch[] {
+  const queryNormalized = normalizeNameForMatch(query);
+  if (!queryNormalized) {
+    return [];
+  }
+  const queryCompact = compactName(queryNormalized);
+  const queryTokens = queryNormalized.split(" ").filter(Boolean);
+
+  const matches: ContactMatch[] = [];
+  for (const contact of contacts) {
+    const display = contactDisplayName(contact);
+    const normalizedName = normalizeNameForMatch(display);
+    if (!normalizedName) {
+      continue;
+    }
+    const compact = compactName(normalizedName);
+    const exactName = normalizedName === queryNormalized;
+    const exactCompact = compact === queryCompact;
+    const nameTokens = normalizedName.split(" ").filter(Boolean);
+    const containsMatch = queryNormalized.length >= 2 && normalizedName.includes(queryNormalized);
+    const tokenPrefixMatch =
+      queryTokens.length > 0 &&
+      queryTokens.every((token) =>
+        nameTokens.some((nameToken) => nameToken.startsWith(token)),
+      );
+
+    if (!(exactName || exactCompact || containsMatch || tokenPrefixMatch)) {
+      continue;
+    }
+
+    let score = 0;
+    if (exactName) {
+      score += 500;
+    }
+    if (exactCompact) {
+      score += 430;
+    }
+    if (queryNormalized.length >= 2 && normalizedName.startsWith(queryNormalized)) {
+      score += 250;
+    }
+    if (containsMatch) {
+      score += 170;
+    }
+    if (tokenPrefixMatch) {
+      score += 220;
+    }
+
+    score += Math.max(0, 30 - Math.abs(nameTokens.length - queryTokens.length) * 10);
+    matches.push({ contact, score, exactName, exactCompact });
+  }
+
+  matches.sort((left, right) => {
+    if (right.score !== left.score) {
+      return right.score - left.score;
+    }
+    return contactDisplayName(left.contact).localeCompare(contactDisplayName(right.contact));
+  });
+
+  return matches;
+}
+
+function notFoundContactError(query: string, contacts: ContactRecord[]): Error {
+  const queryNormalized = normalizeNameForMatch(query);
+  const queryTokens = queryNormalized.split(" ").filter((token) => token.length >= 2);
+  const suggestions = dedupeList(
+    contacts
+      .map((contact) => contactDisplayName(contact))
+      .filter(Boolean)
+      .filter((name) => {
+        const normalized = normalizeNameForMatch(name);
+        return queryTokens.some((token) => normalized.includes(token));
+      })
+      .slice(0, 4),
+  );
+
+  if (suggestions.length > 0) {
+    return new Error(
+      `No contact found for "${query}". Similar contacts: ${suggestions.join(", ")}. Ask the user which contact to message or provide a phone/email.`,
+    );
+  }
+  return new Error(
+    `No contact found for "${query}". Ask the user for a full contact name or a phone/email.`,
+  );
+}
+
+function ambiguousContactError(query: string, matches: ContactMatch[]): Error {
+  const candidates = dedupeList(
+    matches
+      .slice(0, 5)
+      .map((match) => formatContactOption(match.contact))
+      .filter(Boolean),
+  );
+  const choices = candidates.length > 0 ? candidates.join(", ") : "multiple contacts";
+  return new Error(
+    `Ambiguous contact name "${query}". Matching contacts: ${choices}. Ask the user which person to message.`,
+  );
+}
+
+function resolveContactFromMatches(query: string, matches: ContactMatch[]): ContactRecord {
+  if (matches.length === 0) {
+    throw new Error(`No matches available for "${query}".`);
+  }
+  if (matches.length === 1) {
+    return matches[0].contact;
+  }
+
+  const exactMatches = matches.filter((match) => match.exactName || match.exactCompact);
+  if (exactMatches.length === 1) {
+    return exactMatches[0].contact;
+  }
+  if (exactMatches.length > 1) {
+    const uniqueExactOptions = dedupeList(
+      exactMatches.map((match) => formatContactOption(match.contact)),
+    );
+    if (uniqueExactOptions.length === 1) {
+      return exactMatches[0].contact;
+    }
+    throw ambiguousContactError(query, exactMatches);
+  }
+
+  const queryTokenCount = normalizeNameForMatch(query).split(" ").filter(Boolean).length;
+  const top = matches[0];
+  const runnerUp = matches[1];
+  if (queryTokenCount >= 2 && top && runnerUp && top.score - runnerUp.score >= 150) {
+    return top.contact;
+  }
+
+  const uniqueOptions = dedupeList(matches.map((match) => formatContactOption(match.contact)));
+  if (uniqueOptions.length === 1) {
+    return matches[0].contact;
+  }
+
+  throw ambiguousContactError(query, matches);
+}
+
+function parseContactRows(output: string): ContactRecord[] {
+  if (!output) {
+    return [];
+  }
+
+  const rows = output
+    .split(CONTACT_RECORD_DELIMITER)
+    .map((row) => row.trim())
+    .filter(Boolean);
+
+  const contacts: ContactRecord[] = [];
+  const seen = new Set<string>();
+  for (const row of rows) {
+    const [fullName = "", firstName = "", lastName = "", phonesRaw = "", emailsRaw = ""] = row
+      .split(CONTACT_FIELD_DELIMITER);
+    const phones = parseDelimitedValues(phonesRaw);
+    const emails = parseDelimitedValues(emailsRaw);
+    if (phones.length === 0 && emails.length === 0) {
+      continue;
+    }
+    const fingerprint = [
+      fullName.trim(),
+      firstName.trim(),
+      lastName.trim(),
+      phones.join("|"),
+      emails.join("|"),
+    ].join("||");
+    if (seen.has(fingerprint)) {
+      continue;
+    }
+    seen.add(fingerprint);
+    contacts.push({
+      fullName: fullName.trim(),
+      firstName: firstName.trim(),
+      lastName: lastName.trim(),
+      phones,
+      emails,
+    });
+  }
+  return contacts;
+}
+
+async function getContactsMatchingQuery(query: string, signal?: AbortSignal): Promise<ContactRecord[]> {
+  const trimmedQuery = query.trim();
+  if (!trimmedQuery) {
+    return [];
+  }
+  const cached = readContactQueryCache(trimmedQuery);
+  if (cached) {
+    return cached;
+  }
+
+  const script =
+    "on replaceText(findText, replaceWith, sourceText)\n" +
+    "set AppleScript's text item delimiters to findText\n" +
+    "set textItems to text items of sourceText\n" +
+    "set AppleScript's text item delimiters to replaceWith\n" +
+    "set joinedText to textItems as text\n" +
+    "set AppleScript's text item delimiters to \"\"\n" +
+    "return joinedText\n" +
+    "end replaceText\n" +
+    "\n" +
+    "on sanitizeText(rawText)\n" +
+    "if rawText is missing value then return \"\"\n" +
+    "set cleaned to rawText as text\n" +
+    "set cleaned to my replaceText(return, \" \", cleaned)\n" +
+    "set cleaned to my replaceText(linefeed, \" \", cleaned)\n" +
+    "set cleaned to my replaceText(character id 29, \" \", cleaned)\n" +
+    "set cleaned to my replaceText(character id 30, \" \", cleaned)\n" +
+    "set cleaned to my replaceText(character id 31, \" \", cleaned)\n" +
+    "return cleaned\n" +
+    "end sanitizeText\n" +
+    "\n" +
+    "on joinList(values, delimiterText)\n" +
+    "set AppleScript's text item delimiters to delimiterText\n" +
+    "set joinedText to values as text\n" +
+    "set AppleScript's text item delimiters to \"\"\n" +
+    "return joinedText\n" +
+    "end joinList\n" +
+    "\n" +
+    "on run argv\n" +
+    "set queryText to item 1 of argv\n" +
+    "set fieldDelimiter to character id 31\n" +
+    "set recordDelimiter to character id 30\n" +
+    "set valueDelimiter to character id 29\n" +
+    "set outputRecords to {}\n" +
+    "tell application \"Contacts\"\n" +
+    "set matchedPeople to {}\n" +
+    "ignoring case\n" +
+    "try\n" +
+    "set matchedPeople to every person whose name contains queryText\n" +
+    "end try\n" +
+    "try\n" +
+    "set matchedPeople to matchedPeople & (every person whose first name contains queryText)\n" +
+    "end try\n" +
+    "try\n" +
+    "set matchedPeople to matchedPeople & (every person whose last name contains queryText)\n" +
+    "end try\n" +
+    "end ignoring\n" +
+    "repeat with p in matchedPeople\n" +
+    "set rawName to \"\"\n" +
+    "set rawFirstName to \"\"\n" +
+    "set rawLastName to \"\"\n" +
+    "try\n" +
+    "set rawName to name of p as text\n" +
+    "end try\n" +
+    "try\n" +
+    "set rawFirstName to first name of p as text\n" +
+    "end try\n" +
+    "try\n" +
+    "set rawLastName to last name of p as text\n" +
+    "end try\n" +
+    "set phoneValues to {}\n" +
+    "repeat with phoneEntry in phones of p\n" +
+    "try\n" +
+    "set phoneValue to value of phoneEntry as text\n" +
+    "if phoneValue is not \"\" then set end of phoneValues to my sanitizeText(phoneValue)\n" +
+    "end try\n" +
+    "end repeat\n" +
+    "set emailValues to {}\n" +
+    "repeat with emailEntry in emails of p\n" +
+    "try\n" +
+    "set emailValue to value of emailEntry as text\n" +
+    "if emailValue is not \"\" then set end of emailValues to my sanitizeText(emailValue)\n" +
+    "end try\n" +
+    "end repeat\n" +
+    "if (count of phoneValues) > 0 or (count of emailValues) > 0 then\n" +
+    "set displayName to my sanitizeText(rawName)\n" +
+    "set firstNameText to my sanitizeText(rawFirstName)\n" +
+    "set lastNameText to my sanitizeText(rawLastName)\n" +
+    "set phoneText to my joinList(phoneValues, valueDelimiter)\n" +
+    "set emailText to my joinList(emailValues, valueDelimiter)\n" +
+    "set rowText to displayName & fieldDelimiter & firstNameText & fieldDelimiter & lastNameText & fieldDelimiter & phoneText & fieldDelimiter & emailText\n" +
+    "set end of outputRecords to rowText\n" +
+    "end if\n" +
+    "end repeat\n" +
+    "end tell\n" +
+    "return my joinList(outputRecords, recordDelimiter)\n" +
+    "end run";
+
+  try {
+    const output = await runAppleScript(
+      script,
+      [trimmedQuery],
+      signal,
+      CONTACT_LOOKUP_TIMEOUT_MS,
+    );
+    const contacts = parseContactRows(output);
+    writeContactQueryCache(trimmedQuery, contacts);
+    return contacts;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/timed out|timeout/i.test(message)) {
+      throw new Error(
+        "Contacts lookup timed out. Check Contacts permissions or send with a phone/email instead.",
+      );
+    }
+    throw new Error(`Contacts lookup failed: ${message}`);
+  }
+}
+
+async function resolveMessageRecipients(
+  requestedRecipients: string[],
+  signal?: AbortSignal,
+): Promise<ResolvedMessageRecipient[]> {
+  const recipients = requestedRecipients
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  if (recipients.length === 0) {
+    throw new Error("Missing required array field: to");
+  }
+
+  const resolved: ResolvedMessageRecipient[] = [];
+  for (const entry of recipients) {
+    const directHandle = maybeDirectMessageHandle(entry);
+    if (directHandle) {
+      resolved.push({
+        input: entry,
+        name: null,
+        handle: directHandle,
+        source: "direct",
+      });
+      continue;
+    }
+
+    const queryCandidates = dedupeList([
+      entry,
+      ...normalizeNameForMatch(entry)
+        .split(" ")
+        .filter((token) => token.length >= 3),
+    ]);
+    const candidateContacts: ContactRecord[] = [];
+    const candidateFingerprints = new Set<string>();
+    for (const query of queryCandidates) {
+      const contacts = await getContactsMatchingQuery(query, signal);
+      for (const contact of contacts) {
+        const fingerprint = [
+          contact.fullName,
+          contact.firstName,
+          contact.lastName,
+          contact.phones.join("|"),
+          contact.emails.join("|"),
+        ].join("||");
+        if (candidateFingerprints.has(fingerprint)) {
+          continue;
+        }
+        candidateFingerprints.add(fingerprint);
+        candidateContacts.push(contact);
+      }
+      if (candidateContacts.length >= 24) {
+        break;
+      }
+    }
+
+    const matches = findContactMatches(entry, candidateContacts);
+    if (matches.length === 0) {
+      throw notFoundContactError(entry, candidateContacts);
+    }
+
+    const matchedContact = resolveContactFromMatches(entry, matches);
+    const handle = selectPreferredMessageHandle(matchedContact);
+    if (!handle) {
+      throw new Error(
+        `Contact "${contactDisplayName(matchedContact)}" has no phone/email handle available for Messages.`,
+      );
+    }
+    resolved.push({
+      input: entry,
+      name: contactDisplayName(matchedContact),
+      handle,
+      source: "contact",
+    });
+  }
+  return resolved;
+}
+
+async function runMessagesSendScript(
+  handles: string[],
+  body: string,
+  signal?: AbortSignal,
+): Promise<number> {
+  const script =
+    "on run argv\n" +
+    "set recipientsText to item 1 of argv\n" +
+    "set msgBody to item 2 of argv\n" +
+    "set sentCount to 0\n" +
+    "tell application \"Messages\"\n" +
+    "launch\n" +
+    "set iMessageService to missing value\n" +
+    "set smsService to missing value\n" +
+    "try\n" +
+    "set iMessageService to first service whose service type = iMessage\n" +
+    "end try\n" +
+    "try\n" +
+    "set smsService to first service whose service type = SMS\n" +
+    "end try\n" +
+    "if iMessageService is missing value and smsService is missing value then error \"No iMessage or SMS service is configured in Messages.\"\n" +
+    "repeat with handleText in paragraphs of recipientsText\n" +
+    "if handleText is not \"\" then\n" +
+    "set sentToRecipient to false\n" +
+    "if iMessageService is not missing value then\n" +
+    "try\n" +
+    "set targetBuddy to buddy handleText of iMessageService\n" +
+    "send msgBody to targetBuddy\n" +
+    "set sentToRecipient to true\n" +
+    "end try\n" +
+    "end if\n" +
+    "if sentToRecipient is false and smsService is not missing value then\n" +
+    "try\n" +
+    "set targetBuddy to buddy handleText of smsService\n" +
+    "send msgBody to targetBuddy\n" +
+    "set sentToRecipient to true\n" +
+    "end try\n" +
+    "end if\n" +
+    "if sentToRecipient is false then error \"Could not resolve Messages recipient: \" & handleText\n" +
+    "set sentCount to sentCount + 1\n" +
+    "end if\n" +
+    "end repeat\n" +
+    "end tell\n" +
+    "return sentCount as text\n" +
+    "end run";
+
+  const output = await runAppleScript(script, [handles.join("\n"), body], signal, 20_000);
+  const parsed = Number.parseInt(output.trim(), 10);
+  if (Number.isFinite(parsed)) {
+    return parsed;
+  }
+  return handles.length;
+}
+
+function summarizeResolvedRecipients(
+  recipients: ResolvedMessageRecipient[],
+): Array<{ input: string; name: string | null; handle: string; source: "contact" | "direct" }> {
+  return recipients.map((recipient) => ({
+    input: recipient.input,
+    name: recipient.name,
+    handle: recipient.handle,
+    source: recipient.source,
+  }));
+}
+
+async function runAppleScript(
+  script: string,
+  args: string[] = [],
+  signal?: AbortSignal,
+  timeoutMs = APPLESCRIPT_TIMEOUT_MS,
+) {
+  const { stdout } = await runCommandSafe({
+    command: "osascript",
+    args: ["-e", script, ...args],
+    signal,
+    timeoutMs,
+  });
+  return stdout;
+}
+
+async function runMailCreateDraft(input: unknown, context: ToolExecutionContext) {
+  ensureMacOS("Mail automation");
+  const payload = asObject(input) as MailInput;
+  const to = asStringArray(payload.to, "to");
+  const subject = asString(payload.subject, "subject");
+  const body = asString(payload.body, "body");
+  const cc = Array.isArray(payload.cc)
+    ? payload.cc.filter((item): item is string => typeof item === "string" && item.trim() !== "")
+    : [];
+  const attachments = Array.isArray(payload.attachments)
+    ? payload.attachments.filter((item): item is string => typeof item === "string" && item.trim() !== "")
+    : [];
+
+  const resolvedAttachments: string[] = [];
+  for (const attachment of attachments) {
+    resolvedAttachments.push(
+      await assertAllowedPath({
+        candidate: attachment,
+        localTools: context.localTools,
+        mode: "read",
+      }),
+    );
+  }
+
+  if (context.localTools.dryRun) {
+    return {
+      dryRun: true,
+      action: "mail_create_draft",
+      to,
+      cc,
+      subject,
+      hasBody: Boolean(body),
+      attachments: resolvedAttachments,
+    };
+  }
+
+  const script =
+    'on run argv\n' +
+    'set toListText to item 1 of argv\n' +
+    'set ccListText to item 2 of argv\n' +
+    'set msgSubject to item 3 of argv\n' +
+    'set msgBody to item 4 of argv\n' +
+    'tell application "Mail"\n' +
+    'set newMessage to make new outgoing message with properties {visible:true, subject:msgSubject, content:msgBody}\n' +
+    'tell newMessage\n' +
+    'repeat with addr in paragraphs of toListText\n' +
+    'if addr is not "" then make new to recipient at end of to recipients with properties {address:addr}\n' +
+    'end repeat\n' +
+    'repeat with ccAddr in paragraphs of ccListText\n' +
+    'if ccAddr is not "" then make new cc recipient at end of cc recipients with properties {address:ccAddr}\n' +
+    'end repeat\n' +
+    'end tell\n' +
+    'activate\n' +
+    'end tell\n' +
+    'return "drafted"\n' +
+    'end run';
+
+  await runAppleScript(script, [to.join("\n"), cc.join("\n"), subject, body], context.signal);
+  return { drafted: true, to, cc, subject, attachments: resolvedAttachments.length };
+}
+
+async function runMailSend(input: unknown, context: ToolExecutionContext) {
+  const result = await runMailCreateDraft(input, context);
+  if (context.localTools.dryRun) {
+    return {
+      ...result,
+      action: "mail_send",
+    };
+  }
+
+  const script =
+    'tell application "Mail"\n' +
+    'set m to last outgoing message\n' +
+    'send m\n' +
+    'end tell';
+  await runAppleScript(script, [], context.signal);
+  return { sent: true };
+}
+
+async function runMessagesCreateDraft(input: unknown, context: ToolExecutionContext) {
+  ensureMacOS("Messages automation");
+  const payload = asObject(input) as MessageDraftInput;
+  const to = asStringArray(payload.to, "to");
+  const body = asString(payload.body, "body");
+  const resolvedRecipients = await resolveMessageRecipients(to, context.signal);
+  const recipientSummary = summarizeResolvedRecipients(resolvedRecipients);
+
+  if (context.localTools.dryRun) {
+    return {
+      dryRun: true,
+      action: "messages_create_draft",
+      recipients: recipientSummary,
+      bodyPreview: body.slice(0, 160),
+    };
+  }
+
+  const script =
+    'tell application "Messages"\n' +
+    "activate\n" +
+    "end tell\n" +
+    'return "draft_prepared"\n';
+  await runAppleScript(script, [], context.signal);
+  return {
+    drafted: true,
+    recipients: recipientSummary,
+    note: "Messages opened. Review and send manually.",
+  };
+}
+
+async function runMessagesSend(input: unknown, context: ToolExecutionContext) {
+  ensureMacOS("Messages automation");
+  const payload = asObject(input) as MessageSendInput;
+  const to = asStringArray(payload.to, "to");
+  const body = asString(payload.body, "body");
+
+  const resolvedRecipients = await resolveMessageRecipients(to, context.signal);
+  const recipientSummary = summarizeResolvedRecipients(resolvedRecipients);
+  const uniqueHandles = dedupeList(resolvedRecipients.map((recipient) => recipient.handle));
+
+  if (context.localTools.dryRun) {
+    return {
+      dryRun: true,
+      action: "messages_send",
+      recipients: recipientSummary,
+      recipientCount: uniqueHandles.length,
+      bodyPreview: body.slice(0, 160),
+    };
+  }
+
+  if (uniqueHandles.length === 0) {
+    throw new Error("No valid message recipients were resolved.");
+  }
+
+  const sentCount = await runMessagesSendScript(uniqueHandles, body, context.signal);
+  return {
+    sent: true,
+    recipients: recipientSummary,
+    recipientCount: sentCount,
+  };
+}
+
+export const communicationTools: ToolDefinition[] = [
+  {
+    name: "mail_create_draft",
+    description: "Create an email draft in Apple Mail.",
+    inputSchema: {
+      type: "object",
+      required: ["to", "subject", "body"],
+      properties: {
+        to: { type: "array", items: { type: "string" } },
+        subject: { type: "string" },
+        body: { type: "string" },
+        cc: { type: "array", items: { type: "string" } },
+        attachments: { type: "array", items: { type: "string" } },
+      },
+      additionalProperties: false,
+    },
+    risk: "external",
+    execute: runMailCreateDraft,
+  },
+  {
+    name: "mail_send",
+    description: "Send an email via Apple Mail.",
+    inputSchema: {
+      type: "object",
+      required: ["to", "subject", "body"],
+      properties: {
+        to: { type: "array", items: { type: "string" } },
+        subject: { type: "string" },
+        body: { type: "string" },
+        cc: { type: "array", items: { type: "string" } },
+        attachments: { type: "array", items: { type: "string" } },
+      },
+      additionalProperties: false,
+    },
+    risk: "external",
+    execute: runMailSend,
+  },
+  {
+    name: "messages_create_draft",
+    description: "Open Messages with resolved recipients and prepare a manual draft (does not send).",
+    inputSchema: {
+      type: "object",
+      required: ["to", "body"],
+      properties: {
+        to: { type: "array", items: { type: "string" } },
+        body: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    risk: "external",
+    execute: runMessagesCreateDraft,
+  },
+  {
+    name: "messages_send",
+    description:
+      "Send a text via Messages. Recipient names are resolved through Contacts; ambiguous names require clarification.",
+    inputSchema: {
+      type: "object",
+      required: ["to", "body"],
+      properties: {
+        to: { type: "array", items: { type: "string" } },
+        body: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+    risk: "external",
+    execute: runMessagesSend,
+  },
+];