@littlebearapps/outlook-assistant 3.12.1 → 3.14.0

package/email/search.js

@@ -19,6 +19,8 @@ const {
   escapeSearchPhrase,
   quoteSearchPhrase,
 } = require('../utils/odata-helpers');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 // Upper bound on how many recent messages the client-side fallback scans
 // before giving up. Deliberately DECOUPLED from the requested result count so
@@ -50,9 +52,7 @@ async function handleSearchEmails(args) {
 
   // Validate count
   if (args.count !== undefined && args.count < 1) {
-    return {
-      content: [{ type: 'text', text: 'count must be at least 1.' }],
-    };
+    return toolError('count must be at least 1.');
   }
 
   // F-17: accept `maxResults` as an alias for `count` in non-delta mode.
@@ -111,12 +111,12 @@ async function handleSearchEmails(args) {
     let endpoint;
     if (searchAllFolders) {
       endpoint = `${buildMailboxPrefix(sharedMailbox)}/messages`;
-      console.error(
+      log.debug(
         `Searching across all mail folders${sharedMailbox ? ` in ${sharedMailbox}` : ''}`
       );
     } else {
       endpoint = await resolveFolderPath(accessToken, folder, sharedMailbox);
-      console.error(`Using endpoint: ${endpoint} for folder: ${folder}`);
+      log.debug(`Using endpoint: ${endpoint} for folder: ${folder}`);
     }
 
     // Execute progressive search with pagination
@@ -140,25 +140,11 @@ async function handleSearchEmails(args) {
   } catch (error) {
     // Handle authentication errors
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
     // General error response
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error searching emails: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error searching emails: ${error.message}`);
   }
 }
 
@@ -256,7 +242,7 @@ async function retryFieldScopedExpression(ctx) {
   const translated = parseFieldScopedExpression(trimmedKql);
   if (!translated) return null;
 
-  console.error(
+  log.debug(
     `Retrying field-scoped searchExpression as OData filters: ${JSON.stringify(translated)}`
   );
   const retry = await progressiveSearch(
@@ -357,7 +343,7 @@ async function progressiveSearch(
     };
 
     try {
-      console.error(`Attempting raw KQL search: ${kqlForSearch}`);
+      log.debug(`Attempting raw KQL search: ${kqlForSearch}`);
       searchAttempts.push('raw-kql');
 
       const kqlParams = {
@@ -373,7 +359,7 @@ async function progressiveSearch(
         kqlParams,
         maxCount
       );
-      console.error(
+      log.debug(
         `Raw KQL search complete: ${response.value?.length || 0} results`
       );
       const matched = response.value?.length || 0;
@@ -400,7 +386,7 @@ async function progressiveSearch(
           const retry = await retryFieldScopedExpression(translationContext);
           if (retry) return retry;
         } catch (retryError) {
-          console.error(`Translated retry failed: ${retryError.message}`);
+          log.debug(`Translated retry failed: ${retryError.message}`);
         }
       }
 
@@ -408,7 +394,7 @@ async function progressiveSearch(
       // would ignore kqlQuery and return unrelated emails.
       return response;
     } catch (error) {
-      console.error(`Raw KQL search failed: ${error.message}`);
+      log.debug(`Raw KQL search failed: ${error.message}`);
       searchAttempts.push('raw-kql-error');
 
       // A field-scoped expression is what Graph rejects here on personal
@@ -422,7 +408,7 @@ async function progressiveSearch(
           return retry;
         }
       } catch (retryError) {
-        console.error(`Translated retry also failed: ${retryError.message}`);
+        log.debug(`Translated retry also failed: ${retryError.message}`);
       }
 
       // Surface the failure rather than masking it with unrelated results.
@@ -454,7 +440,7 @@ async function progressiveSearch(
     (filterTerms.hasAttachments === true || filterTerms.unreadOnly === true)
   ) {
     // Skip directly to boolean-only filter (step 3) — combined search is redundant
-    console.error('Only boolean filters provided, skipping combined search');
+    log.debug('Only boolean filters provided, skipping combined search');
   } else {
     try {
       const params = buildSearchParams(
@@ -463,7 +449,7 @@ async function progressiveSearch(
         Math.min(50, maxCount),
         selectFields
       );
-      console.error('Attempting combined search with params:', params);
+      log.debug('Attempting combined search with params:', params);
       searchAttempts.push('combined-search');
 
       const response = await callGraphAPIPaginated(
@@ -474,7 +460,7 @@ async function progressiveSearch(
         maxCount
       );
       if (response.value && response.value.length > 0) {
-        console.error(
+        log.debug(
           `Combined search successful: found ${response.value.length} results`
         );
         response._searchInfo = {
@@ -488,7 +474,7 @@ async function progressiveSearch(
         return response;
       }
     } catch (error) {
-      console.error(`Combined search failed: ${error.message}`);
+      log.debug(`Combined search failed: ${error.message}`);
     }
   }
 
@@ -503,9 +489,7 @@ async function progressiveSearch(
     // 2a. Server-side single-term attempt (isolated try/catch — a failure
     // here just falls through to the one client-side fallback below).
     try {
-      console.error(
-        `Attempting search with only ${term}: "${searchTerms[term]}"`
-      );
+      log.debug(`Attempting search with only ${term}: "${searchTerms[term]}"`);
       searchAttempts.push(`single-term-${term}`);
 
       const simplifiedParams = {
@@ -565,7 +549,7 @@ async function progressiveSearch(
             secondaryApplied.length > 0
               ? ` after local ${secondaryApplied.join(', ')} narrowing of ${response.value.length}`
               : '';
-          console.error(
+          log.debug(
             `Search with ${term} successful: found ${matched.length} results${narrowing}`
           );
           narrowResponse(response, matched);
@@ -582,12 +566,12 @@ async function progressiveSearch(
           return response;
         }
         recordNarrowingMiss(scanState, response.value.length);
-        console.error(
+        log.debug(
           `Search with ${term} found ${response.value.length} results, but none also satisfied ${secondaryApplied.join(', ')} — continuing`
         );
       }
     } catch (error) {
-      console.error(`Search with ${term} failed: ${error.message}`);
+      log.debug(`Search with ${term} failed: ${error.message}`);
       // Fall through to the client-side fallback below.
     }
 
@@ -597,7 +581,7 @@ async function progressiveSearch(
     // try/catch prevents the double-scan/double-label a throw inside a
     // success-path fallback would otherwise cause. (#169)
     if (term === 'to' || term === 'query') {
-      console.error(
+      log.debug(
         `${term} unsatisfied server-side, trying client-side filtering`
       );
       searchAttempts.push(`client-side-${term}`);
@@ -614,7 +598,7 @@ async function progressiveSearch(
         );
         if (fallback) return fallback;
       } catch (fallbackError) {
-        console.error(
+        log.debug(
           `Client-side ${term} fallback also failed: ${fallbackError.message}`
         );
       }
@@ -628,7 +612,7 @@ async function progressiveSearch(
     filterTerms.receivedAfter || filterTerms.receivedBefore;
   if (hasBooleanFilters || hasDateFilters) {
     try {
-      console.error('Attempting search with only boolean/date filters');
+      log.debug('Attempting search with only boolean/date filters');
       searchAttempts.push('boolean-filters-only');
 
       const filterOnlyParams = {
@@ -651,7 +635,7 @@ async function progressiveSearch(
         filterOnlyParams,
         maxCount
       );
-      console.error(
+      log.debug(
         `Boolean filter search found ${response.value?.length || 0} results`
       );
       // This step applied only the boolean/date filters. Narrow by the
@@ -677,15 +661,15 @@ async function progressiveSearch(
         return response;
       }
       recordNarrowingMiss(scanState, response.value.length);
-      console.error(
+      log.debug(
         `Boolean filter search found ${response.value.length} results, but none satisfied ${secondaryApplied.join(', ')} — continuing`
       );
     } catch (error) {
-      console.error(`Boolean filter search failed: ${error.message}`);
+      log.debug(`Boolean filter search failed: ${error.message}`);
       // Retry without $orderby if it was the issue
       if (error.message && error.message.includes('InefficientFilter')) {
         try {
-          console.error('Retrying boolean filters without $orderby');
+          log.debug('Retrying boolean filters without $orderby');
           const retryParams = {
             $top: Math.min(50, maxCount),
             $select: selectFields,
@@ -722,13 +706,11 @@ async function progressiveSearch(
             return response;
           }
           recordNarrowingMiss(scanState, response.value.length);
-          console.error(
+          log.debug(
             `Boolean filter retry found ${response.value.length} results, but none satisfied ${secondaryApplied.join(', ')} — continuing`
           );
         } catch (retryError) {
-          console.error(
-            `Boolean filter retry also failed: ${retryError.message}`
-          );
+          log.debug(`Boolean filter retry also failed: ${retryError.message}`);
         }
       }
     }
@@ -745,7 +727,7 @@ async function progressiveSearch(
     searchTerms.kqlQuery;
 
   if (hasAnyFilters) {
-    console.error(
+    log.debug(
       'All search strategies exhausted with filters active — returning 0 results'
     );
     searchAttempts.push('no-results');
@@ -774,7 +756,7 @@ async function progressiveSearch(
   }
 
   // No search filters specified — return recent emails (list mode)
-  console.error('No search filters specified, returning recent emails');
+  log.debug('No search filters specified, returning recent emails');
   searchAttempts.push('recent-emails');
 
   const basicParams = {
@@ -790,7 +772,7 @@ async function progressiveSearch(
     basicParams,
     maxCount
   );
-  console.error(`Recent emails: found ${response.value?.length || 0} results`);
+  log.debug(`Recent emails: found ${response.value?.length || 0} results`);
 
   response._searchInfo = {
     attemptsCount: searchAttempts.length,
@@ -1023,6 +1005,7 @@ function narrowResponse(response, matched) {
   if (dropped) {
     delete response['@odata.count'];
     delete response['@odata.nextLink'];
+    delete response.hasMore;
   }
 }
 
@@ -1177,7 +1160,7 @@ async function runClientSideFallback(
   if (matched.length === 0) {
     return null;
   }
-  console.error(
+  log.debug(
     `Client-side ${kind} matched ${matched.length} of ${messages.length} scanned messages`
   );
   return {
@@ -1257,7 +1240,7 @@ function buildSearchParams(searchTerms, filterTerms, count, selectFields) {
       const afterDate = new Date(filterTerms.receivedAfter).toISOString();
       filterConditions.push(`receivedDateTime ge ${afterDate}`);
     } catch (_e) {
-      console.error(`Invalid receivedAfter date: ${filterTerms.receivedAfter}`);
+      log.debug(`Invalid receivedAfter date: ${filterTerms.receivedAfter}`);
     }
   }
 
@@ -1266,9 +1249,7 @@ function buildSearchParams(searchTerms, filterTerms, count, selectFields) {
       const beforeDate = new Date(filterTerms.receivedBefore).toISOString();
       filterConditions.push(`receivedDateTime le ${beforeDate}`);
     } catch (_e) {
-      console.error(
-        `Invalid receivedBefore date: ${filterTerms.receivedBefore}`
-      );
+      log.debug(`Invalid receivedBefore date: ${filterTerms.receivedBefore}`);
     }
   }
 
@@ -1307,7 +1288,7 @@ function addBooleanFilters(params, filterTerms) {
       const afterDate = new Date(filterTerms.receivedAfter).toISOString();
       filterConditions.push(`receivedDateTime ge ${afterDate}`);
     } catch (_e) {
-      console.error(`Invalid receivedAfter date: ${filterTerms.receivedAfter}`);
+      log.debug(`Invalid receivedAfter date: ${filterTerms.receivedAfter}`);
     }
   }
 
@@ -1316,9 +1297,7 @@ function addBooleanFilters(params, filterTerms) {
       const beforeDate = new Date(filterTerms.receivedBefore).toISOString();
       filterConditions.push(`receivedDateTime le ${beforeDate}`);
     } catch (_e) {
-      console.error(
-        `Invalid receivedBefore date: ${filterTerms.receivedBefore}`
-      );
+      log.debug(`Invalid receivedBefore date: ${filterTerms.receivedBefore}`);
     }
   }
 
@@ -1440,7 +1419,7 @@ function formatSearchResults(response, folder, verbosity, searchAllFolders) {
   const meta = {
     returned: (response.value || []).length,
     totalAvailable: response['@odata.count'] || null,
-    hasMore: Boolean(response['@odata.nextLink']),
+    hasMore: Boolean(response.hasMore || response['@odata.nextLink']),
     verbosity: verbosity,
   };
 
@@ -1585,14 +1564,9 @@ async function handleSearchByMessageId(args) {
   const prefix = buildMailboxPrefix(args.sharedMailbox || args.email || null);
 
   if (!messageId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Message-ID is required. Provide the full Message-ID header value (e.g., <abc123@example.com>)',
-        },
-      ],
-    };
+    return toolError(
+      'Message-ID is required. Provide the full Message-ID header value (e.g., <abc123@example.com>)'
+    );
   }
 
   try {
@@ -1613,7 +1587,7 @@ async function handleSearchByMessageId(args) {
       $top: '10', // Usually only one match, but allow for edge cases
     };
 
-    console.error(`Searching for Message-ID: ${messageId}`);
+    log.debug(`Searching for Message-ID: ${messageId}`);
 
     const response = await callGraphAPI(
       accessToken,
@@ -1659,24 +1633,10 @@ async function handleSearchByMessageId(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 searching by Message-ID: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error searching by Message-ID: ${error.message}`);
   }
 }
 

package/email/send.js

@@ -10,6 +10,34 @@ const {
   formatDryRunPreview,
 } = require('../utils/safety');
 const { handleGetMailTips } = require('./mail-tips');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+
+/**
+ * Mail-tip issues that stop a send until the caller passes
+ * `acknowledgeWarnings: true` (#272). Custom tips and moderation are
+ * returned with the result but do not block.
+ */
+const BLOCKING_TIP_LABELS = {
+  outOfOffice: 'out of office',
+  mailboxFull: 'mailbox full',
+  deliveryRestricted: 'delivery restricted',
+  external: 'external recipient',
+  externalMembers: 'group with external members',
+};
+
+const DELIVERY_CAVEAT =
+  'Mail tips are M365-only: personal Outlook.com accounts return none, and no warnings is not proof the email will be delivered.';
+
+/**
+ * One line per blocking issue, e.g. "- a@b.com: mailbox full".
+ * @param {Array<{address: string, type: string}>} issues
+ * @returns {string}
+ */
+function formatBlockingIssues(issues) {
+  return issues
+    .map((issue) => `- ${issue.address}: ${BLOCKING_TIP_LABELS[issue.type]}`)
+    .join('\n');
+}
 
 /**
  * Send email handler
@@ -27,40 +55,20 @@ async function handleSendEmail(args) {
     saveToSentItems = true,
     dryRun = false,
     checkRecipients = false,
+    acknowledgeWarnings = false,
   } = args;
 
   // Validate required parameters
   if (!to) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Recipient (to) is required.',
-        },
-      ],
-    };
+    return toolError('Recipient (to) is required.');
   }
 
   if (!subject) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Subject is required.',
-        },
-      ],
-    };
+    return toolError('Subject is required.');
   }
 
   if (!body) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Body content is required.',
-        },
-      ],
-    };
+    return toolError('Body content is required.');
   }
 
   try {
@@ -122,7 +130,9 @@ async function handleSendEmail(args) {
       saveToSentItems,
     };
 
-    // Pre-send mail tips check
+    // Pre-send mail tips check. The tips are kept out of emailObject: only
+    // Graph message properties may go in the sendMail payload (#272).
+    let mailTips = null;
     if (checkRecipients) {
       const allAddresses = allRecipients.map((r) => r.emailAddress.address);
       const tipsResult = await handleGetMailTips({
@@ -130,27 +140,52 @@ async function handleSendEmail(args) {
       });
 
       const tipsText = tipsResult.content[0]?.text || '';
+      const blocking = (tipsResult._meta?.issues || []).filter(
+        (issue) => BLOCKING_TIP_LABELS[issue.type]
+      );
 
       // In dry-run mode, always include mail tips in the preview
       if (dryRun) {
         const preview = formatDryRunPreview(emailObject);
+        const refusalNote =
+          blocking.length > 0 && !acknowledgeWarnings
+            ? `\n\nNote: a real send would be refused until acknowledgeWarnings: true is passed, because of:\n${formatBlockingIssues(blocking)}`
+            : '';
         return {
           content: [
             {
               type: 'text',
-              text: `${tipsText}\n\n---\n\n${preview.content[0].text}`,
+              text: `${tipsText}\n\n---\n\n${preview.content[0].text}${refusalNote}`,
             },
           ],
           _meta: { mailTips: tipsResult._meta },
         };
       }
 
-      // In send mode, warn if there are issues but proceed
-      if (tipsResult._meta?.warningCount > 0) {
-        // Store tips to prepend to send response
-        emailObject._mailTipsText = tipsText;
-        emailObject._mailTipsMeta = tipsResult._meta;
+      // The caller asked for a check, so a failed check stops the send.
+      if (tipsResult.isError) {
+        return toolError(
+          `Email not sent: the recipient check failed.\n\n${tipsText}`,
+          tipsText.includes('Next step:')
+            ? {}
+            : {
+                nextStep:
+                  'Retry the call, or call send-email without checkRecipients to send without the check.',
+              }
+        );
       }
+
+      if (blocking.length > 0 && !acknowledgeWarnings) {
+        return toolError(
+          `Email not sent: the recipient check flagged ${blocking.length} issue(s):\n${formatBlockingIssues(blocking)}\n\n${tipsText}`,
+          {
+            nextStep:
+              'Show these warnings to the user. If they still want to send, call send-email again with the same arguments plus acknowledgeWarnings: true; otherwise change the recipients.',
+          }
+        );
+      }
+
+      mailTips = { text: tipsText, meta: tipsResult._meta, blocking };
     }
 
     // Dry-run mode: return preview without sending
@@ -168,34 +203,33 @@ async function handleSendEmail(args) {
     // Make API call to send email
     await callGraphAPI(accessToken, 'POST', 'me/sendMail', emailObject);
 
+    const sentText = `Email sent successfully!\n\nSubject: ${subject}\nRecipients: ${toRecipients.length}${ccRecipients.length > 0 ? ` + ${ccRecipients.length} CC` : ''}${bccRecipients.length > 0 ? ` + ${bccRecipients.length} BCC` : ''}\nMessage Length: ${body.length} characters`;
+
+    if (!mailTips) {
+      return { content: [{ type: 'text', text: sentText }] };
+    }
+
+    // Empty tips already carry their own M365-only note; don't repeat it.
+    const caveat = mailTips.meta?.allEmpty ? '' : `\n\n${DELIVERY_CAVEAT}`;
+    const acknowledged =
+      mailTips.blocking.length > 0
+        ? `\n\nSent with ${mailTips.blocking.length} acknowledged warning(s):\n${formatBlockingIssues(mailTips.blocking)}`
+        : '';
     return {
       content: [
         {
           type: 'text',
-          text: `Email sent successfully!\n\nSubject: ${subject}\nRecipients: ${toRecipients.length}${ccRecipients.length > 0 ? ` + ${ccRecipients.length} CC` : ''}${bccRecipients.length > 0 ? ` + ${bccRecipients.length} BCC` : ''}\nMessage Length: ${body.length} characters`,
+          text: `${sentText}${acknowledged}\n\n---\n\n${mailTips.text}${caveat}`,
         },
       ],
+      _meta: { mailTips: mailTips.meta },
     };
   } catch (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 sending email: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error sending email: ${error.message}`);
   }
 }
 

package/folder/create.js

@@ -5,6 +5,8 @@ const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolder, listChildFolders } = require('./resolve');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * Create folder handler
@@ -18,14 +20,7 @@ async function handleCreateFolder(args) {
   const sharedMailbox = args.sharedMailbox || args.email || null;
 
   if (!folderName) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Folder name is required.',
-        },
-      ],
-    };
+    return toolError('Folder name is required.');
   }
 
   try {
@@ -52,24 +47,10 @@ async function handleCreateFolder(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 creating folder: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error creating folder: ${error.message}`);
   }
 }
 
@@ -153,7 +134,7 @@ async function createMailFolder(accessToken, folderName, parentSpec) {
       };
     }
   } catch (error) {
-    console.error(`Error creating folder "${folderName}": ${error.message}`);
+    log.debug(`Error creating folder "${folderName}": ${error.message}`);
     throw error;
   }
 }