@littlebearapps/outlook-assistant 3.13.0 → 3.14.1

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/
@@ -82,6 +83,47 @@ function clampPageSize(value) {
   return Math.min(Math.max(Math.floor(n), 1), MAX_PAGE_SIZE);
 }
 
+/**
+ * Sync phase of each continuation token this server issued (#262). A
+ * `$skiptoken` page belongs to whichever sync produced it, initial or
+ * incremental, and its URL doesn't say which, so remember it. Bounded; a
+ * continuation token not in here (e.g. after a restart) has phase 'unknown'.
+ */
+const CONTINUATION_PHASES = new Map();
+const MAX_TRACKED_CONTINUATIONS = 200;
+
+function rememberPhase(token, phase) {
+  CONTINUATION_PHASES.delete(token);
+  CONTINUATION_PHASES.set(token, phase);
+  if (CONTINUATION_PHASES.size > MAX_TRACKED_CONTINUATIONS) {
+    CONTINUATION_PHASES.delete(CONTINUATION_PHASES.keys().next().value);
+  }
+}
+
+/**
+ * 'initial' (no token, or a continuation of an initial sync), 'incremental'
+ * (a delta token, or a continuation of one) or 'unknown' (a continuation
+ * token this server didn't issue).
+ * @param {string} [deltaToken]
+ * @returns {'initial'|'incremental'|'unknown'}
+ */
+function syncPhase(deltaToken) {
+  if (!deltaToken) return 'initial';
+  if (CONTINUATION_PHASES.has(deltaToken)) {
+    return CONTINUATION_PHASES.get(deltaToken);
+  }
+  // A continuation token this server didn't issue (e.g. from before a
+  // restart) can't be placed; any other token is a delta token.
+  if (/[?&](\$|%24)skiptoken=/i.test(deltaToken)) return 'unknown';
+  return 'incremental';
+}
+
+const PHASE_LABEL = {
+  initial: 'Initial',
+  incremental: 'Incremental',
+  unknown: 'Continuation (initial or incremental unknown)',
+};
+
 /**
  * List emails delta handler - incremental sync
  * @param {object} args - Tool arguments
@@ -116,16 +158,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 {
@@ -159,6 +195,7 @@ async function handleListEmailsDelta(args) {
     );
 
     // Process results
+    const phase = syncPhase(deltaToken);
     const emails = response.value || [];
     const nextLink = response['@odata.nextLink'];
     const deltaLink = response['@odata.deltaLink'];
@@ -180,20 +217,20 @@ async function handleListEmailsDelta(args) {
           removed: true,
           reason: email['@removed'].reason || 'deleted',
         });
-      } else if (deltaToken) {
-        // With deltaToken, all non-removed items are changes
-        // We can't reliably distinguish created vs updated via delta
-        changesSummary.updated++;
+      } else if (phase === 'initial') {
+        // Initial sync (any page) - all items are "created" for our purposes
+        changesSummary.created++;
         processedEmails.push(email);
       } else {
-        // Initial sync - all items are "created" for our purposes
-        changesSummary.created++;
+        // Incremental (or unknown) - every non-removed item is a change; Graph
+        // doesn't say whether it was created or updated
+        changesSummary.updated++;
         processedEmails.push(email);
       }
     }
 
     // Build response
-    const isInitialSync = !deltaToken;
+    const isInitialSync = phase === 'initial';
     const hasMoreChanges = Boolean(nextLink);
     const newDeltaToken = deltaLink || nextLink;
     // F-15: nextLink is a continuation token (more pages of the same
@@ -201,6 +238,7 @@ async function handleListEmailsDelta(args) {
     // the initial sync finishes paging. Distinguish them in output so
     // callers know what they're storing.
     const tokenIsContinuation = !deltaLink && Boolean(nextLink);
+    if (tokenIsContinuation) rememberPhase(nextLink, phase);
 
     // Format output based on verbosity
     let resultText;
@@ -209,7 +247,7 @@ async function handleListEmailsDelta(args) {
       resultText += `| Metric | Value |\n`;
       resultText += `|--------|-------|\n`;
       resultText += `| Items | ${processedEmails.length} |\n`;
-      resultText += `| Type | ${isInitialSync ? 'Initial' : 'Incremental'} |\n`;
+      resultText += `| Type | ${PHASE_LABEL[phase]} |\n`;
       resultText += `| More | ${hasMoreChanges ? 'Yes' : 'No'} |\n`;
       if (newDeltaToken) {
         const label = tokenIsContinuation
@@ -218,7 +256,7 @@ async function handleListEmailsDelta(args) {
         resultText += `\n**${label}**:\n\`\`\`\n${newDeltaToken}\n\`\`\`\n`;
       }
     } else {
-      resultText = `## Delta Sync ${isInitialSync ? '(Initial)' : '(Incremental)'}\n\n`;
+      resultText = `## Delta Sync (${PHASE_LABEL[phase]})\n\n`;
 
       // Changes summary
       resultText += `### Changes Summary\n\n`;
@@ -236,8 +274,11 @@ async function handleListEmailsDelta(args) {
       const activeEmails = processedEmails.filter((e) => !e.removed);
       if (activeEmails.length > 0) {
         resultText += `\n### Emails\n\n`;
+        // formatEmailList takes (emails, folder, verbosity): the verbosity
+        // used to land in the folder slot ("Emails in standard", #306).
         resultText += formatEmailList(
           activeEmails,
+          deltaToken ? 'this sync page' : folder,
           verbosity === 'full' ? VERBOSITY.FULL : VERBOSITY.STANDARD
         );
       }
@@ -280,12 +321,12 @@ async function handleListEmailsDelta(args) {
         },
       ],
       _meta: {
-        syncType: isInitialSync ? 'initial' : 'incremental',
+        syncType: phase,
         mailbox: sharedMailbox || 'me',
         // With a token the folder comes from the token, not the `folder` arg
         // (which is ignored) — don't echo a value we didn't use.
-        folder: isInitialSync ? folder : null,
-        folderSource: isInitialSync ? 'argument' : 'deltaToken',
+        folder: deltaToken ? null : folder,
+        folderSource: deltaToken ? 'deltaToken' : 'argument',
         itemCount: processedEmails.length,
         hasMoreChanges: hasMoreChanges,
         changesSummary: changesSummary,
@@ -295,14 +336,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,25 +344,14 @@ 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}`);
   }
 }
 
 module.exports = handleListEmailsDelta;
+module.exports.syncPhase = syncPhase;