@littlebearapps/outlook-assistant 3.12.0 → 3.12.1

package/email/delta.js

@@ -63,19 +63,39 @@ function mailboxesConflict(tokenMailbox, prefix) {
   return isAddress(token) && isAddress(target);
 }
 
+const DEFAULT_PAGE_SIZE = 100;
+const MAX_PAGE_SIZE = 200;
+
+/**
+ * Turn the caller's `maxResults` into a delta page size: an integer from 1 to
+ * 200. Missing or non-numeric values give the default (100); fractions are
+ * floored; zero and negatives become 1; anything over 200 becomes 200.
+ * @param {*} value - Raw `maxResults` argument
+ * @returns {number} - Page size to request
+ */
+function clampPageSize(value) {
+  const n =
+    typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+  if (typeof n !== 'number' || !Number.isFinite(n)) {
+    return DEFAULT_PAGE_SIZE;
+  }
+  return Math.min(Math.max(Math.floor(n), 1), MAX_PAGE_SIZE);
+}
+
 /**
  * List emails delta handler - incremental sync
  * @param {object} args - Tool arguments
  * @param {string} [args.folder] - Folder to sync (default: inbox)
  * @param {string} [args.deltaToken] - Token from previous delta call (omit for initial sync)
- * @param {number} [args.maxResults] - Max results per page (default: 100)
+ * @param {number} [args.maxResults] - Page size, 1-200 (default: 100). Sent as
+ *   `Prefer: odata.maxpagesize` on every page; `$top` would cap the whole sync.
  * @param {string} [args.outputVerbosity] - Output detail level
  * @returns {object} - MCP response with emails, deltaToken, and change summary
  */
 async function handleListEmailsDelta(args) {
   const folder = args.folder || 'inbox';
   const deltaToken = args.deltaToken;
-  const maxResults = Math.min(args.maxResults || 100, 200);
+  const maxResults = clampPageSize(args.maxResults);
   const verbosity = args.outputVerbosity || 'standard';
   // Optional: scope the delta sync to a shared/delegated mailbox rather than
   // the signed-in account. Accepts a custom/localized folder name or path.
@@ -123,19 +143,19 @@ async function handleListEmailsDelta(args) {
           : { name: folder, mailbox: sharedMailbox }
       );
       endpoint = `${prefix}/mailFolders/${resolved.id}/messages/delta`;
-      queryParams = {
-        $select: getEmailFields('delta'),
-        $top: maxResults.toString(),
-      };
+      // No `$top`: on messages/delta it caps the whole sync, not the page.
+      queryParams = { $select: getEmailFields('delta') };
     }
 
-    // Fetch delta results
+    // Fetch delta results. Graph honours the page size only on requests that
+    // carry the Prefer header, so continuation calls must send it too.
     const response = await callGraphAPI(
       accessToken,
       'GET',
       endpoint,
       null,
-      deltaToken ? {} : queryParams
+      queryParams,
+      { Prefer: `odata.maxpagesize=${maxResults}` }
     );
 
     // Process results
@@ -237,7 +257,7 @@ async function handleListEmailsDelta(args) {
       // Pagination info
       if (hasMoreChanges) {
         resultText += `\n### More Pages Available\n`;
-        resultText += `This page returned a continuation token. Call \`search-emails deltaMode=true deltaToken=<token>\` again to fetch the next page. The real delta token only emits once paging completes.\n`;
+        resultText += `This page returned a continuation token. Call \`search-emails deltaMode=true deltaToken=<token>\` again to fetch the next page, and pass the same \`maxResults\` on every page to keep the page size. The real delta token only emits once paging completes.\n`;
       }
 
       // Token (delta or continuation)

package/email/draft.js

@@ -94,6 +94,51 @@ function formatDraftResponse(draft, actionLabel) {
   };
 }
 
+/**
+ * Raised when update/send/delete is pointed at something that is not an
+ * unsent draft. Carries the user-facing message; handleError turns it into
+ * a tool error without the generic "Error ..." prefix.
+ */
+class DraftGuardError extends Error {}
+
+/**
+ * Refuse to mutate anything that is not an unsent draft. Graph's PATCH,
+ * DELETE and /send accept any message id, so without this check a received
+ * or sent message could be edited, deleted or re-sent (#246).
+ * @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)
+ * @throws {DraftGuardError} If the id is not a draft or does not exist
+ */
+async function assertIsDraft(accessToken, id, action) {
+  let message;
+  try {
+    message = await callGraphAPI(
+      accessToken,
+      'GET',
+      `me/messages/${id}`,
+      null,
+      {
+        $select: 'id,isDraft,subject',
+      }
+    );
+  } catch (error) {
+    if (/status 404\b|ErrorItemNotFound/.test(error.message)) {
+      throw new DraftGuardError(
+        `Draft not found: \`${id}\`. It may already have been sent or deleted, or the ID is wrong.`
+      );
+    }
+    throw error;
+  }
+
+  if (message?.isDraft !== true) {
+    const subject = message?.subject ? ` ("${message.subject}")` : '';
+    throw new DraftGuardError(
+      `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.`
+    );
+  }
+}
+
 /**
  * Draft handler — routes to action-specific logic
  * @param {object} args - Tool arguments
@@ -242,12 +287,14 @@ async function handleUpdateDraft(args) {
     if (allowlistError) return allowlistError;
   }
 
-  // Rate limit check
-  const rateLimitError = checkRateLimit('draft');
-  if (rateLimitError) return rateLimitError;
-
   try {
     const accessToken = await ensureAuthenticated();
+    // Refusals must not consume a rate-limit slot, so check before counting
+    await assertIsDraft(accessToken, id, 'update');
+
+    const rateLimitError = checkRateLimit('draft');
+    if (rateLimitError) return rateLimitError;
+
     const draft = await callGraphAPI(
       accessToken,
       'PATCH',
@@ -272,12 +319,14 @@ async function handleSendDraft(args) {
     };
   }
 
-  // Rate limit via send-email counter (shares limit with direct sends)
-  const rateLimitError = checkRateLimit('send-email');
-  if (rateLimitError) return rateLimitError;
-
   try {
     const accessToken = await ensureAuthenticated();
+    await assertIsDraft(accessToken, id, 'send');
+
+    // Rate limit via send-email counter (shares limit with direct sends)
+    const rateLimitError = checkRateLimit('send-email');
+    if (rateLimitError) return rateLimitError;
+
     await callGraphAPI(accessToken, 'POST', `me/messages/${id}/send`);
     return {
       content: [
@@ -308,12 +357,13 @@ async function handleDeleteDraft(args) {
 
   try {
     const accessToken = await ensureAuthenticated();
+    await assertIsDraft(accessToken, id, 'delete');
     await callGraphAPI(accessToken, 'DELETE', `me/messages/${id}`);
     return {
       content: [
         {
           type: 'text',
-          text: `Draft \`${id}\` deleted.`,
+          text: `Draft \`${id}\` deleted. It skips Deleted Items and goes to Recoverable Items, where Outlook's "Recover deleted items" can restore it for a limited time, depending on your account.`,
         },
       ],
     };
@@ -458,6 +508,13 @@ async function handleForwardDraft(args) {
  * Standard error handler
  */
 function handleError(actionLabel, error) {
+  if (error instanceof DraftGuardError) {
+    return {
+      content: [{ type: 'text', text: error.message }],
+      isError: true,
+    };
+  }
+
   if (error.message === 'Authentication required') {
     return {
       content: [

package/email/export.js

@@ -18,7 +18,9 @@ const {
 const { getEmailFields } = require('../utils/field-presets');
 const { resolveFolderPath } = require('./folder-utils');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { quoteSearchPhrase } = require('../utils/odata-helpers');
 const { safeAttachmentFilename } = require('./attachments');
+const { writeClaimedFile } = require('../utils/safe-write');
 
 // Export format constants
 const EXPORT_FORMATS = {
@@ -336,7 +338,7 @@ async function handleBatchExportEmails(args) {
         outputDir,
         `batch_export_${timestamp}`,
         'csv',
-        new Set(),
+        null,
         csvContent,
         'utf8'
       );
@@ -513,7 +515,7 @@ async function searchEmailsForExport(accessToken, query, mailbox = null) {
     searchParts.push(`subject:${query.subject}`);
   }
   if (searchParts.length > 0) {
-    params.$search = `"${searchParts.join(' ')}"`;
+    params.$search = quoteSearchPhrase(searchParts.join(' '));
     delete params.$orderby; // Can't combine $search with $orderby
   }
 
@@ -694,7 +696,7 @@ async function saveAttachments(
           outputDir,
           `${messageTag(emailId)}_${base}`,
           extension,
-          claimedPaths || new Set(),
+          claimedPaths,
           buffer
         );
         saved.push({
@@ -728,82 +730,6 @@ function filenameTimestamp(isoDateTime) {
   return parsed.toISOString().slice(0, 19).replace(/[:.]/g, '-');
 }
 
-/**
- * Claim a not-yet-used path in `outputDir`, appending `_2`, `_3`, ... until the
- * name is free both on disk and among the paths already claimed in this batch.
- *
- * Silent overwrite is the dangerous part of the collision defect: the exporter
- * reported `Successful N / Failed 0` while messages vanished. Never overwrite —
- * disambiguate instead, and let the caller reconcile via the manifest.
- *
- * The claim is synchronous, so it is atomic with respect to the event loop and
- * safe under the batch exporter's 4-way concurrency even though the write
- * itself happens after an await.
- *
- * @param {string} outputDir - Target directory
- * @param {string} base - Filename without extension
- * @param {string} extension - Extension without a leading dot
- * @param {Set<string>} claimed - Paths already claimed by this batch
- * @returns {string} - An unused absolute path, now claimed
- */
-function claimUniquePath(outputDir, base, extension, claimed) {
-  const root = path.resolve(outputDir);
-  const ext = extension ? `.${extension}` : '';
-  let candidate = path.join(root, `${base}${ext}`);
-  let suffix = 1;
-  while (claimed.has(candidate) || pathEntryExists(candidate)) {
-    suffix += 1;
-    candidate = path.join(root, `${base}_${suffix}${ext}`);
-  }
-  // Names are built from sanitised parts, but confine defensively anyway.
-  if (path.dirname(candidate) !== root) {
-    throw new Error('Refusing to write export file outside outputDir');
-  }
-  claimed.add(candidate);
-  return candidate;
-}
-
-/**
- * Like fs.existsSync, but a dangling symlink counts as existing (existsSync
- * follows the link and reports false).
- * @param {string} candidate
- * @returns {boolean}
- */
-function pathEntryExists(candidate) {
-  try {
-    fs.lstatSync(candidate);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Claim a unique name in `outputDir` and write `data` to it exclusively. The
- * `wx` flag fails on any existing entry — including a dangling symlink planted
- * after the claim — so an export never overwrites a file or follows a link;
- * on EEXIST the next suffix is claimed instead.
- * @param {string} outputDir - Target directory
- * @param {string} base - Filename without extension (already sanitised)
- * @param {string} extension - Extension without a leading dot ('' for none)
- * @param {Set<string>} claimed - Paths already claimed by this export
- * @param {string|Buffer} data - File contents
- * @param {string} [encoding] - Encoding for string data
- * @returns {string} - Absolute path actually written
- */
-function writeClaimedFile(outputDir, base, extension, claimed, data, encoding) {
-  for (let attempt = 0; attempt < 1000; attempt++) {
-    const candidate = claimUniquePath(outputDir, base, extension, claimed);
-    try {
-      fs.writeFileSync(candidate, data, { encoding, flag: 'wx' });
-      return candidate;
-    } catch (error) {
-      if (error.code !== 'EEXIST') throw error;
-    }
-  }
-  throw new Error(`Too many files named ${base} in ${outputDir}`);
-}
-
 /**
  * Short, filesystem-safe tag for a message id. Graph ids in one mailbox share
  * a long common prefix and are caller-supplied, so neither a raw prefix nor

package/email/folder-utils.js

@@ -1,7 +1,6 @@
 /**
  * Email folder utilities
  */
-const { callGraphAPI } = require('../utils/graph-api');
 const { resolveFolder, looksLikeFolderId } = require('../folder/resolve');
 const { buildMailboxPrefix } = require('../utils/mailbox');
 
@@ -111,129 +110,7 @@ async function resolveFolderPath(accessToken, folderName, mailbox = null) {
   }
 }
 
-/**
- * Get the ID of a mail folder by its name
- * @param {string} accessToken - Access token
- * @param {string} folderName - Name of the folder to find
- * @returns {Promise<string|null>} - Folder ID or null if not found
- */
-async function getFolderIdByName(accessToken, folderName) {
-  try {
-    // First try with exact match filter
-    console.error(`Looking for folder with name "${folderName}"`);
-    const response = await callGraphAPI(
-      accessToken,
-      'GET',
-      'me/mailFolders',
-      null,
-      { $filter: `displayName eq '${folderName}'` }
-    );
-
-    if (response.value && response.value.length > 0) {
-      console.error(
-        `Found folder "${folderName}" with ID: ${response.value[0].id}`
-      );
-      return response.value[0].id;
-    }
-
-    // If exact match fails, try to get all folders and do a case-insensitive comparison
-    console.error(
-      `No exact match found for "${folderName}", trying case-insensitive search`
-    );
-    const allFoldersResponse = await callGraphAPI(
-      accessToken,
-      'GET',
-      'me/mailFolders',
-      null,
-      { $top: 100 }
-    );
-
-    if (allFoldersResponse.value) {
-      const lowerFolderName = folderName.toLowerCase();
-      const matchingFolder = allFoldersResponse.value.find(
-        (folder) => folder.displayName.toLowerCase() === lowerFolderName
-      );
-
-      if (matchingFolder) {
-        console.error(
-          `Found case-insensitive match for "${folderName}" with ID: ${matchingFolder.id}`
-        );
-        return matchingFolder.id;
-      }
-    }
-
-    console.error(`No folder found matching "${folderName}"`);
-    return null;
-  } catch (error) {
-    console.error(`Error finding folder "${folderName}": ${error.message}`);
-    return null;
-  }
-}
-
-/**
- * Get all mail folders
- * @param {string} accessToken - Access token
- * @returns {Promise<Array>} - Array of folder objects
- */
-async function getAllFolders(accessToken) {
-  try {
-    // Get top-level folders
-    const response = await callGraphAPI(
-      accessToken,
-      'GET',
-      'me/mailFolders',
-      null,
-      {
-        $top: 100,
-        $select:
-          'id,displayName,parentFolderId,childFolderCount,totalItemCount,unreadItemCount',
-      }
-    );
-
-    if (!response.value) {
-      return [];
-    }
-
-    // Get child folders for folders with children
-    const foldersWithChildren = response.value.filter(
-      (f) => f.childFolderCount > 0
-    );
-
-    const childFolderPromises = foldersWithChildren.map(async (folder) => {
-      try {
-        const childResponse = await callGraphAPI(
-          accessToken,
-          'GET',
-          `me/mailFolders/${folder.id}/childFolders`,
-          null,
-          {
-            $select:
-              'id,displayName,parentFolderId,childFolderCount,totalItemCount,unreadItemCount',
-          }
-        );
-
-        return childResponse.value || [];
-      } catch (error) {
-        console.error(
-          `Error getting child folders for "${folder.displayName}": ${error.message}`
-        );
-        return [];
-      }
-    });
-
-    const childFolders = await Promise.all(childFolderPromises);
-
-    // Combine top-level folders and all child folders
-    return [...response.value, ...childFolders.flat()];
-  } catch (error) {
-    console.error(`Error getting all folders: ${error.message}`);
-    return [];
-  }
-}
-
 module.exports = {
   WELL_KNOWN_FOLDERS,
   resolveFolderPath,
-  getFolderIdByName,
-  getAllFolders,
 };

package/email/index.js

@@ -48,7 +48,7 @@ const emailTools = [
         deltaMode: {
           type: 'boolean',
           description:
-            'Enable delta sync mode. Returns only changes since last sync. Use deltaToken for subsequent calls. Honors `sharedMailbox`/`email` (and custom `folder` paths) to sync within a shared/delegated mailbox.',
+            'Enable delta sync mode. Returns only changes since last sync. Use deltaToken for subsequent calls; an initial sync larger than `maxResults` arrives over several pages, each returning a continuation token to pass back until a delta token is returned. Honors `sharedMailbox`/`email` (and custom `folder` paths) to sync within a shared/delegated mailbox.',
         },
         internetMessageId: {
           type: 'string',
@@ -58,7 +58,7 @@ const emailTools = [
         conversationId: {
           type: 'string',
           description:
-            'Get all messages in a conversation thread by conversationId. Honors `sharedMailbox`/`email` to thread within a shared/delegated mailbox.',
+            'Get the messages in a conversation thread by conversationId, oldest first (up to 100; a longer thread is marked truncated — use `export target=conversation` for up to 1000). Honors `sharedMailbox`/`email` to thread within a shared/delegated mailbox.',
         },
         groupByConversation: {
           type: 'boolean',
@@ -74,7 +74,7 @@ const emailTools = [
         searchExpression: {
           type: 'string',
           description:
-            'Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text.',
+            'Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases, escaping any `"` or `\\` inside them with a backslash; a single bare token is auto-quoted and escaped for you. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: personal Outlook.com accounts reject field-scoped `$search` outright; since v3.10.0 recognised `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried automatically (a `subject:` term becomes a substring match, so it is close but not identical) (reported as strategy `raw-kql-translated`). Expressions that cannot be translated exactly — free text, `AND`/`OR`, unknown prefixes — are not retried, so use `query` for those there. RELEVANCE, NOT RECENCY: an untranslated expression is answered by Graph `$search` over the whole message including the body, ranked by relevance and not sorted by date, so top hits can look unrelated to a caller expecting a subject match. `query` is the more predictable choice for a term you expect in a subject line; `searchExpression` is the one that reaches body text.',
         },
         kqlQuery: {
           type: 'string',
@@ -147,7 +147,7 @@ const emailTools = [
         maxResults: {
           type: 'number',
           description:
-            'Max results per page for delta sync (default: 100, max: 200)',
+            'Delta sync page size (deltaMode only): 1-200, default 100, sent to Graph as the `Prefer: odata.maxpagesize` header. It sizes each page, not the whole sync: while a page returns a continuation token, keep calling with that token until a delta token is returned, and pass the same `maxResults` on every page (an omitted value means 100).',
         },
         // Conversation params
         includeHeaders: {
@@ -327,7 +327,7 @@ const emailTools = [
   {
     name: 'draft',
     description:
-      'Full draft lifecycle for review-before-send workflows (destructive: covers `send` and `delete`). action=`create` saves a new draft in the Drafts folder and returns its id (use `dryRun: true` to preview without saving; `checkRecipients: true` runs mail-tips first). action=`update` patches an existing draft by `id` (only fields passed are changed). action=`send` dispatches an existing draft — shares the rate limit with `send-email`. action=`delete` removes a draft permanently. action=`reply`/`reply-all` creates a reply draft from a message `id` (use `comment` to prepend text — mutually exclusive with `body`). action=`forward` creates a forward draft (requires `id` and `to`). Recipient allowlist applies to create/update/forward. Returns the draft object on create/update/reply/forward; status confirmation on send/delete.',
+      'Full draft lifecycle for review-before-send workflows (destructive: covers `send` and `delete`). action=`create` saves a new draft in the Drafts folder and returns its id (use `dryRun: true` to preview without saving; `checkRecipients: true` runs mail-tips first). action=`update` patches an existing draft by `id` (only fields passed are changed). action=`send` dispatches an existing draft — shares the rate limit with `send-email`. action=`delete` deletes a draft: it skips Deleted Items and goes to Recoverable Items (restorable for a limited time, depending on your account, via "Recover deleted items" in Outlook). update/send/delete refuse any `id` that is not an unsent draft (received or sent messages are never changed). action=`reply`/`reply-all` creates a reply draft from a message `id` (use `comment` to prepend text — mutually exclusive with `body`). action=`forward` creates a forward draft (requires `id` and `to`). Recipient allowlist applies to create/update/forward. Returns the draft object on create/update/reply/forward; status confirmation on send/delete.',
     annotations: {
       title: 'Draft Operations',
       readOnlyHint: false,
@@ -354,7 +354,7 @@ const emailTools = [
         id: {
           type: 'string',
           description:
-            'Draft or message ID. Required for update/send/delete/reply/reply-all/forward.',
+            'Draft or message ID. Required for update/send/delete/reply/reply-all/forward. update/send/delete need a draft ID; reply/reply-all/forward take any message ID.',
         },
         to: {
           type: 'string',
@@ -406,7 +406,7 @@ const emailTools = [
   {
     name: 'update-email',
     description:
-      'Update message state without modifying content (idempotent — safe to retry). action=`mark-read`/`mark-unread` toggles the `isRead` flag on a single message by `id`. action=`flag` sets a follow-up flag with optional `dueDateTime`/`startDateTime` (ISO 8601). action=`unflag` clears the flag. action=`complete` marks the flag as done. Flag/unflag/complete accept either `id` (single) or `ids` (batch array) — batch operations use Graph `$batch` for efficiency. Pass `sharedMailbox` (or alias `email`) to update messages in a shared/delegated mailbox instead of the signed-in account (requires Mail.ReadWrite.Shared + delegate access). Returns status confirmation per message.',
+      'Update message state without modifying content (idempotent — safe to retry). action=`mark-read`/`mark-unread` toggles the `isRead` flag on a single message by `id`. action=`flag` sets a follow-up flag with optional `dueDateTime`/`startDateTime` (ISO 8601 with a time: a value with `Z` or a ±hh:mm offset is kept as that exact instant; a value without one is read in the configured default timezone (OUTLOOK_DEFAULT_TIMEZONE); date-only or unparseable values are refused before any change). With only `dueDateTime`, the start defaults to 09:00 on the due date in the default timezone, or to the due time if that is earlier. action=`unflag` clears the flag. action=`complete` marks the flag as done. Flag/unflag/complete accept either `id` (single) or `ids` (batch array) — messages in a batch are updated one at a time (one PATCH each, not Graph `$batch`). Pass `sharedMailbox` (or alias `email`) to update messages in a shared/delegated mailbox instead of the signed-in account (requires Mail.ReadWrite.Shared + delegate access). Returns status confirmation per message.',
     annotations: {
       title: 'Update Email',
       readOnlyHint: false,
@@ -436,11 +436,13 @@ const emailTools = [
         // Flag params
         dueDateTime: {
           type: 'string',
-          description: 'Due date/time for follow-up, ISO 8601 (action=flag)',
+          description:
+            'Due date/time for follow-up (action=flag). ISO 8601 with a time: "2026-03-01T09:00:00Z" or "2026-03-01T09:00:00+10:00" is that exact instant; "2026-03-01T09:00:00" (no zone) is read in the default timezone (OUTLOOK_DEFAULT_TIMEZONE).',
         },
         startDateTime: {
           type: 'string',
-          description: 'Start date/time for follow-up, ISO 8601 (action=flag)',
+          description:
+            'Start date/time for follow-up (action=flag), same format as dueDateTime. Defaults to 09:00 on the due date in the default timezone (capped at the due time) when only dueDateTime is given.',
         },
         sharedMailbox: {
           type: 'string',
@@ -575,7 +577,7 @@ const emailTools = [
   {
     name: 'export',
     description:
-      'Export emails to file formats for archival, forensics, or programmatic processing. target=`message` (default) exports a single email by `id` to `savePath` — accepts `mime`/`eml`/`markdown`/`json`/`csv`. target=`messages` batch-exports either an explicit `emailIds` array or messages matching `searchQuery` (or `query` shortcut) into `outputDir` — accepts `markdown`/`json`/`csv`. target=`conversation` exports a full thread by `conversationId` into `outputDir` (chronological by default; pass `order: "reverse"` for newest-first) — accepts `eml`/`mbox`/`markdown`/`json`/`html`/`csv`. target=`mime` returns raw RFC-822 MIME bytes for `id` (use `headersOnly` for just headers, `base64` for encoded transport, `maxSize` to cap at default 1MB). All targets accept `sharedMailbox` (alias `email`) to export from a shared/delegated mailbox instead of the signed-in account — pass it whenever the id(s)/conversationId/searchQuery come from a shared mailbox, or exports fail with 404 ErrorInvalidMailboxItemId. `includeAttachments` defaults to true for single-message exports and false for batch. Format support varies by target — see the format param enum.',
+      'Export emails to file formats for archival, forensics, or programmatic processing. target=`message` (default) exports a single email by `id` to `savePath` — accepts `mime`/`eml`/`markdown`/`json`/`csv`. target=`messages` batch-exports either an explicit `emailIds` array or messages matching `searchQuery` (or `query` shortcut) into `outputDir` — accepts `markdown`/`json`/`csv`. target=`conversation` exports a full thread (up to 1000 messages) by `conversationId` into `outputDir` (chronological by default; pass `order: "reverse"` for newest-first) — accepts `eml`/`mbox`/`markdown`/`json`/`html`/`csv`. target=`mime` returns raw RFC-822 MIME bytes for `id` (use `headersOnly` for just headers, `base64` for encoded transport, `maxSize` to cap at default 1MB). All targets accept `sharedMailbox` (alias `email`) to export from a shared/delegated mailbox instead of the signed-in account — pass it whenever the id(s)/conversationId/searchQuery come from a shared mailbox, or exports fail with 404 ErrorInvalidMailboxItemId. `includeAttachments` defaults to true for single-message exports and false for batch. Format support varies by target — see the format param enum.',
     annotations: {
       title: 'Export Emails',
       readOnlyHint: false,

package/email/search.js

@@ -14,7 +14,11 @@ const {
   DEFAULT_LIMITS,
 } = require('../utils/response-formatter');
 const { getEmailFields } = require('../utils/field-presets');
-const { escapeODataString } = require('../utils/odata-helpers');
+const {
+  escapeODataString,
+  escapeSearchPhrase,
+  quoteSearchPhrase,
+} = require('../utils/odata-helpers');
 
 // Upper bound on how many recent messages the client-side fallback scans
 // before giving up. Deliberately DECOUPLED from the requested result count so
@@ -328,12 +332,13 @@ async function progressiveSearch(
       trimmedKql.includes(':') || /\s/.test(trimmedKql);
     // Already-quoted phrases and KQL-looking expressions (field syntax
     // or multi-word) are passed through as-is; only bare single tokens
-    // are wrapped so Graph treats them as phrase searches.
+    // are wrapped so Graph treats them as phrase searches. The wrapped
+    // token's own `"` and `\` are escaped so they cannot end the phrase. (#251)
     let kqlForSearch;
     if (alreadyQuoted || looksLikeExpression) {
       kqlForSearch = trimmedKql;
     } else {
-      kqlForSearch = `"${trimmedKql}"`;
+      kqlForSearch = `"${escapeSearchPhrase(trimmedKql)}"`;
     }
 
     // Graph rejects field-scoped expressions outright on personal accounts
@@ -1212,7 +1217,7 @@ function buildSearchParams(searchTerms, filterTerms, count, selectFields) {
 
   // Handle search terms - use $search only for free-text query
   if (searchTerms.query) {
-    params.$search = `"${searchTerms.query}"`;
+    params.$search = quoteSearchPhrase(searchTerms.query);
   }
 
   // Build filter conditions array - use $filter for structured fields (more reliable)

package/folder/index.js

@@ -12,7 +12,7 @@ const folderTools = [
   {
     name: 'folders',
     description:
-      "Manage mail folders (tool-level destructiveHint=true because `delete` permanently removes a folder; `list` and `stats` are read-only sub-actions despite the annotation). Folders can be addressed by name, by a slash-separated PATH for nested folders (e.g. `Triage/Delete`, `Inbox/Clients/Acme`, case-insensitive), or by explicit ID; `list` output includes each folder's full path and `[id: …]`. A bare name resolves a unique top-level folder first, then searches nested folders (ambiguous names return the candidates — disambiguate with a path or ID). action=`list` (default) returns the folder tree (toggle `includeItemCounts` for unread/total, `includeChildren` for hierarchy). action=`create` makes a new folder under the root, or under `parentFolder` (name/path) / `parentFolderId`, and returns its id. action=`move` relocates emails (`emailIds`) into `targetFolder` (name/path) or `targetFolderId`. action=`stats` returns counts (totalItemCount/unreadItemCount) for `folder` (name/path) or `folderId`, suitable for pagination planning. action=`delete` removes a folder (by `folderName`/path or `folderId`) and its contents — on Outlook.com the folder is moved to Deleted Items (recoverable until you empty it); M365/Exchange accounts may hard-delete per retention policy. Every action accepts `sharedMailbox` (alias `email`) to target a shared/delegated mailbox instead of the signed-in account — folder names, paths, and IDs are then resolved inside that mailbox. Protected folders cannot be deleted in any mailbox.",
+      "Manage mail folders (tool-level destructiveHint=true because `delete` removes a folder and its contents; `list` and `stats` are read-only sub-actions despite the annotation). Folders can be addressed by name, by a slash-separated PATH for nested folders (e.g. `Triage/Delete`, `Inbox/Clients/Acme`, case-insensitive), or by explicit ID; `list` output includes each folder's full path and `[id: …]`. A bare name resolves a unique top-level folder first, then searches nested folders (ambiguous names return the candidates — disambiguate with a path or ID). action=`list` (default) returns the folder tree (toggle `includeItemCounts` for unread/total, `includeChildren` for hierarchy). action=`create` makes a new folder under the root, or under `parentFolder` (name/path) / `parentFolderId`, and returns its id. action=`move` relocates emails (`emailIds`) into `targetFolder` (name/path) or `targetFolderId`. action=`stats` returns counts (totalItemCount/unreadItemCount) for `folder` (name/path) or `folderId`, suitable for pagination planning. action=`delete` removes a folder (by `folderName`/path or `folderId`) and its contents — it does not go to Deleted Items, and Graph doesn't document whether it can be restored (some accounts may offer Outlook's \"Recover deleted items\" for a limited time, but don't rely on it), so move out anything you might need first. Every action accepts `sharedMailbox` (alias `email`) to target a shared/delegated mailbox instead of the signed-in account — folder names, paths, and IDs are then resolved inside that mailbox. Protected folders cannot be deleted in any mailbox.",
     annotations: {
       title: 'Mail Folders',
       readOnlyHint: false,

package/folder/resolve.js

@@ -1,9 +1,10 @@
 /**
  * Shared, path-aware, ambiguity-aware mail-folder resolver. (#216)
  *
- * Replaces the two top-level-only resolvers (`getFolderIdByName` in
+ * Replaced the top-level-only resolvers (`getFolderIdByName` in
  * email/folder-utils.js and `resolveFolderName` in folder/stats.js) that could
- * not address nested folders. Accepts, in priority order:
+ * not address nested folders (manage-rules folder actions use it since #248).
+ * Accepts, in priority order:
  *   1. an explicit folder ID (never guessed from a name),
  *   2. a well-known alias (inbox, archive, sent, ...),
  *   3. a folder PATH like "Triage/Delete" or "Inbox/Clients/Acme"

package/index.js

@@ -35,8 +35,16 @@ Key environment variables:
   OUTLOOK_CLIENT_SECRET             Client secret VALUE (not the Secret ID)
   OUTLOOK_AUTH_METHOD               device-code (default) | browser
   OUTLOOK_AUTH_AUDIENCE             common | consumers | organizations | <tenant-guid>
-  OUTLOOK_MAX_EMAILS_PER_SESSION    Cap on sends per session
+  OUTLOOK_SHARED_MAILBOX            Opt in to shared mailboxes: read | true (work/school only)
   OUTLOOK_ALLOWED_RECIPIENTS        Comma-separated recipient allowlist
+  OUTLOOK_MAX_EMAILS_PER_SESSION    Default cap per session for every rate-limited tool
+                                    (send-email, draft, manage-rules); 0 or unset = no cap
+  OUTLOOK_MAX_<TOOL>_PER_SESSION    Per-tool cap overriding the default, tool name in upper
+                                    case with _ for -, e.g. OUTLOOK_MAX_SEND_EMAIL_PER_SESSION
+  OUTLOOK_DEFAULT_TIMEZONE          IANA timezone for event times (default Australia/Melbourne)
+  OUTLOOK_IMMUTABLE_IDS             Set to "true" for message IDs that survive folder moves
+  OUTLOOK_SEARCH_SCAN_LIMIT         Local search fallback window (default 500, max 5000)
+  OUTLOOK_REQUEST_TIMEOUT_MS        Graph request inactivity timeout (default 60000)
   USE_TEST_MODE                     Set to "true" to run against mock data
 
 Documentation: https://github.com/littlebearapps/outlook-assistant`;

package/llms.txt

@@ -83,6 +83,6 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/faq.md): Frequently asked questions — install, accounts, permissions, tokens, send safety, updates, uninstall (also at <https://littlebearapps.com/help/outlook-assistant/faq/>)
 - [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
 - [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
-- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.12.0 — opt-in shared-mailbox read and organise support via `sharedMailbox` and `OUTLOOK_SHARED_MAILBOX` (#228), `list-events` `startAfter`/`startBefore`/`subject` filters (#193), token refresh requesting the granted scopes plus `offline_access` (#241), and two security fixes: dot segments in resource paths rejected, `export` writes confined to the output directory. Preceded by v3.11.2 — security release: attachment downloads confined to `outputDir` (GHSA-755c-c45g-69rv) and the access token only ever sent to Microsoft Graph (GHSA-mqfm-wfjq-jxq2); v3.11.1 — search and export correctness (filters combined with dates no longer silently dropped, batch export no longer overwrites same-day reply chains); v3.11.0 — `--version`/`--help` CLI flags (#68) and the `AADSTS7000215` Secret ID vs Value explanation (#69); v3.10.0 — search correctness (#217, #229, #230, #231))
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.12.1 — Graph reliability and correctness fixes: throttling retries, a request inactivity timeout and a 4-request concurrency cap (#244), complete delta paging (#254), a draft-only guard on `draft` update/send/delete (#246), nested folder paths in `manage-rules` (#248), flag dates honouring `Z` and offsets (#247), attendee types kept on `manage-event update` (#249), no "via API" text on decline/cancel (#242), escaped `$search` phrases (#251), and conversation read/export working on personal accounts. Preceded by v3.12.0 — opt-in shared-mailbox read and organise support via `sharedMailbox` and `OUTLOOK_SHARED_MAILBOX` (#228), `list-events` `startAfter`/`startBefore`/`subject` filters (#193), token refresh requesting the granted scopes plus `offline_access` (#241), and two security fixes: dot segments in resource paths rejected, `export` writes confined to the output directory. Preceded by v3.11.2 — security release: attachment downloads confined to `outputDir` (GHSA-755c-c45g-69rv) and the access token only ever sent to Microsoft Graph (GHSA-mqfm-wfjq-jxq2); v3.11.1 — search and export correctness (filters combined with dates no longer silently dropped, batch export no longer overwrites same-day reply chains); v3.11.0 — `--version`/`--help` CLI flags (#68) and the `AADSTS7000215` Secret ID vs Value explanation (#69); v3.10.0 — search correctness (#217, #229, #230, #231))
 - [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.12.x tool description audit, v3.8.x carry-over, v3.13.0+ new Graph APIs)
-- [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls
+- [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy (report vulnerabilities privately via GitHub private vulnerability reporting; acknowledged within 7 days), token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.12.0",
+  "version": "3.12.1",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 22 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",