@littlebearapps/outlook-assistant 3.12.1 → 3.14.0

package/email/conversations.js

@@ -14,14 +14,22 @@ const { ensureAuthenticated } = require('../auth');
 const { getEmailFields } = require('../utils/field-presets');
 const { resolveFolderPath } = require('./folder-utils');
 const { buildMailboxPrefix } = require('../utils/mailbox');
-const { writeClaimedFile, makeClaimedDir } = require('../utils/safe-write');
+const {
+  writeClaimedFile,
+  ensureOutputDir,
+  makeClaimedDir,
+  confineOutputPath,
+  OutputPathError,
+} = require('../utils/safe-write');
 const { escapeODataString } = require('../utils/odata-helpers');
 const {
   formatEmailContent,
   formatEmailsAsCSV,
   stripHtml,
   VERBOSITY,
+  DEFAULT_LIMITS,
 } = require('../utils/response-formatter');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 // Note: buildFromFilter/buildToFilter from search.js use OData $filter which causes
 // InefficientFilter on personal accounts with $orderby. Client-side filtering used instead.
 
@@ -235,20 +243,9 @@ async function handleListConversations(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        { type: 'text', text: `Error listing conversations: ${error.message}` },
-      ],
-    };
+    return toolError(`Error listing conversations: ${error.message}`);
   }
 }
 
@@ -264,8 +261,8 @@ const EXPORT_CONVERSATION_MESSAGE_LIMIT = 1000;
  * personal Microsoft accounts (400 InefficientFilter), so the query carries no
  * `$orderby`: the pages are fetched and the messages are sorted here. Paging
  * stops at the caller's `limit` or if Graph repeats a nextLink; either
- * way the result is marked truncated. (Not callGraphAPIPaginated: it can't
- * report truncation or catch a repeated nextLink.)
+ * way the result is marked truncated. (callGraphAPIPaginated stops the same
+ * way and reports `hasMore` since #279; this loop predates that.)
  * @param {string} accessToken - Access token
  * @param {string} prefix - Mailbox prefix (`me` or `users/{mailbox}`)
  * @param {string} conversationId - Conversation ID
@@ -364,9 +361,7 @@ async function handleGetConversation(args) {
   const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!conversationId) {
-    return {
-      content: [{ type: 'text', text: 'Conversation ID is required.' }],
-    };
+    return toolError('Conversation ID is required.');
   }
 
   try {
@@ -386,14 +381,9 @@ async function handleGetConversation(args) {
     );
 
     if (messages.length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `No messages found for conversation ID: ${conversationId}`,
-          },
-        ],
-      };
+      return toolError(
+        `No messages found for conversation ID: ${conversationId}`
+      );
     }
 
     // Format output
@@ -407,7 +397,13 @@ async function handleGetConversation(args) {
 
     messages.forEach((msg, index) => {
       output.push(`## Message ${index + 1} of ${messages.length}`);
-      output.push(formatEmailContent(msg, verbosity, { includeHeaders }));
+      output.push(
+        formatEmailContent(msg, verbosity, {
+          includeHeaders,
+          sharedMailbox,
+          maxFullBodyChars: DEFAULT_LIMITS.maxFullBodyChars,
+        })
+      );
       output.push('\n---\n');
     });
 
@@ -427,20 +423,9 @@ async function handleGetConversation(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        { type: 'text', text: `Error getting conversation: ${error.message}` },
-      ],
-    };
+    return toolError(`Error getting conversation: ${error.message}`);
   }
 }
 
@@ -467,21 +452,22 @@ async function handleExportConversation(args) {
   const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!conversationId) {
-    return {
-      content: [{ type: 'text', text: 'Conversation ID is required.' }],
-    };
+    return toolError('Conversation ID is required.');
   }
 
   const validFormats = ['eml', 'mbox', 'markdown', 'json', 'html', 'csv'];
   if (!validFormats.includes(format)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Invalid format. Use: ${validFormats.join(', ')}`,
-        },
-      ],
-    };
+    return toolError(`Invalid format. Use: ${validFormats.join(', ')}`);
+  }
+
+  // Resolve and check the directory before fetching anything; write only to
+  // the resolved path.
+  let resolvedDir;
+  try {
+    resolvedDir = confineOutputPath(outputDir);
+  } catch (error) {
+    if (!(error instanceof OutputPathError)) throw error;
+    return toolError(error.message, { nextStep: error.nextStep });
   }
 
   try {
@@ -500,20 +486,14 @@ async function handleExportConversation(args) {
     );
 
     if (messages.length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `No messages found for conversation ID: ${conversationId}`,
-          },
-        ],
-      };
+      return toolError(
+        `No messages found for conversation ID: ${conversationId}`
+      );
     }
 
     // Create output directory
-    const resolvedDir = path.resolve(outputDir);
     if (!fs.existsSync(resolvedDir)) {
-      fs.mkdirSync(resolvedDir, { recursive: true });
+      ensureOutputDir(resolvedDir);
     }
 
     // Generate filename base
@@ -788,23 +768,9 @@ async function handleExportConversation(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error exporting conversation: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error exporting conversation: ${error.message}`);
   }
 }
 

package/email/delta.js

@@ -10,6 +10,7 @@ const { formatEmailList, VERBOSITY } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
 const { buildMailboxPrefix } = require('../utils/mailbox');
 const { resolveFolder, looksLikeFolderId } = require('../folder/resolve');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Extract the mailbox segment (`me` or `users/{address}`) from a delta/
@@ -116,16 +117,10 @@ async function handleListEmailsDelta(args) {
       // different mailbox rather than silently syncing the wrong one.
       const tokenMailbox = mailboxFromToken(deltaToken);
       if (tokenMailbox && mailboxesConflict(tokenMailbox, prefix)) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text:
-                `Delta token mailbox mismatch: the token belongs to \`${tokenMailbox}\` but this call targets \`${prefix}\`.\n\n` +
-                'A delta token is bound to the mailbox and folder it was issued for. Use the token from that same mailbox/folder, or omit `deltaToken` to start a fresh initial sync here.',
-            },
-          ],
-        };
+        return toolError(
+          `Delta token mailbox mismatch: the token belongs to \`${tokenMailbox}\` but this call targets \`${prefix}\`.\n\n` +
+            'A delta token is bound to the mailbox and folder it was issued for. Use the token from that same mailbox/folder, or omit `deltaToken` to start a fresh initial sync here.'
+        );
       }
       endpoint = deltaToken;
     } else {
@@ -295,14 +290,7 @@ async function handleListEmailsDelta(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
     // Handle expired delta token
@@ -310,24 +298,12 @@ async function handleListEmailsDelta(args) {
       error.message.includes('410') ||
       error.message.includes('resyncRequired')
     ) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `## Delta Token Expired\n\nThe provided delta token has expired. Please start a new initial sync by calling without a deltaToken.\n\n**Error:** ${error.message}`,
-          },
-        ],
-      };
+      return toolError(
+        `## Delta Token Expired\n\nThe provided delta token has expired. Please start a new initial sync by calling without a deltaToken.\n\n**Error:** ${error.message}`
+      );
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Delta sync failed: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Delta sync failed: ${error.message}`);
   }
 }
 

package/email/draft.js

@@ -9,9 +9,12 @@ const { ensureAuthenticated } = require('../auth');
 const {
   checkRateLimit,
   checkRecipientAllowlist,
+  findBlockedRecipients,
+  getRecipientAllowlist,
   formatDryRunPreview,
 } = require('../utils/safety');
 const { handleGetMailTips } = require('./mail-tips');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Format comma-separated email string into Graph API recipient objects
@@ -25,6 +28,18 @@ function formatRecipients(recipientString) {
   }));
 }
 
+/** Graph fields holding a message's recipients. */
+const RECIPIENT_FIELDS = ['toRecipients', 'ccRecipients', 'bccRecipients'];
+
+/**
+ * Every to/cc/bcc recipient on a Graph message.
+ * @param {object} message - Graph message
+ * @returns {Array<{emailAddress: {address: string}}>}
+ */
+function recipientsOf(message) {
+  return RECIPIENT_FIELDS.flatMap((field) => message?.[field] || []);
+}
+
 /**
  * Auto-detect HTML vs plain text body
  * @param {string} body - Email body content
@@ -108,9 +123,11 @@ class DraftGuardError extends Error {}
  * @param {string} accessToken - Graph access token
  * @param {string} id - Message id the caller passed as the draft id
  * @param {string} action - The draft action being guarded (for the message)
+ * @param {string[]} [extraFields] - Further fields to fetch in the same GET
+ * @returns {Promise<object>} The draft, with id, isDraft, subject and extraFields
  * @throws {DraftGuardError} If the id is not a draft or does not exist
  */
-async function assertIsDraft(accessToken, id, action) {
+async function assertIsDraft(accessToken, id, action, extraFields = []) {
   let message;
   try {
     message = await callGraphAPI(
@@ -119,7 +136,7 @@ async function assertIsDraft(accessToken, id, action) {
       `me/messages/${id}`,
       null,
       {
-        $select: 'id,isDraft,subject',
+        $select: ['id', 'isDraft', 'subject', ...extraFields].join(','),
       }
     );
   } catch (error) {
@@ -137,6 +154,7 @@ async function assertIsDraft(accessToken, id, action) {
       `Message \`${id}\`${subject} is not a draft, so draft action=${action} refused it and nothing was changed. update/send/delete only act on unsent drafts.`
     );
   }
+  return message;
 }
 
 /**
@@ -148,14 +166,9 @@ async function handleDraft(args) {
   const { action } = args;
 
   if (!action) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "Action is required. Use 'create', 'update', 'send', 'delete', 'reply', 'reply-all', or 'forward'.",
-        },
-      ],
-    };
+    return toolError(
+      "Action is required. Use 'create', 'update', 'send', 'delete', 'reply', 'reply-all', or 'forward'."
+    );
   }
 
   switch (action) {
@@ -174,14 +187,9 @@ async function handleDraft(args) {
     case 'forward':
       return handleForwardDraft(args);
     default:
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Invalid action '${action}'. Use 'create', 'update', 'send', 'delete', 'reply', 'reply-all', or 'forward'.`,
-          },
-        ],
-      };
+      return toolError(
+        `Invalid action '${action}'. Use 'create', 'update', 'send', 'delete', 'reply', 'reply-all', or 'forward'.`
+      );
   }
 }
 
@@ -203,10 +211,12 @@ async function handleCreateDraft(args) {
     if (allowlistError) return allowlistError;
   }
 
-  // Pre-save recipient validation via mail-tips
+  // Pre-save recipient validation via mail-tips. The tips are returned
+  // with the result, never added to the draft payload (#272).
+  let tipsResult = null;
   if (doCheckRecipients && allRecipients.length > 0) {
     const allAddresses = allRecipients.map((r) => r.emailAddress.address);
-    const tipsResult = await handleGetMailTips({ recipients: allAddresses });
+    tipsResult = await handleGetMailTips({ recipients: allAddresses });
     const tipsText = tipsResult.content[0]?.text || '';
 
     if (dryRun) {
@@ -254,7 +264,12 @@ async function handleCreateDraft(args) {
       'me/messages',
       message
     );
-    return formatDraftResponse(draft, 'created');
+    const response = formatDraftResponse(draft, 'created');
+    if (tipsResult) {
+      response.content[0].text += `\n---\n\n${tipsResult.content[0]?.text || ''}`;
+      response._meta.mailTips = tipsResult._meta;
+    }
+    return response;
   } catch (error) {
     return handleError('creating draft', error);
   }
@@ -267,11 +282,7 @@ async function handleUpdateDraft(args) {
   const { id } = args;
 
   if (!id) {
-    return {
-      content: [
-        { type: 'text', text: 'Draft ID (id) is required for update.' },
-      ],
-    };
+    return toolError('Draft ID (id) is required for update.');
   }
 
   const message = buildMessageObject(args);
@@ -314,14 +325,29 @@ async function handleSendDraft(args) {
   const { id } = args;
 
   if (!id) {
-    return {
-      content: [{ type: 'text', text: 'Draft ID (id) is required for send.' }],
-    };
+    return toolError('Draft ID (id) is required for send.');
   }
 
   try {
     const accessToken = await ensureAuthenticated();
-    await assertIsDraft(accessToken, id, 'send');
+    // Fetch the recipients as they are now: the draft may have been edited
+    // (here or in Outlook) since it was created.
+    const draft = await assertIsDraft(
+      accessToken,
+      id,
+      'send',
+      RECIPIENT_FIELDS
+    );
+    const blocked = findBlockedRecipients(recipientsOf(draft));
+    if (blocked) {
+      return toolError(
+        `Draft not sent: it is addressed to ${blocked.blocked.join(', ')}, which OUTLOOK_ALLOWED_RECIPIENTS does not allow (allowed recipients/domains: ${blocked.allowed.join(', ')}). The draft is unchanged and still in Drafts.`,
+        {
+          nextStep:
+            'Remove those recipients from the draft (in Outlook, or with draft action=update), or ask the user to add them to OUTLOOK_ALLOWED_RECIPIENTS.',
+        }
+      );
+    }
 
     // Rate limit via send-email counter (shares limit with direct sends)
     const rateLimitError = checkRateLimit('send-email');
@@ -348,11 +374,7 @@ async function handleDeleteDraft(args) {
   const { id } = args;
 
   if (!id) {
-    return {
-      content: [
-        { type: 'text', text: 'Draft ID (id) is required for delete.' },
-      ],
-    };
+    return toolError('Draft ID (id) is required for delete.');
   }
 
   try {
@@ -379,25 +401,15 @@ async function handleReplyDraft(args, endpoint) {
   const { id, body, comment } = args;
 
   if (!id) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Message ID (id) is required for ${endpoint === 'createReplyAll' ? 'reply-all' : 'reply'}.`,
-        },
-      ],
-    };
+    return toolError(
+      `Message ID (id) is required for ${endpoint === 'createReplyAll' ? 'reply-all' : 'reply'}.`
+    );
   }
 
   if (comment && body) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Cannot use both comment and body. Use comment for a short prepended note, or body for full HTML/text content.',
-        },
-      ],
-    };
+    return toolError(
+      'Cannot use both comment and body. Use comment for a short prepended note, or body for full HTML/text content.'
+    );
   }
 
   const requestBody = {};
@@ -412,6 +424,13 @@ async function handleReplyDraft(args, endpoint) {
     };
   }
 
+  const actionName = endpoint === 'createReplyAll' ? 'reply-all' : 'reply';
+
+  // Counted before the draft is created: a reply that the allowlist refuses
+  // below has still written (and removed) a draft.
+  const rateLimitError = checkRateLimit('draft');
+  if (rateLimitError) return rateLimitError;
+
   try {
     const accessToken = await ensureAuthenticated();
     const draft = await callGraphAPI(
@@ -420,17 +439,69 @@ async function handleReplyDraft(args, endpoint) {
       `me/messages/${id}/${endpoint}`,
       Object.keys(requestBody).length > 0 ? requestBody : null
     );
-    const label =
-      endpoint === 'createReplyAll'
-        ? 'reply-all draft created'
-        : 'reply draft created';
-    return formatDraftResponse(draft, label);
+
+    // Graph fills in the recipients from the original message, so they can
+    // only be checked once the draft exists.
+    const refusal = await refuseBlockedReply(accessToken, draft, actionName);
+    if (refusal) return refusal;
+
+    return formatDraftResponse(draft, `${actionName} draft created`);
+  } catch (error) {
+    return handleError(`creating ${actionName} draft`, error);
+  }
+}
+
+/**
+ * When a recipient allowlist is configured, check the recipients Graph put
+ * on a new reply draft. If any is not allowed, delete the draft and return a
+ * refusal; otherwise return null.
+ * @param {string} accessToken - Graph access token
+ * @param {object} draft - The draft Graph returned from createReply/createReplyAll
+ * @param {string} actionName - 'reply' or 'reply-all'
+ * @returns {Promise<object|null>} A tool error, or null to keep the draft
+ */
+async function refuseBlockedReply(accessToken, draft, actionName) {
+  if (!getRecipientAllowlist()) return null;
+
+  let reason;
+  let nextStep;
+  try {
+    let message = draft;
+    if (!RECIPIENT_FIELDS.every((field) => Array.isArray(draft?.[field]))) {
+      message = await callGraphAPI(
+        accessToken,
+        'GET',
+        `me/messages/${draft.id}`,
+        null,
+        { $select: ['id', ...RECIPIENT_FIELDS].join(',') }
+      );
+    }
+    const blocked = findBlockedRecipients(recipientsOf(message));
+    if (!blocked) return null;
+    reason = `The ${actionName} draft would be addressed to ${blocked.blocked.join(', ')}, which OUTLOOK_ALLOWED_RECIPIENTS does not allow (allowed recipients/domains: ${blocked.allowed.join(', ')}).`;
+    nextStep =
+      'Reply only to allowed recipients (for example, action=reply rather than reply-all, or draft action=create addressed to them), or ask the user to add those recipients to OUTLOOK_ALLOWED_RECIPIENTS.';
   } catch (error) {
-    return handleError(
-      `creating ${endpoint === 'createReplyAll' ? 'reply-all' : 'reply'} draft`,
-      error
+    // Unchecked recipients are treated like blocked ones.
+    reason = `The ${actionName} draft's recipients could not be checked against OUTLOOK_ALLOWED_RECIPIENTS (${error.message}).`;
+    nextStep = 'Try the call again.';
+  }
+
+  try {
+    await callGraphAPI(accessToken, 'DELETE', `me/messages/${draft.id}`);
+  } catch (error) {
+    return toolError(
+      `${reason} The draft Graph created could not be deleted (${error.message}), so it is still in Drafts with ID \`${draft.id}\`. Do not send it.`,
+      {
+        nextStep: `Delete it with draft action=delete id=${draft.id} (or in Outlook). ${nextStep}`,
+      }
     );
   }
+
+  return toolError(
+    `${reason} The draft Graph created was deleted, so nothing was kept.`,
+    { nextStep }
+  );
 }
 
 /**
@@ -440,33 +511,17 @@ async function handleForwardDraft(args) {
   const { id, to, body, comment } = args;
 
   if (!id) {
-    return {
-      content: [
-        { type: 'text', text: 'Message ID (id) is required for forward.' },
-      ],
-    };
+    return toolError('Message ID (id) is required for forward.');
   }
 
   if (!to) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Forward recipient (to) is required for forward.',
-        },
-      ],
-    };
+    return toolError('Forward recipient (to) is required for forward.');
   }
 
   if (comment && body) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Cannot use both comment and body. Use comment for a short prepended note, or body for full HTML/text content.',
-        },
-      ],
-    };
+    return toolError(
+      'Cannot use both comment and body. Use comment for a short prepended note, or body for full HTML/text content.'
+    );
   }
 
   const toRecipients = formatRecipients(to);
@@ -475,6 +530,9 @@ async function handleForwardDraft(args) {
   const allowlistError = checkRecipientAllowlist(toRecipients);
   if (allowlistError) return allowlistError;
 
+  const rateLimitError = checkRateLimit('draft');
+  if (rateLimitError) return rateLimitError;
+
   const requestBody = {
     toRecipients,
   };
@@ -516,24 +574,10 @@ function handleError(actionLabel, error) {
   }
 
   if (error.message === 'Authentication required') {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-        },
-      ],
-    };
+    return authRequiredError();
   }
 
-  return {
-    content: [
-      {
-        type: 'text',
-        text: `Error ${actionLabel}: ${error.message}`,
-      },
-    ],
-  };
+  return toolError(`Error ${actionLabel}: ${error.message}`);
 }
 
 module.exports = handleDraft;