@littlebearapps/outlook-assistant 3.11.0 → 3.11.1

package/.env.example

@@ -24,6 +24,13 @@ USE_TEST_MODE=false
 # Optional: Enable immutable IDs (IDs persist through folder moves)
 # OUTLOOK_IMMUTABLE_IDS=true
 
+# How many recent messages the client-side search fallback scans before giving
+# up. Personal Outlook.com rejects the server-side recipient filter, so a `to`
+# search is matched locally within this window — on a large archive the default
+# silently excludes older mail. Max 5000. Pair `to` with receivedAfter/
+# receivedBefore rather than raising this if you can.
+# OUTLOOK_SEARCH_SCAN_LIMIT=500
+
 # Optional: Default authentication method (device-code or browser)
 # device-code: No auth server needed, works remotely/headless
 # browser: Traditional OAuth redirect via localhost:3333

package/README.md

@@ -164,7 +164,7 @@ npx @littlebearapps/outlook-assistant
 To check which version you have, or to see the available options:
 
 ```bash
-outlook-assistant --version     # prints e.g. 3.11.0
+outlook-assistant --version     # prints e.g. 3.11.1
 outlook-assistant --help        # usage, options and key environment variables
 ```
 
@@ -366,6 +366,7 @@ USE_TEST_MODE=false
 | `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone applied to calendar events when callers don't pass one (e.g. `Europe/London`, `America/New_York`). | `Australia/Melbourne` |
 | `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on `send-email` + `draft send` per MCP server lifetime. | unlimited |
 | `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of domains/addresses for sends, drafts, and rule forwards. | unrestricted |
+| `OUTLOOK_SEARCH_SCAN_LIMIT` | How many recent messages the client-side search fallback scans. Personal accounts match `to` locally within this window, so the default caps how far back a `to` search reaches. Max 5000. | `500` |
 
 ### MCP Client Configuration
 
@@ -523,7 +524,7 @@ USE_TEST_MODE=true npm start
 | [Getting Started](docs/how-to/getting-started/connect-outlook-to-claude.md) | Install, configure, and authenticate — start here |
 | [Azure Setup Guide](docs/guides/azure-setup.md) | Azure account creation, app registration, permissions, and secrets |
 | [How-To Guides](docs/how-to/index.md) | 29 practical guides for email, calendar, contacts, and settings |
-| [Roadmap](ROADMAP.md) | Active milestones (v3.11.1, v3.8.x, v3.12.0+) and recent releases |
+| [Roadmap](ROADMAP.md) | Active milestones (v3.11.2, v3.8.x, v3.12.0+) and recent releases |
 | [Troubleshooting & FAQ](docs/how-to/getting-started/verify-your-connection.md#common-connection-problems) | Common problems, re-authentication, and frequently asked questions |
 | [Tools Reference](docs/quickrefs/tools-reference.md) | All 22 tools with parameters |
 | [AI Agent Guide](docs/how-to/ai-agents/using-outlook-assistant-in-agents.md) | Tool selection and workflow patterns for AI agents |
@@ -532,7 +533,8 @@ Full documentation: [docs/](docs/README.md)
 
 ## Known Limitations
 
-- **Personal account search**: Free-text `query` and the raw `searchExpression` (formerly `kqlQuery`) rely on Microsoft's `$search` API, which has limited support on personal Outlook.com accounts. `query` mitigates this with progressive fallback (OData filters, boolean filters, then a client-side scan). Field-scoped `$search` (e.g. `subject:"…"`) is rejected outright there; since v3.10.0 `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried, but boolean operators, grouping, wildcards and other field prefixes are not — those still terminate with an explicit no-results rather than a silent broader search. Structured filters (`from`, `subject`, `to`, `receivedAfter`) remain the most direct route. Cross-folder search (`searchAllFolders: true`) returns a superset of inbox-only results.
+- **Personal account search**: Free-text `query` and the raw `searchExpression` (formerly `kqlQuery`) rely on Microsoft's `$search` API, which has limited support on personal Outlook.com accounts. `query` mitigates this with progressive fallback (OData filters, boolean filters, then a client-side scan). Field-scoped `$search` (e.g. `subject:"…"`) is rejected outright there; since v3.10.0 `from:`/`to:`/`subject:` expressions are translated into the closest equivalent OData filters and retried, but boolean operators, grouping, wildcards and other field prefixes are not — those still terminate with an explicit no-results rather than a silent broader search. Structured filters (`from`, `subject`, `to`, `receivedAfter`) remain the most direct route. Cross-folder search (`searchAllFolders: true`) returns a superset of inbox-only results. Note that `query` and `searchExpression` are not interchangeable there: `searchExpression` goes to `$search`, which matches the whole message including the body and ranks by relevance rather than date, while `query` falls back to a subject substring match that never reads bodies.
+- **`to` search depth on personal accounts**: the server-side recipient filter is rejected, so `to` is matched locally over the 500 most recent messages (`OUTLOOK_SEARCH_SCAN_LIMIT`, max 5000). On a large archive that excludes older mail — pair `to` with `receivedAfter`/`receivedBefore`. Since v3.11.1 the response says so whenever the scan was truncated, whether or not it matched.
 - **Focused Inbox**: Only available on work/school Microsoft 365 accounts.
 - **Shared mailboxes**: Require `Mail.Read.Shared` permission and a work/school account.
 - **Meeting room search**: Requires `Place.Read.All` permission with admin consent (work/school accounts only).

package/email/export.js

@@ -78,26 +78,32 @@ async function handleExportEmail(args) {
       };
     }
 
-    // Generate filename based on email metadata
-    const timestamp = new Date(email.receivedDateTime)
-      .toISOString()
-      .slice(0, 10);
+    // Generate filename based on email metadata. The time matters: a
+    // date-only name collides across any same-day reply chain, and the old
+    // behaviour was to overwrite silently.
+    const timestamp = filenameTimestamp(email.receivedDateTime);
     const safeSubject = sanitizeFilename(email.subject || 'no-subject');
     const extension = getExtension(format);
-    const defaultFilename = `${timestamp}_${safeSubject}.${extension}`;
+    const defaultBase = `${timestamp}_${safeSubject}`;
+
+    // Paths claimed while writing this message (main file + attachments).
+    const claimedPaths = new Set();
 
     // Determine final save path
     let finalPath;
-    if (savePath) {
-      // If savePath is a directory, append filename
-      if (fs.existsSync(savePath) && fs.statSync(savePath).isDirectory()) {
-        finalPath = path.join(savePath, defaultFilename);
-      } else {
-        finalPath = savePath;
-      }
+    if (
+      savePath &&
+      !(fs.existsSync(savePath) && fs.statSync(savePath).isDirectory())
+    ) {
+      // An explicit file path is the caller's to control — honour it exactly,
+      // including overwriting, since that is what an explicit path means.
+      finalPath = savePath;
     } else {
-      // Default to OS temp directory to avoid polluting the working directory
-      finalPath = path.join(os.tmpdir(), defaultFilename);
+      // A directory (or the default temp dir) means we choose the name, so
+      // never clobber a file that is already there.
+      const dir = savePath || os.tmpdir();
+      fs.mkdirSync(dir, { recursive: true });
+      finalPath = claimUniquePath(dir, defaultBase, extension, claimedPaths);
     }
 
     // Export based on format
@@ -152,7 +158,8 @@ async function handleExportEmail(args) {
       attachmentsSaved = await saveAttachments(
         accessToken,
         emailId,
-        path.dirname(finalPath)
+        path.dirname(finalPath),
+        claimedPaths
       );
     }
 
@@ -372,6 +379,21 @@ async function handleBatchExportEmails(args) {
     );
     resultText += `| Total Size | ${(totalBytes / 1024).toFixed(1)} KB |\n`;
 
+    // Requested id -> written path, so a caller can reconcile without
+    // listing the directory. A batch that silently lost messages to
+    // filename collisions still reported "Successful N / Failed 0", and the
+    // loss was only ever caught by counting distinct Message-IDs by hand.
+    const manifest = successful.map((r) => ({
+      emailId: r.emailId,
+      filePath: r.filePath,
+    }));
+    const disambiguated = manifest.filter((entry) =>
+      /_\d+\.[^.]+$/.test(entry.filePath)
+    );
+    if (disambiguated.length > 0) {
+      resultText += `\n> ${disambiguated.length} file name(s) were disambiguated with a numeric suffix — messages sharing a timestamp and subject, or names already present in the output directory. Nothing was overwritten.\n`;
+    }
+
     if (failed.length > 0) {
       resultText += `\n### Failed Exports\n\n`;
       for (const f of failed.slice(0, 10)) {
@@ -396,6 +418,7 @@ async function handleBatchExportEmails(args) {
         successful: successful.length,
         failed: failed.length,
         totalBytes: totalBytes,
+        manifest,
       },
     };
   } catch (error) {
@@ -488,6 +511,8 @@ async function exportWithConcurrency(
 ) {
   const results = [];
   const inProgress = new Set();
+  // Shared across the batch so concurrent exports cannot claim the same path.
+  const claimedPaths = new Set();
   let index = 0;
 
   while (index < emailIds.length || inProgress.size > 0) {
@@ -499,7 +524,8 @@ async function exportWithConcurrency(
         emailId,
         format,
         outputDir,
-        includeAttachments
+        includeAttachments,
+        claimedPaths
       ).then((result) => {
         inProgress.delete(promise);
         results.push(result);
@@ -526,7 +552,8 @@ async function exportSingleForBatch(
   emailId,
   format,
   outputDir,
-  includeAttachments
+  includeAttachments,
+  claimedPaths
 ) {
   try {
     const selectFields = getEmailFields('export');
@@ -538,13 +565,15 @@ async function exportSingleForBatch(
       { $select: selectFields }
     );
 
-    const timestamp = new Date(email.receivedDateTime)
-      .toISOString()
-      .slice(0, 10);
+    const timestamp = filenameTimestamp(email.receivedDateTime);
     const safeSubject = sanitizeFilename(email.subject || 'no-subject');
     const extension = getExtension(format);
-    const filename = `${timestamp}_${safeSubject}.${extension}`;
-    const filePath = path.join(outputDir, filename);
+    const filePath = claimUniquePath(
+      outputDir,
+      `${timestamp}_${safeSubject}`,
+      extension,
+      claimedPaths
+    );
 
     let content;
     if (format === EXPORT_FORMATS.MIME || format === EXPORT_FORMATS.EML) {
@@ -562,7 +591,12 @@ async function exportSingleForBatch(
     // Handle attachments if requested
     let attachmentCount = 0;
     if (includeAttachments && email.hasAttachments) {
-      const saved = await saveAttachments(accessToken, emailId, outputDir);
+      const saved = await saveAttachments(
+        accessToken,
+        emailId,
+        outputDir,
+        claimedPaths
+      );
       attachmentCount = saved.length;
     }
 
@@ -585,7 +619,7 @@ async function exportSingleForBatch(
 /**
  * Save email attachments to directory
  */
-async function saveAttachments(accessToken, emailId, outputDir) {
+async function saveAttachments(accessToken, emailId, outputDir, claimedPaths) {
   const saved = [];
 
   try {
@@ -602,9 +636,16 @@ async function saveAttachments(accessToken, emailId, outputDir) {
     for (const att of response.value) {
       if (att.contentBytes) {
         const safeFilename = sanitizeFilename(att.name || 'attachment');
-        const filePath = path.join(
+        // `emailId.substring(0, 8)` was not a disambiguator: Graph message ids
+        // within one mailbox share a long common prefix, so every message's
+        // `invoice.pdf` resolved to the same path and all but the last were
+        // overwritten. Claim a unique path instead.
+        const { base, extension } = splitExtension(safeFilename);
+        const filePath = claimUniquePath(
           outputDir,
-          `${emailId.substring(0, 8)}_${safeFilename}`
+          `${emailId.substring(0, 8)}_${base}`,
+          extension,
+          claimedPaths || new Set()
         );
         const buffer = Buffer.from(att.contentBytes, 'base64');
         fs.writeFileSync(filePath, buffer);
@@ -622,6 +663,63 @@ async function saveAttachments(accessToken, emailId, outputDir) {
   return saved;
 }
 
+/**
+ * Format a message timestamp for use in a filename.
+ *
+ * Date-only was the collision: a same-day reply chain is extremely common, and
+ * every message in it normalises to the same `<date>_<subject>` name. Keeping
+ * the time disambiguates the realistic case. Mirrors the sanitisation #82
+ * applied to the aggregated CSV name.
+ *
+ * @param {string} isoDateTime - Message receivedDateTime
+ * @returns {string} - e.g. `2023-06-15T01-26-00`
+ */
+function filenameTimestamp(isoDateTime) {
+  const parsed = new Date(isoDateTime);
+  if (Number.isNaN(parsed.getTime())) return 'undated';
+  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) {
+  let candidate = path.join(outputDir, `${base}.${extension}`);
+  let suffix = 1;
+  while (claimed.has(candidate) || fs.existsSync(candidate)) {
+    suffix += 1;
+    candidate = path.join(outputDir, `${base}_${suffix}.${extension}`);
+  }
+  claimed.add(candidate);
+  return candidate;
+}
+
+/**
+ * Split a filename into base and extension for collision-safe claiming.
+ * @param {string} name - Sanitised filename, possibly with an extension
+ * @returns {{base: string, extension: string}}
+ */
+function splitExtension(name) {
+  const dot = name.lastIndexOf('.');
+  if (dot <= 0) return { base: name, extension: '' };
+  return { base: name.slice(0, dot), extension: name.slice(dot + 1) };
+}
+
 /**
  * Sanitize filename for filesystem
  */

package/email/index.js

@@ -68,12 +68,13 @@ const emailTools = [
         // Search/list params
         query: {
           type: 'string',
-          description: 'Search query text. Omit for list mode.',
+          description:
+            'Search query text. Omit for list mode. On personal Outlook.com accounts Graph `$search` is unavailable, so this falls back to a subject substring match (all words must appear in the subject) — precise, but it does NOT search message bodies. Use `searchExpression` when you need body content.',
         },
         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.',
+            '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.',
         },
         kqlQuery: {
           type: 'string',
@@ -90,7 +91,8 @@ const emailTools = [
         },
         to: {
           type: 'string',
-          description: 'Filter by recipient email/name',
+          description:
+            'Filter by recipient email/name. Personal Outlook.com accounts reject the server-side recipient filter, in which case this is matched locally over the 500 most recent messages only (raise with `OUTLOOK_SEARCH_SCAN_LIMIT`). On a large archive, pair `to` with `receivedAfter`/`receivedBefore` to reach older mail; the response says so when the scan was truncated.',
         },
         subject: {
           type: 'string',

package/email/search.js

@@ -79,9 +79,19 @@ async function handleSearchEmails(args) {
   // this, a `from`+`to` search would drop every row at default verbosity and
   // return "No emails found" — making `outputVerbosity`, a presentation
   // parameter, decide which messages are found.
+  //
+  // A SINGLE term needs the richer preset too when it is `to` or `query`. The
+  // date/boolean rung applies no search term server-side, so it narrows by
+  // every supplied term locally — and `filterToClientSide` reads
+  // `toRecipients` while `filterQueryClientSide` reads `bodyPreview`, neither
+  // of which the `list` preset requests. Left lean, those matchers see
+  // `undefined` on every row and drop the entire result set.
   const searchTermCount = [query, from, to, subject].filter(Boolean).length;
+  const needsMatcherFields = Boolean(to) || Boolean(query);
   const selectFields = getEmailFields(
-    verbosity === VERBOSITY.FULL || searchTermCount > 1 ? 'search' : 'list'
+    verbosity === VERBOSITY.FULL || searchTermCount > 1 || needsMatcherFields
+      ? 'search'
+      : 'list'
   );
 
   try {
@@ -1300,9 +1310,20 @@ function addBooleanFilters(params, filterTerms) {
     }
   }
 
-  // Add $filter parameter if we have any filter conditions
+  // AND onto any $filter the caller already built — never replace it.
+  //
+  // The single-term rung sets `$filter` from the search term (e.g.
+  // `toRecipients/any(...)`) and then calls this to add the date/boolean
+  // window. Assigning here silently dropped that term, so a `to` + date-window
+  // search issued a DATE-ONLY request and returned the whole window labelled
+  // `single-term-to` with `appliedTerms: ['to']` — a superset presented as a
+  // filtered result. Affected `from`, `to`, `subject` and `query` alike.
+  //
+  // Every condition either side is a conjunct, so a flat ' and ' join is
+  // sound; there is no top-level `or` that would need parenthesising.
   if (filterConditions.length > 0) {
-    params.$filter = filterConditions.join(' and ');
+    const added = filterConditions.join(' and ');
+    params.$filter = params.$filter ? `${params.$filter} and ${added}` : added;
   }
 }
 
@@ -1506,6 +1527,17 @@ function formatSearchResults(response, folder, verbosity, searchAllFolders) {
     } else {
       searchNote = `\n\n_Search strategy: ${strategy}_`;
     }
+
+    // A local scan that filled its budget did not see the whole mailbox, so
+    // these results are a bounded sample rather than the complete set. #231
+    // says so only when the search returns nothing; a truncated scan that
+    // DID match is exactly as incomplete and reads as authoritative. On a
+    // large archive that silently caps historical searches.
+    if (response._searchInfo.truncated) {
+      const scanned = response._searchInfo.candidatesScanned;
+      const limit = response._searchInfo.scanLimit;
+      searchNote += `\n\n> **Partial coverage**: matched locally within the ${scanned} most recent messages, hitting the ${limit} scan limit — older matches were not seen. Narrow with \`receivedAfter\`/\`receivedBefore\` to search further back.`;
+    }
   }
 
   // Format results using shared formatter

package/llms.txt

@@ -79,6 +79,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.11.0 — fixes & polish: `--version`/`--help` CLI flags, where previously any argument was ignored and the server booted and hung on stdin (#68); `AADSTS7000215` (the Secret ID vs Secret Value mistake) now explains itself instead of passing Microsoft's raw error through, via one shared AADSTS hint table (#69); token-refresh round trip covered end to end from disk to the `Authorization` header on the next Graph call (#72); all 17 development-dependency advisories cleared, so `npm audit` reports zero at every severity. Preceded by v3.10.0 — search correctness: field-scoped `searchExpression` translated to OData filters and retried on personal accounts (#217), two-filter searches no longer returning the single-filter superset with `searchMetadata.droppedFilters` reporting anything unhonoured (#229), `from`/`to` filter values OData-escaped (#230), no-results guidance derived from what was actually attempted (#231) — and v3.9.1, a packaging hotfix restoring `request-handler.js` in the published tarball (#223))
-- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.11.1 tool description audit, v3.8.x carry-over, v3.12.0+ new Graph APIs)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.11.1 — search and export correctness: a search term combined with a date or boolean filter was silently overwritten, so the request carried only the date window and the whole window came back reported as a filtered result; batch export named files `<date>_<subject>`, so a same-day reply chain overwrote itself on disk while the summary reported `Failed 0` — filenames now carry the time, collisions get a numeric suffix instead of clobbering, and a manifest maps each requested ID to the file actually written; a truncated local scan is now disclosed when it matched, not only when it returned nothing; `query` versus `searchExpression` and the 500-message `to` scan cap documented. Preceded by v3.11.0 — fixes & polish: `--version`/`--help` CLI flags (#68), `AADSTS7000215` explaining the Secret ID vs Secret Value mistake via one shared AADSTS hint table (#69), token-refresh round trip covered end to end (#72), and all 17 development-dependency advisories cleared; and v3.10.0 — search correctness: field-scoped `searchExpression` translated to OData filters and retried on personal accounts (#217), two-filter searches no longer returning the single-filter superset (#229), `from`/`to` filter values OData-escaped (#230), no-results guidance derived from what was actually attempted (#231))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.11.2 tool description audit, v3.8.x carry-over, v3.12.0+ new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.11.0",
+  "version": "3.11.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",