m365connector 0.3.6 → 0.3.8

package/src/lib/content-reader.js

@@ -0,0 +1,2746 @@
+let jsZipRef = globalThis.JSZip || null;
+let jsZipLoadPromise = null;
+let jsZipLoadFailed = false;
+
+const EMAIL_SELECTORS = [
+  "td.x_message",
+  'div[aria-label="Message body"]',
+  'div[aria-label^="Message body"]',
+  "div.ReadingPaneContents",
+  'div[role="document"]'
+];
+
+const GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0";
+const TEN_MB = 10 * 1024 * 1024;
+const CIRCUIT_FAILURE_WINDOW_MS = 5 * 60 * 1000;
+const CIRCUIT_OPEN_MS = 10 * 60 * 1000;
+const NEGATIVE_CACHE_MS = 30 * 60 * 1000;
+const TRANSLATION_CACHE_MS = 6 * 60 * 60 * 1000;
+const MAX_CACHE_ENTRIES = 500;
+const HTML_ENTITY_MAP = new Map([
+  ["nbsp", " "],
+  ["amp", "&"],
+  ["lt", "<"],
+  ["gt", ">"],
+  ["quot", '"'],
+  ["apos", "'"],
+  ["rsquo", "'"],
+  ["lsquo", "'"],
+  ["rdquo", '"'],
+  ["ldquo", '"'],
+  ["ndash", "-"],
+  ["mdash", "--"],
+  ["hellip", "..."],
+  ["copy", "(c)"],
+  ["reg", "(r)"],
+  ["trade", "TM"]
+]);
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function pickContext(params) {
+  if (!params) {
+    return null;
+  }
+  return params.context || params.read_context || null;
+}
+
+function nowMs() {
+  return Date.now();
+}
+
+async function ensureJsZipAvailable() {
+  if (jsZipRef) {
+    return jsZipRef;
+  }
+  if (jsZipLoadFailed) {
+    return null;
+  }
+  if (jsZipLoadPromise) {
+    return jsZipLoadPromise;
+  }
+
+  jsZipLoadPromise = import("./vendor/jszip.min.js")
+    .then(() => {
+      jsZipRef = globalThis.JSZip || null;
+      if (!jsZipRef) {
+        jsZipLoadFailed = true;
+      }
+      return jsZipRef;
+    })
+    .catch(() => {
+      jsZipLoadFailed = true;
+      return null;
+    })
+    .finally(() => {
+      jsZipLoadPromise = null;
+    });
+
+  return jsZipLoadPromise;
+}
+
+function evictOldestEntries(map, maxEntries) {
+  while (map.size > maxEntries) {
+    const firstKey = map.keys().next().value;
+    if (firstKey === undefined) {
+      break;
+    }
+    map.delete(firstKey);
+  }
+}
+
+function decodeCodePointSafe(value) {
+  if (!Number.isFinite(value) || value < 0 || value > 0x10ffff) {
+    return "";
+  }
+  try {
+    return String.fromCodePoint(value);
+  } catch (_err) {
+    return "";
+  }
+}
+
+function htmlToText(value) {
+  if (!value) {
+    return "";
+  }
+
+  return decodeXmlEntities(
+    String(value)
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<br\s*\/?\s*>/gi, "\n")
+    .replace(/<\/p>/gi, "\n")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\r/g, "")
+    .replace(/\n\s+\n/g, "\n\n")
+    .replace(/[ \t]+/g, " ")
+    .trim()
+  );
+}
+
+function decodeXmlEntities(text) {
+  return String(text || "")
+    .replace(/&#x([0-9A-Fa-f]+);/g, (_m, hex) => decodeCodePointSafe(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_m, dec) => decodeCodePointSafe(parseInt(dec, 10)))
+    .replace(/&([A-Za-z][A-Za-z0-9]+);/g, (match, entity) => {
+      const value = HTML_ENTITY_MAP.get(entity.toLowerCase());
+      return value !== undefined ? value : "";
+    });
+}
+
+function extractTagValues(xml, tagName) {
+  const pattern = new RegExp(`<${tagName}[^>]*>([\\s\\S]*?)<\\/${tagName}>`, "g");
+  const values = [];
+  let match;
+  while ((match = pattern.exec(xml)) !== null) {
+    values.push(decodeXmlEntities(match[1]));
+  }
+  return values;
+}
+
+function getFileExtension(context = {}, driveItem = {}) {
+  const rawType = String(context?.metadata?.fileType || "").toLowerCase().replace(/^\./, "");
+  if (rawType) {
+    return rawType;
+  }
+
+  const candidates = [
+    String(driveItem?.name || ""),
+    String(context?.title || ""),
+    String(context?.url || ""),
+    String(context?.webUrl || "")
+  ];
+
+  for (const candidate of candidates) {
+    const match = candidate.toLowerCase().match(/\.([a-z0-9]{1,10})(?:\?|#|$)/);
+    if (match?.[1]) {
+      return match[1];
+    }
+  }
+  return "";
+}
+
+function isAllowedSharePointUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:") {
+      return false;
+    }
+
+    const host = parsed.hostname.toLowerCase();
+    return host.endsWith(".sharepoint.com")
+      || host.endsWith(".sharepoint-df.com")
+      || host === "sharepoint.com"
+      || host === "sharepoint-df.com";
+  } catch (_err) {
+    return false;
+  }
+}
+
+function extractOutlookDeepLinkItemId(url) {
+  if (!url) {
+    return "";
+  }
+
+  try {
+    const parsed = new URL(url);
+    const host = parsed.hostname.toLowerCase();
+    if (parsed.protocol !== "https:" || host !== "outlook.office.com") {
+      return "";
+    }
+    if (!parsed.pathname.toLowerCase().startsWith("/mail/deeplink")) {
+      return "";
+    }
+    return String(parsed.searchParams.get("ItemID") || parsed.searchParams.get("itemid") || "").trim();
+  } catch (_err) {
+    return "";
+  }
+}
+
+function base64UrlEncode(value) {
+  const bytes = new TextEncoder().encode(String(value || ""));
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+
+function retryAfterSeconds(headerValue) {
+  if (!headerValue) {
+    return null;
+  }
+  const asInt = parseInt(headerValue, 10);
+  if (Number.isInteger(asInt) && asInt >= 0) {
+    return asInt;
+  }
+  const asDate = Date.parse(headerValue);
+  if (!Number.isNaN(asDate)) {
+    const deltaMs = asDate - Date.now();
+    if (deltaMs > 0) {
+      return Math.ceil(deltaMs / 1000);
+    }
+  }
+  return null;
+}
+
+function normalizeString(value) {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  return String(value).trim();
+}
+
+function normalizePhoneList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const phones = value
+    .map((entry) => {
+      if (typeof entry === "string") {
+        return normalizeString(entry);
+      }
+      if (entry && typeof entry === "object") {
+        return normalizeString(entry.number || entry.phoneNumber || entry.value);
+      }
+      return "";
+    })
+    .filter(Boolean);
+
+  return Array.from(new Set(phones));
+}
+
+function inferAlias(mailNickname, userPrincipalName, mail) {
+  const alias = normalizeString(mailNickname);
+  if (alias) {
+    return alias;
+  }
+
+  const upn = normalizeString(userPrincipalName);
+  if (upn.includes("@")) {
+    return upn.split("@")[0];
+  }
+
+  const email = normalizeString(mail);
+  if (email.includes("@")) {
+    return email.split("@")[0];
+  }
+
+  return "";
+}
+
+function normalizeDirectoryPerson(record, source = "users") {
+  const row = record && typeof record === "object" ? record : {};
+  const scoredEmails = Array.isArray(row.scoredEmailAddresses)
+    ? row.scoredEmailAddresses
+      .map((entry) => normalizeString(entry?.address || entry?.addressString || entry?.value))
+      .filter(Boolean)
+    : [];
+
+  const businessPhones = normalizePhoneList(row.businessPhones);
+  const fallbackPhones = normalizePhoneList(row.phones);
+  const mobilePhone = normalizeString(row.mobilePhone);
+  const allPhones = Array.from(
+    new Set(
+      [
+        mobilePhone,
+        ...businessPhones,
+        ...fallbackPhones
+      ].filter(Boolean)
+    )
+  );
+
+  const userPrincipalName = normalizeString(row.userPrincipalName);
+  const mail = normalizeString(row.mail || scoredEmails[0]);
+  const alias = inferAlias(row.mailNickname, userPrincipalName, mail);
+
+  return {
+    id: normalizeString(row.id || row.userId || row.personId),
+    alias,
+    displayName: normalizeString(row.displayName),
+    givenName: normalizeString(row.givenName),
+    surname: normalizeString(row.surname),
+    mail,
+    userPrincipalName,
+    jobTitle: normalizeString(row.jobTitle),
+    department: normalizeString(row.department),
+    officeLocation: normalizeString(row.officeLocation),
+    mobilePhone,
+    businessPhones,
+    phones: allPhones,
+    source
+  };
+}
+
+function escapeODataStringLiteral(value) {
+  return normalizeString(value).replace(/'/g, "''");
+}
+
+function buildUsersFieldFilter(field, query) {
+  const safeField = normalizeString(field);
+  const safeQuery = escapeODataStringLiteral(query);
+  return `startswith(${safeField},'${safeQuery}')`;
+}
+
+function trimForError(value, maxLen = 220) {
+  const compact = normalizeString(value).replace(/\s+/g, " ");
+  if (compact.length <= maxLen) {
+    return compact;
+  }
+  return `${compact.slice(0, maxLen)}...`;
+}
+
+function escapeGraphSearchValue(value) {
+  return normalizeString(value)
+    .replace(/["\\]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function buildUsersSearchClause(query) {
+  const token = escapeGraphSearchValue(query);
+  if (!token) {
+    return "\"displayName:\"";
+  }
+  return [
+    `"displayName:${token}"`,
+    `"mailNickname:${token}"`,
+    `"mail:${token}"`,
+    `"userPrincipalName:${token}"`
+  ].join(" OR ");
+}
+
+function containsFuzzy(haystack, needle) {
+  const left = normalizeString(haystack).toLowerCase();
+  const right = normalizeString(needle).toLowerCase();
+  if (!right) {
+    return true;
+  }
+  return left.includes(right);
+}
+
+function normalizePeopleFilters(params = {}) {
+  return {
+    query: normalizeString(params.query),
+    alias: normalizeString(params.alias),
+    principalName: normalizeString(params.principal_name || params.principalName || params.user_principal_name),
+    displayName: normalizeString(params.display_name || params.displayName),
+    department: normalizeString(params.department),
+    office: normalizeString(params.office || params.office_location),
+    title: normalizeString(params.title || params.job_title)
+  };
+}
+
+function pickSearchSeeds(filters) {
+  const ordered = [
+    filters.query,
+    filters.alias,
+    filters.principalName,
+    filters.displayName,
+    filters.department,
+    filters.office,
+    filters.title
+  ].filter(Boolean);
+  return Array.from(new Set(ordered));
+}
+
+function matchesPeopleFilters(person, filters) {
+  const p = person || {};
+  if (filters.alias && !containsFuzzy(p.alias, filters.alias)) {
+    return false;
+  }
+  if (filters.principalName && !containsFuzzy(p.userPrincipalName, filters.principalName)) {
+    return false;
+  }
+  if (filters.displayName && !containsFuzzy(p.displayName, filters.displayName)) {
+    return false;
+  }
+  if (filters.department && !containsFuzzy(p.department, filters.department)) {
+    return false;
+  }
+  if (filters.office && !containsFuzzy(p.officeLocation, filters.office)) {
+    return false;
+  }
+  if (filters.title && !containsFuzzy(p.jobTitle, filters.title)) {
+    return false;
+  }
+
+  if (filters.query) {
+    const fields = [
+      p.alias,
+      p.displayName,
+      p.mail,
+      p.userPrincipalName,
+      p.jobTitle,
+      p.department,
+      p.officeLocation
+    ];
+    if (!fields.some((value) => containsFuzzy(value, filters.query))) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+const DIRECTORY_PERSON_SELECT = [
+  "id",
+  "displayName",
+  "givenName",
+  "surname",
+  "mail",
+  "userPrincipalName",
+  "mailNickname",
+  "jobTitle",
+  "department",
+  "officeLocation",
+  "mobilePhone",
+  "businessPhones"
+].join(",");
+
+const COMPACT_DIRECTORY_PERSON_SELECT = [
+  "id",
+  "displayName",
+  "mail",
+  "userPrincipalName",
+  "mailNickname",
+  "jobTitle",
+  "department",
+  "officeLocation"
+].join(",");
+
+const PEOPLE_DIRECT_REPORT_CONCURRENCY = 5;
+const PEOPLE_DIRECT_REPORT_TIMEOUT_MS = 5000;
+
+function withTimeout(promise, timeoutMs, message) {
+  let timeoutId = null;
+  const timeoutPromise = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(message || "Operation timed out"));
+    }, timeoutMs);
+  });
+
+  return Promise.race([promise, timeoutPromise]).finally(() => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  });
+}
+
+async function mapWithConcurrencyLimit(items, limit, mapper) {
+  const results = [];
+  const batchSize = Math.max(1, Number(limit) || 1);
+
+  for (let start = 0; start < items.length; start += batchSize) {
+    const chunk = items.slice(start, start + batchSize);
+    const settled = await Promise.allSettled(
+      chunk.map((item, index) => mapper(item, start + index))
+    );
+    results.push(...settled);
+  }
+
+  return results;
+}
+
+function isIgnorableDirectoryLookupError(err) {
+  const message = String(err?.message || err);
+  return message.includes("Graph token unavailable or missing scope")
+    || message.includes("Graph permission denied (403)")
+    || message.includes("Graph request failed (404)");
+}
+
+function getDirectoryPersonKey(person) {
+  return normalizeString(person?.id || person?.userPrincipalName || person?.mail);
+}
+
+class GraphHttpError extends Error {
+  constructor(message, status = 0, body = "", retryAfter = null) {
+    super(message);
+    this.name = "GraphHttpError";
+    this.status = Number(status || 0);
+    this.body = body || "";
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class ContentReader {
+  #deepLinkActive = false;
+
+  constructor(graphTokenProvider = null, logger = console) {
+    this.graphTokenProvider = graphTokenProvider;
+    this.logger = logger;
+    this.circuitBreakers = {
+      email: { failures: [], openUntil: 0 },
+      event: { failures: [], openUntil: 0 },
+      file: { failures: [], openUntil: 0 }
+    };
+    this.deniedCache = new Map();
+    this.translationCache = new Map();
+  }
+
+  async read(params = {}) {
+    const context = pickContext(params);
+    if (!context || !context.type) {
+      throw new Error("Invalid read context");
+    }
+    const options = { fullContent: Boolean(params.fullContent) };
+
+    switch (context.type) {
+      case "email":
+        return this.readEmail(context);
+      case "file":
+        return this.readFile(context, null, options);
+      case "external":
+        return this.readExternal(context);
+      case "chat":
+        return this.readChat(context);
+      case "event":
+        return this.readEvent(context);
+      default:
+        return {
+          content: context.snippet || "",
+          contentType: "text",
+          completeness: "snippet",
+          type: context.type,
+          title: context.title || "",
+          url: context.url || "",
+          metadata: context.metadata || {},
+          warning: `Unsupported type for open: ${context.type}`
+        };
+    }
+  }
+
+  async readEmail(context) {
+    const itemId = this.getEmailItemId(context);
+    this.logger.info("[m365connector][graph] readEmail: id=%s mailboxOwnerId=%s", itemId, context.mailboxOwnerId);
+    if (!itemId) {
+      return {
+        content: context.snippet || "",
+        contentType: "text",
+        completeness: "snippet",
+        type: "email",
+        title: context.title || "",
+        url: context.url || "",
+        metadata: {},
+        warning: "Email item id missing in read context"
+      };
+    }
+
+    const graphResult = await this.tryGraphRead(
+      "email",
+      itemId,
+      "Mail.Read",
+      (token) => this.readEmailViaGraph(token, context)
+    );
+
+    // Check if Graph returned IRM-protected or empty content that warrants deep-link fallback
+    const graphContentEmpty = graphResult && (!graphResult.content || !graphResult.content.trim());
+    const graphContentEncrypted = graphResult && this.isEncryptedEmailContent(graphResult.content);
+
+    if (graphResult && !graphContentEmpty && !graphContentEncrypted) {
+      return graphResult;
+    }
+
+    if (graphResult) {
+      this.logger.info("[m365connector][graph] readEmail: Graph returned %s content, trying deep-link fallback",
+        graphContentEncrypted ? "IRM-protected" : "empty");
+    }
+
+    const fallbackReason = graphContentEncrypted ? "IRM-protected" : (graphResult ? "empty Graph body" : "Graph unavailable");
+
+    let deepLinkResult = null;
+    try {
+      deepLinkResult = await this.readEmailViaDeepLink(context);
+    } catch (err) {
+      this.logger.warn("[m365connector][graph] readEmail: deep-link fallback threw", err?.message || err);
+      if (graphResult) {
+        return {
+          ...graphResult,
+          warning: `Email has ${fallbackReason}; deep-link fallback failed: ` + (err?.message || "unknown error")
+        };
+      }
+    }
+
+    if (deepLinkResult && deepLinkResult.completeness !== "snippet") {
+      // Validate that deep-link didn't also return encrypted wrapper content
+      if (this.isEncryptedEmailContent(deepLinkResult.content)) {
+        this.logger.info("[m365connector][graph] readEmail: deep-link also returned encrypted wrapper");
+        if (graphResult) {
+          return {
+            ...graphResult,
+            warning: `Email has ${fallbackReason}; deep-link also returned encrypted wrapper`
+          };
+        }
+        return {
+          ...deepLinkResult,
+          completeness: "snippet",
+          warning: `Email has ${fallbackReason}; deep-link extraction also returned encrypted wrapper`
+        };
+      }
+
+      // Merge Graph metadata into deep-link result when available
+      if (graphResult && graphResult.metadata) {
+        return {
+          ...deepLinkResult,
+          title: deepLinkResult.title || graphResult.title,
+          metadata: { ...graphResult.metadata, ...deepLinkResult.metadata }
+        };
+      }
+      return deepLinkResult;
+    }
+
+    // Deep-link also failed; return Graph result with metadata if available.
+    if (graphResult) {
+      return {
+        ...graphResult,
+        warning: `Email has ${fallbackReason}; deep-link extraction also failed`
+      };
+    }
+
+    return deepLinkResult || {
+      content: context.snippet || "",
+      contentType: "text",
+      completeness: "snippet",
+      type: "email",
+      title: context.title || "",
+      url: context.url || "",
+      metadata: {},
+      warning: "Both Graph and deep-link fallback failed"
+    };
+  }
+
+  async readEvent(context) {
+    const itemId = context.id;
+    this.logger.info("[m365connector][graph] readEvent: id=%s calendarOwnerId=%s", itemId, context.calendarOwnerId);
+    if (itemId) {
+      const graphResult = await this.tryGraphRead(
+        "event",
+        itemId,
+        "Calendars.Read",
+        (token) => this.readEventViaGraph(token, context)
+      );
+
+      if (graphResult) {
+        return graphResult;
+      }
+    }
+
+    return this.readEventFromMetadata(context);
+  }
+
+  async readFile(context, warningOverride = null, options = {}) {
+    const itemId = context.id;
+    this.logger.info("[m365connector][graph] readFile: id=%s webUrl=%s", itemId, String(context.webUrl || "").substring(0, 60));
+
+    if (itemId || context.webUrl) {
+      const requiredScope = this.isSharePointResource(context) ? "Sites.Read.All" : "Files.Read.All";
+      const graphResult = await this.tryGraphRead(
+        "file",
+        itemId || context.webUrl,
+        requiredScope,
+        (token) => this.readFileViaGraph(token, context)
+      );
+
+      if (graphResult && graphResult.completeness === "full") {
+        return graphResult;
+      }
+
+      if (graphResult && graphResult.completeness === "partial") {
+        if (options.fullContent) {
+          this.logger.info("[m365connector] readFile: Graph returned partial result, trying deep-link fallback (fullContent=true)");
+          const deepLinkResult = await this.readFileViaDeepLink(context, options);
+          if (deepLinkResult && !deepLinkResult.skipped) {
+            return {
+              ...deepLinkResult,
+              metadata: { ...(graphResult.metadata || {}), ...(deepLinkResult.metadata || {}) }
+            };
+          }
+          if (deepLinkResult?.skipped === "busy") {
+            graphResult.warning = (graphResult.warning ? graphResult.warning + ". " : "")
+              + "Another fullContent request is in progress. Retry with fullContent=true after it completes to get the full document. Read fullContent documents sequentially, not in parallel.";
+          }
+        }
+        return graphResult;
+      }
+    }
+
+    if (options.fullContent) {
+      this.logger.info("[m365connector] readFile: Graph unavailable, trying deep-link fallback (fullContent=true)");
+      const deepLinkResult = await this.readFileViaDeepLink(context, options);
+      if (deepLinkResult && !deepLinkResult.skipped) {
+        return deepLinkResult;
+      }
+      if (deepLinkResult?.skipped === "busy") {
+        const fallback = await this.readFileFallback(context, warningOverride);
+        fallback.warning = (fallback.warning ? fallback.warning + ". " : "")
+          + "Another fullContent request is in progress. Retry with fullContent=true after it completes to get the full document. Read fullContent documents sequentially, not in parallel.";
+        return fallback;
+      }
+    }
+
+    return this.readFileFallback(context, warningOverride);
+  }
+
+  readExternal(context) {
+    const content = String(context.summary || context.snippet || "");
+    return {
+      content,
+      contentType: "text",
+      completeness: content.length > 2000 ? "full" : "partial",
+      type: "external",
+      title: context.title || "",
+      url: context.url || "",
+      metadata: context.metadata || {},
+      warning: undefined
+    };
+  }
+
+  readChat(context) {
+    return {
+      content: String(context.preview || context.snippet || ""),
+      contentType: "text",
+      completeness: "snippet",
+      type: "chat",
+      title: context.title || "",
+      url: context.url || "",
+      metadata: context.metadata || {},
+      warning: "Chat full-thread reading is unavailable without Graph Chat.Read scope"
+    };
+  }
+
+  readEventFromMetadata(context) {
+    const metadata = context.metadata || {};
+    const contentParts = [
+      metadata.subject ? `Subject: ${metadata.subject}` : "",
+      metadata.startTime ? `Start: ${metadata.startTime}` : "",
+      metadata.endTime ? `End: ${metadata.endTime}` : "",
+      metadata.location ? `Location: ${metadata.location}` : "",
+      metadata.organizer ? `Organizer: ${metadata.organizer}` : "",
+      Array.isArray(metadata.attendees) && metadata.attendees.length
+        ? `Attendees: ${metadata.attendees.join(", ")}`
+        : "",
+      metadata.bodyPreview ? `Body Preview: ${metadata.bodyPreview}` : "",
+      metadata.meetingUrl ? `Meeting URL: ${metadata.meetingUrl}` : ""
+    ].filter(Boolean);
+
+    return {
+      content: contentParts.join("\n"),
+      contentType: "text",
+      completeness: "full",
+      type: "event",
+      title: context.title || "",
+      url: context.url || "",
+      metadata,
+      warning: undefined
+    };
+  }
+
+  async getGraphTokenForScopes(scopes = []) {
+    if (!this.graphTokenProvider) {
+      return { token: null, scope: null };
+    }
+
+    const candidates = Array.isArray(scopes) ? scopes.filter(Boolean) : [];
+    for (const scope of candidates) {
+      const token = await this.graphTokenProvider.getToken(scope);
+      if (token) {
+        return { token, scope };
+      }
+    }
+
+    return { token: null, scope: null };
+  }
+
+  async fetchGraphJsonWithScopes(scopes, pathOrUrl, options = {}) {
+    const scopeCandidates = Array.isArray(scopes) ? scopes.filter(Boolean) : [];
+    if (!scopeCandidates.length) {
+      throw new Error("At least one scope is required");
+    }
+
+    let { token } = await this.getGraphTokenForScopes(scopeCandidates);
+    if (!token) {
+      throw new Error(`Graph token unavailable or missing scope: ${scopeCandidates.join(" or ")}`);
+    }
+
+    try {
+      return await this.fetchGraphJson(token, pathOrUrl, options);
+    } catch (err) {
+      if (Number(err?.status || 0) === 401 && this.graphTokenProvider) {
+        await this.graphTokenProvider.refresh();
+        const refreshed = await this.getGraphTokenForScopes(scopeCandidates);
+        token = refreshed.token;
+        if (!token) {
+          throw new Error(`Graph token unavailable or missing scope: ${scopeCandidates.join(" or ")}`);
+        }
+        return this.fetchGraphJson(token, pathOrUrl, options);
+      }
+
+      if (err instanceof GraphHttpError) {
+        if (err.status === 403) {
+          throw new Error(`Graph permission denied (403). Required scope: ${scopeCandidates.join(" or ")}`);
+        }
+        const detail = trimForError(err.body);
+        const suffix = detail ? `: ${detail}` : "";
+        throw new Error(`Graph request failed (${err.status || "unknown"})${suffix}`);
+      }
+
+      throw err;
+    }
+  }
+
+  async queryUsersBySearch(query, size, select) {
+    const searchClause = buildUsersSearchClause(query);
+    const path = `/users?$top=${size}`
+      + `&$count=true`
+      + `&$select=${encodeURIComponent(select)}`
+      + `&$search=${encodeURIComponent(searchClause)}`;
+
+    const response = await this.fetchGraphJsonWithScopes(
+      ["User.ReadBasic.All", "User.Read.All", "Directory.Read.All"],
+      path,
+      {
+        headers: {
+          ConsistencyLevel: "eventual"
+        }
+      }
+    );
+
+    return Array.isArray(response?.value) ? response.value : [];
+  }
+
+  async queryUsersByField(field, query, size, select) {
+    const path = `/users?$top=${size}`
+      + `&$select=${encodeURIComponent(select)}`
+      + `&$filter=${encodeURIComponent(buildUsersFieldFilter(field, query))}`;
+
+    const response = await this.fetchGraphJsonWithScopes(
+      ["User.ReadBasic.All", "User.Read.All", "Directory.Read.All"],
+      path
+    );
+
+    return Array.isArray(response?.value) ? response.value : [];
+  }
+
+  async fetchDirectReports(path, size, source = "directReport") {
+    const safeSize = Number.isInteger(size)
+      ? Math.min(100, Math.max(1, size))
+      : 30;
+    const response = await this.fetchGraphJsonWithScopes(
+      ["User.Read.All", "Directory.Read.All"],
+      `${path}?$count=true&$top=${safeSize}&$select=${encodeURIComponent(COMPACT_DIRECTORY_PERSON_SELECT)}`,
+      {
+        headers: {
+          ConsistencyLevel: "eventual"
+        }
+      }
+    );
+
+    const rows = Array.isArray(response?.value) ? response.value : [];
+    const directReports = rows.map((row) => normalizeDirectoryPerson(row, source));
+    const directReportsCount = Number.isInteger(response?.["@odata.count"])
+      ? response["@odata.count"]
+      : rows.length;
+
+    return {
+      directReports,
+      directReportsCount
+    };
+  }
+
+  buildPeopleQuery(filters, size, options = {}) {
+    const safeSize = Number.isInteger(size)
+      ? Math.max(1, size)
+      : 20;
+    const searchSeeds = pickSearchSeeds(filters);
+    const activeSearchSeed = normalizeString(options.searchSeed);
+    const searchClause = activeSearchSeed
+      ? buildUsersSearchClause(activeSearchSeed)
+      : "";
+
+    const graphFilters = [];
+    if (filters.department) {
+      graphFilters.push(buildUsersFieldFilter("department", filters.department));
+    }
+    if (filters.office) {
+      graphFilters.push(buildUsersFieldFilter("officeLocation", filters.office));
+    }
+    if (filters.title) {
+      graphFilters.push(buildUsersFieldFilter("jobTitle", filters.title));
+    }
+    const filterClause = graphFilters.join(" and ");
+    const requiresAdvancedQuery = Boolean(searchClause || filters.office || options.forceConsistencyLevel);
+
+    let path = `/users?$top=${safeSize}&$select=${encodeURIComponent(DIRECTORY_PERSON_SELECT)}`;
+    if (options.includeCount || searchClause || filters.office) {
+      path += "&$count=true";
+    }
+    if (searchClause) {
+      path += `&$search=${encodeURIComponent(searchClause)}`;
+    }
+    if (filterClause) {
+      path += `&$filter=${encodeURIComponent(filterClause)}`;
+    }
+
+    const requestOptions = requiresAdvancedQuery
+      ? {
+        headers: {
+          ConsistencyLevel: "eventual"
+        }
+      }
+      : {};
+
+    return {
+      path,
+      requestOptions,
+      searchClause,
+      searchSeeds,
+      activeSearchSeed
+    };
+  }
+
+  async fetchUsersRows(path, requestOptions = {}, options = {}) {
+    const followNextLink = Boolean(options.followNextLink);
+    const maxRows = Number.isInteger(options.maxRows) ? Math.max(1, options.maxRows) : Number.MAX_SAFE_INTEGER;
+    const rows = [];
+    let nextRef = path;
+
+    while (nextRef && rows.length < maxRows) {
+      const response = await this.fetchGraphJsonWithScopes(
+        ["User.ReadBasic.All", "User.Read.All", "Directory.Read.All"],
+        nextRef,
+        requestOptions
+      );
+      const pageRows = Array.isArray(response?.value) ? response.value : [];
+      rows.push(...pageRows);
+      if (!followNextLink || !response?.["@odata.nextLink"]) {
+        break;
+      }
+      nextRef = response["@odata.nextLink"];
+    }
+
+    return rows.slice(0, maxRows);
+  }
+
+  async queryPeopleFallbackRows(query, size, options = {}) {
+    const fields = query.includes("@")
+      ? ["mail", "userPrincipalName", "mailNickname", "displayName"]
+      : ["displayName", "mailNickname", "userPrincipalName", "mail", "givenName", "surname"];
+
+    const merged = new Map();
+    const followNextLink = Boolean(options.followNextLink);
+    const maxRows = Number.isInteger(options.maxRows) ? Math.max(1, options.maxRows) : size;
+    for (const field of fields) {
+      try {
+        const fieldPath = `/users?$top=${size}`
+          + `&$select=${encodeURIComponent(DIRECTORY_PERSON_SELECT)}`
+          + `&$filter=${encodeURIComponent(buildUsersFieldFilter(field, query))}`;
+        const fieldRows = await this.fetchUsersRows(fieldPath, {}, { followNextLink, maxRows });
+        for (const row of fieldRows) {
+          const person = normalizeDirectoryPerson(row, "users");
+          const key = getDirectoryPersonKey(person);
+          if (!key || merged.has(key)) {
+            continue;
+          }
+          merged.set(key, person);
+          if (!followNextLink && merged.size >= maxRows) {
+            break;
+          }
+        }
+        if (!followNextLink && merged.size >= maxRows) {
+          break;
+        }
+      } catch (fieldErr) {
+        const fieldMessage = String(fieldErr?.message || fieldErr);
+        if (!fieldMessage.includes("Graph request failed (400)")) {
+          throw fieldErr;
+        }
+      }
+    }
+
+    return Array.from(merged.values());
+  }
+
+  async queryPeopleResults(filters, size, options = {}) {
+    const textSeeds = pickSearchSeeds({
+      query: filters.query,
+      alias: filters.alias,
+      principalName: filters.principalName,
+      displayName: filters.displayName
+    });
+    const searchSeeds = textSeeds.length ? textSeeds : [""];
+    const merged = new Map();
+    const followNextLink = Boolean(options.followNextLink);
+    const maxRows = Number.isInteger(options.maxRows) ? Math.max(1, options.maxRows) : size;
+
+    for (const searchSeed of searchSeeds) {
+      const { path, requestOptions, searchClause } = this.buildPeopleQuery(filters, size, {
+        ...options,
+        searchSeed
+      });
+
+      let rows = [];
+      try {
+        rows = await this.fetchUsersRows(path, requestOptions, { followNextLink, maxRows });
+      } catch (err) {
+        const message = String(err?.message || err);
+        if (!searchClause || !message.includes("Graph request failed (400)")) {
+          throw err;
+        }
+        rows = await this.queryPeopleFallbackRows(searchSeed, size, { followNextLink, maxRows });
+      }
+
+      for (const row of rows) {
+        const person = row && row.source ? row : normalizeDirectoryPerson(row, "users");
+        const key = getDirectoryPersonKey(person);
+        if (!key || merged.has(key)) {
+          continue;
+        }
+        merged.set(key, person);
+      }
+
+      if (!followNextLink) {
+        const matchedCount = Array.from(merged.values())
+          .filter((row) => row.displayName || row.mail || row.userPrincipalName)
+          .filter((row) => matchesPeopleFilters(row, filters))
+          .length;
+        if (matchedCount >= maxRows) {
+          break;
+        }
+      }
+    }
+
+    return Array.from(merged.values())
+      .filter((row) => row.displayName || row.mail || row.userPrincipalName)
+      .filter((row) => matchesPeopleFilters(row, filters));
+  }
+
+  async whoAmI(options = {}) {
+    const directReportsSize = Number.isInteger(options.directReportsSize)
+      ? Math.min(100, Math.max(1, options.directReportsSize))
+      : 30;
+    const me = await this.fetchGraphJsonWithScopes(
+      ["User.Read", "User.ReadBasic.All", "User.Read.All", "Directory.Read.All"],
+      `/me?$select=${encodeURIComponent(DIRECTORY_PERSON_SELECT)}`
+    );
+
+    let manager = null;
+    try {
+      const managerRaw = await this.fetchGraphJsonWithScopes(
+        ["User.Read.All", "Directory.Read.All"],
+        `/me/manager?$select=${encodeURIComponent(DIRECTORY_PERSON_SELECT)}`
+      );
+
+      if (managerRaw && typeof managerRaw === "object") {
+        manager = normalizeDirectoryPerson(managerRaw, "manager");
+      }
+    } catch (err) {
+      if (!isIgnorableDirectoryLookupError(err)) {
+        this.logger.warn("[m365connector][graph] whoAmI manager lookup failed:", String(err?.message || err));
+      }
+    }
+
+    let directReports = [];
+    let directReportsCount = 0;
+    try {
+      const directReportsResponse = await this.fetchDirectReports(
+        "/me/directReports",
+        directReportsSize,
+        "directReport"
+      );
+      directReports = directReportsResponse.directReports;
+      directReportsCount = directReportsResponse.directReportsCount;
+    } catch (err) {
+      if (!isIgnorableDirectoryLookupError(err)) {
+        this.logger.warn("[m365connector][graph] whoAmI directReports lookup failed:", String(err?.message || err));
+      }
+    }
+
+    return {
+      ...normalizeDirectoryPerson(me, "me"),
+      manager,
+      directReports,
+      directReportsCount
+    };
+  }
+
+  async findPeople(params = {}) {
+    const filters = normalizePeopleFilters(params);
+    if (!Object.values(filters).some(Boolean)) {
+      throw new Error("At least one people filter is required");
+    }
+
+    const size = Number.isInteger(params.size)
+      ? Math.min(50, Math.max(1, params.size))
+      : 20;
+    const includeDirectReports = Boolean(params.include_direct_reports || params.includeDirectReports);
+    const directReportsSize = Number.isInteger(params.direct_reports_size)
+      ? Math.min(100, Math.max(1, params.direct_reports_size))
+      : Number.isInteger(params.directReportsSize)
+        ? Math.min(100, Math.max(1, params.directReportsSize))
+        : 30;
+    let results = (await this.queryPeopleResults(filters, size)).slice(0, size);
+
+    if (includeDirectReports && results.length) {
+      const settled = await mapWithConcurrencyLimit(
+        results,
+        PEOPLE_DIRECT_REPORT_CONCURRENCY,
+        async (person) => {
+          if (!person.id) {
+            throw new Error("Missing user id for directReports lookup");
+          }
+          return withTimeout(
+            this.fetchDirectReports(
+              `/users/${encodeURIComponent(person.id)}/directReports`,
+              directReportsSize,
+              "directReport"
+            ),
+            PEOPLE_DIRECT_REPORT_TIMEOUT_MS,
+            `directReports lookup timed out for ${person.id}`
+          );
+        }
+      );
+
+      results = results.map((person, index) => {
+        const outcome = settled[index];
+        if (!outcome || outcome.status !== "fulfilled") {
+          return {
+            ...person,
+            directReports: null,
+            directReportsCount: null
+          };
+        }
+        return {
+          ...person,
+          directReports: outcome.value.directReports,
+          directReportsCount: outcome.value.directReportsCount
+        };
+      });
+    }
+
+    return {
+      filters,
+      results,
+      total: results.length
+    };
+  }
+
+  async countPeople(params = {}) {
+    const filters = normalizePeopleFilters(params);
+    if (!Object.values(filters).some(Boolean)) {
+      throw new Error("At least one people filter is required");
+    }
+
+    const results = await this.queryPeopleResults(filters, 999, {
+      includeCount: true,
+      forceConsistencyLevel: true,
+      followNextLink: true,
+      maxRows: Number.MAX_SAFE_INTEGER
+    });
+
+    return {
+      filters,
+      count: results.length
+    };
+  }
+
+  readFileFallback(context, warningOverride = null) {
+    const content = String(context.summary || context.snippet || "");
+    return {
+      content,
+      contentType: "text",
+      completeness: "partial",
+      type: "file",
+      title: context.title || "",
+      url: context.url || "",
+      metadata: context.metadata || {},
+      warning: warningOverride || "File content comes from extracted summary, not full document bytes"
+    };
+  }
+
+  buildOfficeEditUrl(webUrl) {
+    try {
+      const url = new URL(webUrl);
+      url.searchParams.set("action", "edit");
+      return url.toString();
+    } catch (_err) {
+      const separator = String(webUrl || "").includes("?") ? "&" : "?";
+      return `${webUrl}${separator}action=edit`;
+    }
+  }
+
+  async waitForEditorInAnyFrame(tabId, deadline) {
+    const pollEnd = Math.min(Date.now() + 60000, deadline);
+
+    while (Date.now() < pollEnd) {
+      try {
+        const results = await chrome.scripting.executeScript({
+          target: { tabId, allFrames: true },
+          func: () => {
+            const host = location.hostname.toLowerCase();
+            if (!host.endsWith(".officeapps.live.com")) {
+              return null;
+            }
+            const hasPanel = Boolean(document.getElementById("WACViewPanel"));
+            const hasSlide = Boolean(
+              document.querySelector('[class*="slide"]')
+              || document.querySelector('[class*="Slide"]')
+            );
+            if (!hasPanel && !hasSlide) {
+              return null;
+            }
+            return "ready";
+          }
+        });
+
+        if (results && results.some((r) => r.result === "ready")) {
+          return true;
+        }
+      } catch (_err) {
+        // Frames may not be ready yet; keep polling.
+      }
+      await sleep(1000);
+    }
+
+    return false;
+  }
+
+  /**
+   * Scroll through the Word Online document inside the iframe so that all
+   * virtually-rendered pages get materialised in the DOM.  Returns the number
+   * of scroll steps performed (0 means no scrollable container was found).
+   */
+  async scrollToLoadAllPages(tabId, budgetMs = 60000) {
+    const stepEnd = Date.now() + Math.min(budgetMs, 60000);
+    let totalSteps = 0;
+
+    // Temporarily activate the tab — Word Online's virtual renderer only
+    // works in the focused window's active tab.  We restore the user's
+    // previous tab after scrolling completes.
+    let previousTabId = null;
+    try {
+      const [activeTab] = await chrome.tabs.query({ active: true, currentWindow: true });
+      if (activeTab) previousTabId = activeTab.id;
+      await chrome.tabs.update(tabId, { active: true });
+      await sleep(500);
+    } catch (_err) {
+      // If we can't activate, proceed anyway.
+    }
+
+    // Strategy: repeatedly jump to the bottom of the scroll container.
+    // Word Online lazily adds pages as the viewport approaches them, so each
+    // jump-to-bottom may increase scrollHeight as new pages materialise.
+    // We keep jumping until scrollHeight stabilises (no growth for 5 rounds).
+    let prevScrollHeight = 0;
+    let stableRounds = 0;
+
+    while (Date.now() < stepEnd && stableRounds < 5) {
+      try {
+        const results = await chrome.scripting.executeScript({
+          target: { tabId, allFrames: true },
+          func: () => {
+            const panel = document.getElementById("WACViewPanel");
+            if (!panel) return null;
+
+            // Find the scrollable container
+            let scroller = null;
+            let el = panel;
+            while (el) {
+              if (el.scrollHeight > el.clientHeight + 20) {
+                scroller = el;
+                break;
+              }
+              el = el.parentElement;
+            }
+            if (!scroller) return { done: true, scrollHeight: 0, pages: 0 };
+
+            // Jump to the very bottom
+            scroller.scrollTop = scroller.scrollHeight;
+
+            // Count rendered .Page elements
+            const pages = document.querySelectorAll(".Page");
+
+            return {
+              done: false,
+              scrollHeight: scroller.scrollHeight,
+              scrollTop: scroller.scrollTop,
+              pages: pages.length
+            };
+          }
+        });
+
+        const hit = results && results.find((r) => r.result);
+        if (!hit || !hit.result || hit.result.done) {
+          break;
+        }
+
+        totalSteps++;
+        const sh = hit.result.scrollHeight;
+        this.logger.info("[m365connector] scrollToLoadAllPages: step", totalSteps,
+          "scrollHeight=", sh, "pages=", hit.result.pages,
+          "prevScrollHeight=", prevScrollHeight);
+
+        if (sh <= prevScrollHeight) {
+          stableRounds++;
+        } else {
+          stableRounds = 0;
+        }
+        prevScrollHeight = sh;
+
+        // Wait for Word Online to render newly-visible pages
+        await sleep(1000);
+      } catch (_err) {
+        await sleep(500);
+      }
+    }
+
+    this.logger.info("[m365connector] scrollToLoadAllPages: finished after", totalSteps,
+      "steps, stableRounds=", stableRounds);
+
+    return totalSteps;
+  }
+
+  /**
+   * Word Online virtualizes long documents. Reading only once after jumping to
+   * the end can miss pages that have already been unloaded, so fullContent mode
+   * walks through the scroll container and accumulates visible page text.
+   */
+  async scrollAndCollectWordText(tabId, budgetMs = 60000) {
+    const stepEnd = Date.now() + Math.min(budgetMs, 60000);
+    const chunks = [];
+    const seen = new Set();
+    let totalSteps = 0;
+    let stableBottomRounds = 0;
+    let lastScrollHeight = 0;
+
+    const remember = (value) => {
+      const text = String(value || "").replace(/\u00a0/g, " ").replace(/[ \t]+/g, " ").trim();
+      if (text.length < 10) {
+        return;
+      }
+      const key = text.replace(/\s+/g, " ").slice(0, 5000);
+      if (seen.has(key)) {
+        return;
+      }
+      seen.add(key);
+      chunks.push(text);
+    };
+
+    let previousTabId = null;
+    try {
+      const [activeTab] = await chrome.tabs.query({ active: true, currentWindow: true });
+      if (activeTab) {
+        previousTabId = activeTab.id;
+      }
+      await chrome.tabs.update(tabId, { active: true });
+      await sleep(800);
+    } catch (_err) {
+      // If activation fails, still try to collect from the loaded DOM.
+    }
+
+    try {
+      await chrome.scripting.executeScript({
+        target: { tabId, allFrames: true },
+        func: () => {
+          const panel = document.getElementById("WACViewPanel");
+          if (!panel) return false;
+          let scroller = null;
+          let el = panel;
+          while (el) {
+            if (el.scrollHeight > el.clientHeight + 20) {
+              scroller = el;
+              break;
+            }
+            el = el.parentElement;
+          }
+          if (!scroller) return false;
+          scroller.scrollTop = 0;
+          return true;
+        }
+      }).catch(() => null);
+
+      while (Date.now() < stepEnd && stableBottomRounds < 4) {
+        const results = await chrome.scripting.executeScript({
+          target: { tabId, allFrames: true },
+          func: () => {
+            const panel = document.getElementById("WACViewPanel");
+            if (!panel) return null;
+
+            let scroller = null;
+            let el = panel;
+            while (el) {
+              if (el.scrollHeight > el.clientHeight + 20) {
+                scroller = el;
+                break;
+              }
+              el = el.parentElement;
+            }
+            if (!scroller) {
+              return {
+                chunks: [panel.innerText || ""],
+                done: true,
+                scrollTop: 0,
+                scrollHeight: 0,
+                clientHeight: 0,
+                pageCount: 0
+              };
+            }
+
+            const pageNodes = Array.from(document.querySelectorAll(".Page"));
+            const pageTexts = pageNodes
+              .map((node) => node.innerText || node.textContent || "")
+              .map((text) => text.trim())
+              .filter((text) => text.length >= 10);
+            const chunks = pageTexts.length ? pageTexts : [panel.innerText || ""];
+
+            const scrollTop = scroller.scrollTop;
+            const scrollHeight = scroller.scrollHeight;
+            const clientHeight = scroller.clientHeight;
+            const atBottom = scrollTop + clientHeight >= scrollHeight - 24;
+            if (!atBottom) {
+              const step = Math.max(Math.floor(clientHeight * 0.85), 500);
+              scroller.scrollTop = Math.min(scrollHeight, scrollTop + step);
+            }
+
+            return {
+              chunks,
+              done: atBottom,
+              scrollTop,
+              scrollHeight,
+              clientHeight,
+              pageCount: pageNodes.length
+            };
+          }
+        });
+
+        const hit = results && results.find((row) => row.result);
+        const value = hit?.result;
+        if (!value) {
+          await sleep(700);
+          continue;
+        }
+
+        for (const chunk of value.chunks || []) {
+          remember(chunk);
+        }
+
+        totalSteps++;
+        if (value.done) {
+          stableBottomRounds = value.scrollHeight <= lastScrollHeight ? stableBottomRounds + 1 : 0;
+        } else {
+          stableBottomRounds = 0;
+        }
+        lastScrollHeight = value.scrollHeight || lastScrollHeight;
+
+        this.logger.info(
+          "[m365connector] scrollAndCollectWordText: step %d scrollTop=%s scrollHeight=%s pages=%s chunks=%s bottomRounds=%s",
+          totalSteps,
+          value.scrollTop,
+          value.scrollHeight,
+          value.pageCount,
+          chunks.length,
+          stableBottomRounds
+        );
+
+        await sleep(value.done ? 900 : 600);
+      }
+    } finally {
+      if (previousTabId && previousTabId !== tabId) {
+        try {
+          await chrome.tabs.update(previousTabId, { active: true });
+        } catch (_err) {
+          // Best-effort; the original tab may have been closed.
+        }
+      }
+    }
+
+    const content = chunks.join("\n\n").trim();
+    this.logger.info(
+      "[m365connector] scrollAndCollectWordText: finished after %d steps, chunks=%d, chars=%d",
+      totalSteps,
+      chunks.length,
+      content.length
+    );
+    return { text: content, steps: totalSteps, chunks: chunks.length };
+  }
+
+  async extractWordText(tabId, budgetMs = 15000, options = {}) {
+    const totalBudget = Math.min(budgetMs, 70000);
+    const pollEnd = Date.now() + totalBudget;
+
+    // First, wait for the panel to appear
+    let panelReady = false;
+    while (Date.now() < pollEnd) {
+      try {
+        const results = await chrome.scripting.executeScript({
+          target: { tabId, allFrames: true },
+          func: () => {
+            const panel = document.getElementById("WACViewPanel");
+            return panel && panel.innerText && panel.innerText.trim().length >= 20;
+          }
+        });
+        if (results && results.some((r) => r.result)) {
+          panelReady = true;
+          break;
+        }
+      } catch (_err) { /* keep waiting */ }
+      await sleep(1000);
+    }
+    if (!panelReady) return null;
+
+    // Scroll through the document to force all pages to render (fullContent only)
+    if (options.fullContent) {
+      const scrollBudget = Math.min(60000, pollEnd - Date.now());
+      if (scrollBudget > 2000) {
+        const collected = await this.scrollAndCollectWordText(tabId, scrollBudget);
+        if (collected.text && collected.text.length >= 10) {
+          return collected.text;
+        }
+      }
+    }
+
+    // Now extract the full text
+    try {
+      const results = await chrome.scripting.executeScript({
+        target: { tabId, allFrames: true },
+        func: () => {
+          const panel = document.getElementById("WACViewPanel");
+          if (!panel || !panel.innerText || panel.innerText.trim().length < 10) {
+            return null;
+          }
+          return panel.innerText.trim();
+        }
+      });
+      const hit = results && results.find((r) => r.result);
+      if (hit) return hit.result;
+    } catch (_err) { /* fall through */ }
+
+    return null;
+  }
+
+  async extractPowerPointText(tabId, budgetMs = 15000) {
+    const pollEnd = Date.now() + Math.min(budgetMs, 15000);
+    while (Date.now() < pollEnd) {
+      try {
+        const results = await chrome.scripting.executeScript({
+          target: { tabId, allFrames: true },
+          func: () => {
+            const runs = document.querySelectorAll("span.NormalTextRun");
+            if (!runs.length) {
+              return null;
+            }
+            const text = Array.from(runs)
+              .map((run) => run.textContent)
+              .filter(Boolean)
+              .join(" ")
+              .replace(/\s+/g, " ")
+              .trim();
+            return text.length > 10 ? text : null;
+          }
+        });
+
+        const hit = results && results.find((r) => r.result);
+        if (hit) {
+          return hit.result;
+        }
+      } catch (_err) {
+        // Keep polling until budget is exhausted.
+      }
+      await sleep(1000);
+    }
+    return null;
+  }
+
+  async readFileViaDeepLink(context, options = {}) {
+    const ext = getFileExtension(context);
+    if (ext !== "docx") {
+      return null;
+    }
+
+    const webUrl = context.webUrl || context.url || "";
+    if (!webUrl) {
+      return null;
+    }
+
+    if (!isAllowedSharePointUrl(webUrl)) {
+      this.logger.warn(
+        "[m365connector] readFileViaDeepLink: rejected non-SharePoint URL:",
+        String(webUrl).substring(0, 60)
+      );
+      return null;
+    }
+
+    if (this.#deepLinkActive) {
+      this.logger.warn("[m365connector] readFileViaDeepLink: another extraction in progress, skipping");
+      return { skipped: "busy" };
+    }
+
+    const DEEP_LINK_BUDGET_MS = 90000;
+    const deadline = Date.now() + DEEP_LINK_BUDGET_MS;
+    const editUrl = this.buildOfficeEditUrl(webUrl);
+    let tabId = null;
+
+    this.#deepLinkActive = true;
+    try {
+      const tab = await chrome.tabs.create({ url: editUrl, active: true });
+      tabId = tab.id;
+
+      await this.waitForTabLoad(tabId, Math.min(15000, deadline - Date.now()));
+      await chrome.tabs.update(tabId, { active: true }).catch(() => null);
+
+      // SharePoint auto-submits the WOPI form into a cross-origin iframe where
+      // Word/PowerPoint Online renders.  Wait for the editor to become ready in
+      // any frame (main page or iframe) instead of trying to hijack the form.
+      const editorReady = await this.waitForEditorInAnyFrame(tabId, deadline);
+      if (!editorReady) {
+        this.logger.warn("[m365connector] readFileViaDeepLink: Office editor not ready in any frame");
+        return null;
+      }
+
+      const remaining = deadline - Date.now();
+      if (remaining < 2000) {
+        this.logger.warn("[m365connector] readFileViaDeepLink: budget exhausted before extraction");
+        return null;
+      }
+
+      const text = await this.extractWordText(tabId, remaining, options);
+
+      if (!text || !text.trim()) {
+        return null;
+      }
+
+      return {
+        content: text.trim(),
+        contentType: "text",
+        completeness: "full",
+        type: "file",
+        title: context.title || "",
+        url: context.url || context.webUrl || "",
+        metadata: context.metadata || {},
+        warning: "Content extracted via Office Online deep-link (not raw file bytes)"
+      };
+    } catch (err) {
+      this.logger.warn("[m365connector] readFileViaDeepLink failed:", err?.message || err);
+      return null;
+    } finally {
+      this.#deepLinkActive = false;
+      if (tabId !== null) {
+        try {
+          await chrome.tabs.remove(tabId);
+        } catch (_err) {
+          // Ignore if tab already closed.
+        }
+      }
+    }
+  }
+
+  async readEmailViaDeepLink(context) {
+    const itemId = this.getEmailItemId(context);
+    const deepLink =
+      context.url ||
+      `https://outlook.office.com/mail/deeplink?exvsurl=1&ItemID=${encodeURIComponent(itemId)}`;
+
+    let tabId = null;
+    let previousActiveTabId = null;
+    let activatedForDecryption = false;
+    try {
+      previousActiveTabId = await this.getActiveTabId();
+      const tab = await chrome.tabs.create({ url: deepLink, active: false });
+      tabId = tab.id;
+
+      // Wait for tab to finish loading instead of polling blindly
+      await this.waitForTabLoad(tabId, 15000);
+
+      // Page loaded — now poll for DOM content.
+      // IRM-protected emails decrypt asynchronously: OWA first renders an
+      // encrypted wrapper ("sent you a protected message …"), then replaces it
+      // with the real body once Azure RMS decryption completes.  We therefore
+      // keep polling if the content looks like an IRM wrapper, using an
+      // extended window (up to IRM_POLL_MS) to give decryption time to finish.
+      // IRM_POLL_MS is a generous safety cap, not a decryption expectation —
+      // the loop exits as soon as real content appears.
+      const BASE_POLL_MS = 40000;
+      const IRM_POLL_MS = 60000;
+      let sawEncryptedWrapper = false;
+      let stableContent = null;
+      let followedReadMessageUrl = false;
+      const startedAt = Date.now();
+      const pollDeadline = () => sawEncryptedWrapper ? IRM_POLL_MS : BASE_POLL_MS;
+
+      while (Date.now() - startedAt < pollDeadline()) {
+        try {
+          const executions = await chrome.scripting.executeScript({
+            target: { tabId, allFrames: true },
+            func: (selectors) => {
+              const candidates = [];
+              const seen = new Set();
+              const readMessageUrls = [];
+              for (const selector of selectors) {
+                for (const el of document.querySelectorAll(selector)) {
+                  if (el && typeof el.innerText === "string") {
+                    const text = el.innerText.trim();
+                    if (text && !seen.has(text)) {
+                      seen.add(text);
+                      candidates.push(text);
+                    }
+                  }
+                }
+              }
+              const bodyText = document.body?.innerText?.trim();
+              if (bodyText && !seen.has(bodyText)) {
+                seen.add(bodyText);
+                candidates.push(bodyText);
+              }
+              for (const link of document.querySelectorAll("a[href]")) {
+                const label = `${link.innerText || ""} ${link.getAttribute("aria-label") || ""}`.toLowerCase();
+                const href = String(link.href || "");
+                if (href && (label.includes("read the message") || href.includes("viewmodel=ReadMessageItem"))) {
+                  readMessageUrls.push(href);
+                }
+              }
+              return { candidates, readMessageUrls };
+            },
+            args: [EMAIL_SELECTORS]
+          });
+
+          const extraction = this.selectEmailExtraction(executions);
+          if (extraction.encrypted && extraction.readMessageUrl && !followedReadMessageUrl && tabId !== null) {
+            followedReadMessageUrl = true;
+            sawEncryptedWrapper = true;
+            this.logger.info("[m365connector][deeplink] following protected-message read link");
+            await this.navigateTabAndWait(tabId, extraction.readMessageUrl, 15000).catch(() => {});
+            await sleep(1000);
+            continue;
+          }
+
+          if (extraction.sawEncrypted && !activatedForDecryption && tabId !== null) {
+            // OWA can defer protected-message decryption in an inactive tab.
+            // Briefly activate the deeplink tab once so the visible reading
+            // pane gets a chance to replace the Purview wrapper with the body.
+            activatedForDecryption = true;
+            try {
+              await chrome.tabs.update(tabId, { active: true });
+            } catch (_err) {
+              // Best-effort; continue polling hidden if activation fails.
+            }
+          }
+
+          if (extraction.text && extraction.text.length > 0) {
+            if (extraction.encrypted) {
+              // IRM wrapper detected — OWA is still decrypting; keep polling.
+              if (!sawEncryptedWrapper) {
+                sawEncryptedWrapper = true;
+                this.logger.info("[m365connector][deeplink] IRM wrapper detected, extending poll window for decryption");
+              }
+            } else {
+              const extracted = extraction.text;
+              // Content is not an IRM wrapper.  If we previously saw the
+              // encrypted wrapper, wait one extra poll to confirm the
+              // content has stabilised (guards against partial rendering
+              // during the decryption transition).
+              if (sawEncryptedWrapper && !stableContent) {
+                stableContent = extracted;
+                // fall through to sleep and re-check
+              } else if (sawEncryptedWrapper && stableContent && stableContent.length !== extracted.length) {
+                // Content is still changing — update and keep polling
+                stableContent = extracted;
+              } else {
+                return {
+                  content: extracted,
+                  contentType: "text",
+                  completeness: "full",
+                  type: "email",
+                  title: context.title || "",
+                  url: deepLink,
+                  metadata: {},
+                  warning: undefined
+                };
+              }
+            }
+          }
+        } catch (_err) {
+          // Page may not be ready yet; keep polling.
+        }
+
+        await sleep(500);
+      }
+
+      return {
+        content: context.snippet || "",
+        contentType: "text",
+        completeness: "snippet",
+        type: "email",
+        title: context.title || "",
+        url: deepLink,
+        metadata: {},
+        warning: "Email extraction timed out; returning search snippet"
+      };
+    } finally {
+      if (tabId !== null) {
+        try {
+          await chrome.tabs.remove(tabId);
+        } catch (_err) {
+          // Ignore if tab already closed.
+        }
+      }
+      if (activatedForDecryption && previousActiveTabId && previousActiveTabId !== tabId) {
+        try {
+          await chrome.tabs.update(previousActiveTabId, { active: true });
+        } catch (_err) {
+          // Best-effort; the original tab may have been closed.
+        }
+      }
+    }
+  }
+
+  async getActiveTabId() {
+    try {
+      const tabs = await chrome.tabs.query({ active: true, currentWindow: true });
+      const id = tabs?.[0]?.id;
+      return Number.isInteger(id) ? id : null;
+    } catch (_err) {
+      return null;
+    }
+  }
+
+  selectEmailExtraction(executions) {
+    let encryptedText = null;
+    let plainText = null;
+    let readMessageUrl = null;
+    const rows = Array.isArray(executions) ? executions : [];
+
+    for (const execution of rows) {
+      const result = execution?.result;
+      if (result && typeof result === "object" && !Array.isArray(result)) {
+        if (!readMessageUrl && Array.isArray(result.readMessageUrls)) {
+          readMessageUrl = result.readMessageUrls.find(Boolean) || null;
+        }
+      }
+      const values = Array.isArray(result)
+        ? result
+        : Array.isArray(result?.candidates)
+          ? result.candidates
+          : [result];
+      for (const value of values) {
+        const text = String(value || "").trim();
+        const lowerText = text.toLowerCase();
+        if (!text || lowerText === "loading" || lowerText === "get data") {
+          continue;
+        }
+        if (this.isEncryptedEmailContent(text)) {
+          if (text.length > (encryptedText?.length || 0)) {
+            encryptedText = text;
+          }
+        } else if (text.length > (plainText?.length || 0)) {
+          plainText = text;
+        }
+      }
+    }
+
+    return {
+      text: plainText || encryptedText || null,
+      encrypted: Boolean(!plainText && encryptedText),
+      sawEncrypted: Boolean(encryptedText),
+      readMessageUrl
+    };
+  }
+
+  async navigateTabAndWait(tabId, url, timeoutMs) {
+    await new Promise((resolve) => {
+      let settled = false;
+      let timeoutId = null;
+
+      const cleanup = () => {
+        if (timeoutId !== null) {
+          clearTimeout(timeoutId);
+        }
+        chrome.tabs.onUpdated.removeListener(onUpdated);
+      };
+
+      const finish = () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        cleanup();
+        resolve();
+      };
+
+      const onUpdated = (updatedTabId, changeInfo) => {
+        if (updatedTabId === tabId && changeInfo.status === "complete") {
+          finish();
+        }
+      };
+
+      chrome.tabs.onUpdated.addListener(onUpdated);
+      timeoutId = setTimeout(finish, timeoutMs);
+      Promise.resolve(chrome.tabs.update(tabId, { url, active: true })).catch(finish);
+    });
+  }
+
+  waitForTabLoad(tabId, timeoutMs) {
+    return new Promise((resolve) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          chrome.tabs.onUpdated.removeListener(listener);
+          resolve();
+        }
+      }, timeoutMs);
+
+      function listener(updatedTabId, changeInfo) {
+        if (updatedTabId === tabId && changeInfo.status === "complete") {
+          if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            chrome.tabs.onUpdated.removeListener(listener);
+            resolve();
+          }
+        }
+      }
+
+      chrome.tabs.onUpdated.addListener(listener);
+
+      // Check if already complete (race condition: tab may have loaded before listener attached)
+      chrome.tabs.get(tabId).then((tab) => {
+        if (tab?.status === "complete" && !settled) {
+          settled = true;
+          clearTimeout(timer);
+          chrome.tabs.onUpdated.removeListener(listener);
+          resolve();
+        }
+      }).catch(() => {
+        // Tab may not exist anymore; resolve to let caller handle it
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          chrome.tabs.onUpdated.removeListener(listener);
+          resolve();
+        }
+      });
+    });
+  }
+
+  async readEmailViaGraph(token, context) {
+    const ownerId = this.getOwnerIdentity(context, "mailbox");
+    const basePath = ownerId ? `/users/${encodeURIComponent(ownerId)}` : "/me";
+    const itemId = this.getEmailItemId(context);
+
+    const message = await this.fetchWithTranslatedId({
+      token,
+      basePath,
+      rawId: itemId,
+      entityPath: "messages",
+      cacheNamespace: `email:${ownerId || "me"}`,
+      select:
+        "subject,body,bodyPreview,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments",
+      prefer: 'outlook.body-content-type="text"'
+    });
+
+    const bodyContent = String(message?.body?.content || "");
+    const content = message?.body?.contentType === "html"
+      ? htmlToText(bodyContent)
+      : String(bodyContent || message?.bodyPreview || context.snippet || "").trim();
+
+    return {
+      content,
+      contentType: "text",
+      completeness: content ? "full" : "snippet",
+      type: "email",
+      title: context.title || String(message?.subject || ""),
+      url: context.url || "",
+      metadata: {
+        subject: message?.subject || "",
+        from: message?.from?.emailAddress?.address || "",
+        toRecipients: Array.isArray(message?.toRecipients)
+          ? message.toRecipients.map((r) => r?.emailAddress?.address || r?.emailAddress?.name || "").filter(Boolean)
+          : [],
+        ccRecipients: Array.isArray(message?.ccRecipients)
+          ? message.ccRecipients.map((r) => r?.emailAddress?.address || r?.emailAddress?.name || "").filter(Boolean)
+          : [],
+        receivedDateTime: message?.receivedDateTime || "",
+        hasAttachments: Boolean(message?.hasAttachments)
+      },
+      warning: undefined
+    };
+  }
+
+  async readEventViaGraph(token, context) {
+    const ownerId = this.getOwnerIdentity(context, "calendar");
+    const basePath = ownerId ? `/users/${encodeURIComponent(ownerId)}` : "/me";
+
+    const event = await this.fetchWithTranslatedId({
+      token,
+      basePath,
+      rawId: context.id,
+      entityPath: "events",
+      cacheNamespace: `event:${ownerId || "me"}`,
+      select: "subject,start,end,organizer,attendees,location,body,bodyPreview,onlineMeeting",
+      prefer: 'outlook.timezone="UTC", outlook.body-content-type="text"'
+    });
+
+    const attendees = Array.isArray(event?.attendees)
+      ? event.attendees
+          .map((attendee) => attendee?.emailAddress?.address || attendee?.emailAddress?.name || "")
+          .filter(Boolean)
+      : [];
+
+    const bodyText = event?.body?.contentType === "html"
+      ? htmlToText(String(event?.body?.content || ""))
+      : String(event?.body?.content || "").trim();
+
+    const contentParts = [
+      event?.subject ? `Subject: ${event.subject}` : "",
+      event?.start?.dateTime ? `Start: ${event.start.dateTime}` : "",
+      event?.end?.dateTime ? `End: ${event.end.dateTime}` : "",
+      event?.location?.displayName ? `Location: ${event.location.displayName}` : "",
+      event?.organizer?.emailAddress?.address
+        ? `Organizer: ${event.organizer.emailAddress.address}`
+        : "",
+      attendees.length ? `Attendees: ${attendees.join(", ")}` : "",
+      bodyText ? `Body: ${bodyText}` : "",
+      event?.onlineMeeting?.joinUrl ? `Meeting URL: ${event.onlineMeeting.joinUrl}` : ""
+    ].filter(Boolean);
+
+    return {
+      content: contentParts.join("\n"),
+      contentType: "text",
+      completeness: contentParts.length ? "full" : "snippet",
+      type: "event",
+      title: context.title || String(event?.subject || ""),
+      url: context.url || "",
+      metadata: {
+        subject: event?.subject || "",
+        startTime: event?.start?.dateTime || "",
+        endTime: event?.end?.dateTime || "",
+        location: event?.location?.displayName || "",
+        organizer: event?.organizer?.emailAddress?.address || "",
+        attendees,
+        bodyPreview: event?.bodyPreview || "",
+        meetingUrl: event?.onlineMeeting?.joinUrl || ""
+      },
+      warning: undefined
+    };
+  }
+
+  async readFileViaGraph(token, context) {
+    const driveItem = await this.resolveDriveItem(token, context);
+    if (!driveItem) {
+      throw new GraphHttpError("Drive item unavailable", 404);
+    }
+
+    const size = Number(driveItem.size || context.size || 0);
+    if (Number.isFinite(size) && size > TEN_MB) {
+      return this.readFileFallback(
+        context,
+        `File is ${size} bytes (> 10MB limit); returning summary instead of downloading bytes`
+      );
+    }
+
+    const downloadUrl = driveItem["@microsoft.graph.downloadUrl"];
+    if (!downloadUrl) {
+      // Graph returned the item metadata but no download URL.  This is a
+      // per-file limitation (cross-tenant, restricted permissions, etc.),
+      // NOT a Graph API failure — so return null instead of throwing,
+      // which would otherwise count toward the circuit breaker.
+      this.logger.info("[m365connector][graph] readFileViaGraph: no downloadUrl in driveItem (id=%s), falling back",
+        String(driveItem.id || context.id || "").substring(0, 40));
+      return null;
+    }
+
+    const downloadResponse = await fetch(downloadUrl);
+    if (!downloadResponse.ok) {
+      const text = await downloadResponse.text().catch(() => "");
+      throw new GraphHttpError(
+        `File download failed (${downloadResponse.status})`,
+        downloadResponse.status,
+        text,
+        retryAfterSeconds(downloadResponse.headers.get("retry-after"))
+      );
+    }
+
+    const arrayBuffer = await downloadResponse.arrayBuffer();
+    const bytes = new Uint8Array(arrayBuffer);
+    if (this.isEncryptedCdf(bytes)) {
+      return this.readFileFallback(
+        context,
+        "File appears sensitivity-label encrypted; returning summary fallback"
+      );
+    }
+
+    const ext = getFileExtension(context, driveItem);
+    const parsed = await this.extractFileContent(ext, arrayBuffer);
+    if (!parsed || !parsed.trim()) {
+      return this.readFileFallback(
+        context,
+        `Unable to parse .${ext || "unknown"} file; returning summary fallback`
+      );
+    }
+
+    return {
+      content: parsed,
+      contentType: "text",
+      completeness: "full",
+      type: "file",
+      title: context.title || driveItem.name || "",
+      url: context.url || context.webUrl || "",
+      metadata: {
+        ...(context.metadata || {}),
+        graphDriveItemId: driveItem.id || "",
+        graphName: driveItem.name || "",
+        size: Number.isFinite(size) ? size : undefined
+      },
+      warning: undefined
+    };
+  }
+
+  async resolveDriveItem(token, context) {
+    const webUrl = String(context.webUrl || "").trim();
+    if (webUrl) {
+      const encodedUrl = `u!${base64UrlEncode(webUrl)}`;
+      try {
+        return await this.fetchGraphJson(
+          token,
+          `/shares/${encodedUrl}/driveItem?$select=id,name,size,@microsoft.graph.downloadUrl,file`
+        );
+      } catch (err) {
+        if (err?.status !== 404 && err?.status !== 400) {
+          throw err;
+        }
+      }
+    }
+
+    if (context.id) {
+      return this.fetchGraphJson(
+        token,
+        `/me/drive/items/${encodeURIComponent(context.id)}?$select=id,name,size,@microsoft.graph.downloadUrl,file`
+      );
+    }
+
+    return null;
+  }
+
+  async extractFileContent(ext, arrayBuffer) {
+    const lowerExt = String(ext || "").toLowerCase();
+
+    if (["txt", "md", "json", "csv"].includes(lowerExt)) {
+      return new TextDecoder("utf-8", { fatal: false }).decode(arrayBuffer).trim();
+    }
+
+    if (!["docx", "xlsx", "pptx"].includes(lowerExt)) {
+      return "";
+    }
+
+    const JSZip = await ensureJsZipAvailable();
+    if (!JSZip) {
+      return "";
+    }
+
+    let zip = null;
+    try {
+      zip = await JSZip.loadAsync(arrayBuffer);
+    } catch (_err) {
+      // Corrupt or non-zip payload with Office extension; caller will fallback.
+      return "";
+    }
+
+    if (lowerExt === "docx") {
+      return this.parseDocx(zip);
+    }
+    if (lowerExt === "xlsx") {
+      return this.parseXlsx(zip);
+    }
+    if (lowerExt === "pptx") {
+      return this.parsePptx(zip);
+    }
+
+    return "";
+  }
+
+  async parseDocx(zip) {
+    const documentXml = await zip.file("word/document.xml")?.async("text");
+    if (!documentXml) {
+      return "";
+    }
+
+    const paragraphs = documentXml.match(/<w:p[\s\S]*?<\/w:p>/g) || [];
+    const lines = [];
+    for (const paragraph of paragraphs) {
+      const textRuns = extractTagValues(paragraph, "w:t");
+      const line = textRuns.join("").trim();
+      if (line) {
+        lines.push(line);
+      }
+    }
+
+    return lines.join("\n").trim();
+  }
+
+  async parsePptx(zip) {
+    const slideFiles = Object.keys(zip.files)
+      .filter((name) => /^ppt\/slides\/slide\d+\.xml$/i.test(name))
+      .sort((a, b) => {
+        const aNum = parseInt((a.match(/slide(\d+)\.xml/i) || [])[1] || "0", 10);
+        const bNum = parseInt((b.match(/slide(\d+)\.xml/i) || [])[1] || "0", 10);
+        return aNum - bNum;
+      });
+
+    const sections = [];
+    for (const file of slideFiles) {
+      const xml = await zip.file(file)?.async("text");
+      if (!xml) {
+        continue;
+      }
+      const slideNum = parseInt((file.match(/slide(\d+)\.xml/i) || [])[1] || "0", 10);
+      const runs = extractTagValues(xml, "a:t").map((value) => value.trim()).filter(Boolean);
+      if (!runs.length) {
+        continue;
+      }
+      sections.push(`Slide ${slideNum}:\n${runs.join("\n")}`);
+    }
+
+    return sections.join("\n\n").trim();
+  }
+
+  async parseXlsx(zip) {
+    const sharedStringsXml = await zip.file("xl/sharedStrings.xml")?.async("text");
+    const sharedStrings = this.parseSharedStrings(sharedStringsXml || "");
+
+    const sheetFiles = Object.keys(zip.files)
+      .filter((name) => /^xl\/worksheets\/sheet\d+\.xml$/i.test(name))
+      .sort((a, b) => {
+        const aNum = parseInt((a.match(/sheet(\d+)\.xml/i) || [])[1] || "0", 10);
+        const bNum = parseInt((b.match(/sheet(\d+)\.xml/i) || [])[1] || "0", 10);
+        return aNum - bNum;
+      });
+
+    const allSheets = [];
+    for (const file of sheetFiles) {
+      const xml = await zip.file(file)?.async("text");
+      if (!xml) {
+        continue;
+      }
+      const rows = this.parseSheetRows(xml, sharedStrings);
+      if (!rows.length) {
+        continue;
+      }
+      const sheetNum = parseInt((file.match(/sheet(\d+)\.xml/i) || [])[1] || "0", 10);
+      allSheets.push(`Sheet ${sheetNum}:\n${rows.join("\n")}`);
+    }
+
+    return allSheets.join("\n\n").trim();
+  }
+
+  parseSharedStrings(xml) {
+    const values = [];
+    const items = xml.match(/<si>[\s\S]*?<\/si>/g) || [];
+    for (const item of items) {
+      const runs = extractTagValues(item, "t");
+      values.push(runs.join(""));
+    }
+    return values;
+  }
+
+  parseSheetRows(xml, sharedStrings) {
+    const rows = [];
+    const rowMatches = xml.match(/<row[^>]*>[\s\S]*?<\/row>/g) || [];
+
+    for (const rowXml of rowMatches) {
+      const cells = [];
+      const cellPattern = /<c([^>]*)>([\s\S]*?)<\/c>/g;
+      let cellMatch;
+      while ((cellMatch = cellPattern.exec(rowXml)) !== null) {
+        const attrs = cellMatch[1] || "";
+        const body = cellMatch[2] || "";
+        // OOXML may omit the cell reference; we then append sequentially as best-effort.
+        const ref = (attrs.match(/\sr="([A-Z]+\d+)"/i) || [])[1] || "";
+        const colRef = (ref.match(/[A-Z]+/i) || [])[0] || "";
+        const colIdx = this.columnRefToIndex(colRef);
+
+        const type = (attrs.match(/\st="([^"]+)"/i) || [])[1] || "";
+        let value = "";
+
+        if (type === "s") {
+          const rawIndex = (body.match(/<v>([\s\S]*?)<\/v>/i) || [])[1];
+          const index = parseInt(String(rawIndex || ""), 10);
+          if (Number.isInteger(index) && sharedStrings[index] != null) {
+            value = sharedStrings[index];
+          }
+        } else if (type === "inlineStr") {
+          value = extractTagValues(body, "t").join("");
+        } else {
+          value = decodeXmlEntities((body.match(/<v>([\s\S]*?)<\/v>/i) || [])[1] || "");
+        }
+
+        if (colIdx >= 0) {
+          cells[colIdx] = value;
+        } else {
+          cells.push(value);
+        }
+      }
+
+      if (cells.length) {
+        rows.push(cells.map((cell) => String(cell || "")).join("\t").trimEnd());
+      }
+    }
+
+    return rows.filter(Boolean);
+  }
+
+  columnRefToIndex(columnRef) {
+    if (!columnRef) {
+      return -1;
+    }
+    let value = 0;
+    const upper = String(columnRef).toUpperCase();
+    for (let i = 0; i < upper.length; i += 1) {
+      const code = upper.charCodeAt(i);
+      if (code < 65 || code > 90) {
+        return -1;
+      }
+      value = value * 26 + (code - 64);
+    }
+    return value - 1;
+  }
+
+  isEncryptedEmailContent(content) {
+    if (!content || !content.trim()) {
+      return false;
+    }
+    const lower = content.toLowerCase();
+    // Multiple resilient markers for IRM/Purview wrapper detection.
+    // Any single strong indicator is sufficient; the AND of two weaker
+    // phrases guards against false positives from normal email text.
+    if (lower.includes("sent you a protected message") && lower.includes("microsoft purview message encryption")) {
+      return true;
+    }
+    if (lower.includes("sent you a protected message") && lower.includes("read the message")) {
+      return true;
+    }
+    if (lower.includes("azure information protection") && lower.includes("protected message")) {
+      return true;
+    }
+    if (lower.includes("microsoft information protection") && lower.includes("protected")) {
+      return true;
+    }
+    if (lower.includes("encrypt.compliance.microsoft.com") || lower.includes("rights-protected message")) {
+      return true;
+    }
+    if (lower.includes("aka.ms/protectedmessage")) {
+      return true;
+    }
+    return false;
+  }
+
+  isEncryptedCdf(bytes) {
+    if (!bytes || bytes.length < 4) {
+      return false;
+    }
+    return bytes[0] === 0xd0 && bytes[1] === 0xcf && bytes[2] === 0x11 && bytes[3] === 0xe0;
+  }
+
+  isSharePointResource(context) {
+    const url = String(context?.webUrl || context?.url || "").toLowerCase();
+    return url.includes(".sharepoint.com/") || url.includes(".sharepoint-df.com/");
+  }
+
+  getEmailItemId(context) {
+    return String(context?.id || "").trim()
+      || extractOutlookDeepLinkItemId(context?.url)
+      || extractOutlookDeepLinkItemId(context?.webUrl);
+  }
+
+  getOwnerIdentity(context, kind) {
+    const metadata = context?.metadata || {};
+    if (kind === "mailbox") {
+      return (
+        context.mailboxOwnerId ||
+        context.ownerId ||
+        metadata.mailboxOwnerId ||
+        metadata.ownerId ||
+        metadata.mailboxOwnerUpn ||
+        ""
+      );
+    }
+
+    return (
+      context.calendarOwnerId ||
+      context.ownerId ||
+      metadata.calendarOwnerId ||
+      metadata.ownerId ||
+      metadata.calendarOwnerUpn ||
+      ""
+    );
+  }
+
+  async fetchWithTranslatedId({ token, basePath, rawId, entityPath, cacheNamespace, select, prefer }) {
+    const cacheKey = `${cacheNamespace}:${rawId}`;
+    const cached = this.getTranslatedId(cacheKey);
+    const hadCachedTranslation = Boolean(cached && cached !== rawId);
+
+    if (hadCachedTranslation) {
+      try {
+        return await this.fetchGraphJson(
+          token,
+          `${basePath}/${entityPath}/${encodeURIComponent(cached)}?$select=${encodeURIComponent(select)}`,
+          {
+            headers: {
+              Prefer: prefer
+            }
+          }
+        );
+      } catch (err) {
+        if (err?.status !== 404) {
+          throw err;
+        }
+        this.translationCache.delete(cacheKey);
+      }
+    }
+
+    try {
+      return await this.fetchGraphJson(
+        token,
+        `${basePath}/${entityPath}/${encodeURIComponent(rawId)}?$select=${encodeURIComponent(select)}`,
+        {
+          headers: {
+            Prefer: prefer
+          }
+        }
+      );
+    } catch (err) {
+      if (err?.status !== 404) {
+        throw err;
+      }
+      if (hadCachedTranslation) {
+        throw new GraphHttpError("Resource not found using cached and raw IDs", 404);
+      }
+    }
+
+    const translated = await this.translateExchangeId(token, basePath, rawId);
+    if (translated && translated !== rawId) {
+      this.setTranslatedId(cacheKey, translated);
+      return this.fetchGraphJson(
+        token,
+        `${basePath}/${entityPath}/${encodeURIComponent(translated)}?$select=${encodeURIComponent(select)}`,
+        {
+          headers: {
+            Prefer: prefer
+          }
+        }
+      );
+    }
+
+    throw new GraphHttpError("Resource not found after ID translation", 404);
+  }
+
+  getTranslatedId(key) {
+    const entry = this.translationCache.get(key);
+    if (!entry) {
+      return null;
+    }
+    if (entry.expiresAt <= nowMs()) {
+      this.translationCache.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+
+  setTranslatedId(key, value) {
+    if (this.translationCache.has(key)) {
+      this.translationCache.delete(key);
+    }
+    this.translationCache.set(key, {
+      value,
+      expiresAt: nowMs() + TRANSLATION_CACHE_MS
+    });
+    evictOldestEntries(this.translationCache, MAX_CACHE_ENTRIES);
+  }
+
+  async translateExchangeId(token, basePath, id) {
+    const response = await this.fetchGraphJson(token, `${basePath}/translateExchangeIds`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        inputIds: [id],
+        sourceIdType: "ewsId",
+        targetIdType: "restId"
+      })
+    });
+
+    const values = Array.isArray(response?.value) ? response.value : [];
+    const first = values[0];
+    return first?.targetId || null;
+  }
+
+  async tryGraphRead(contentType, itemId, requiredScope, operation) {
+    if (!this.graphTokenProvider) {
+      this.logger.info("[m365connector][graph] tryGraphRead(%s): no graphTokenProvider", contentType);
+      return null;
+    }
+    if (!itemId) {
+      this.logger.info("[m365connector][graph] tryGraphRead(%s): no itemId", contentType);
+      return null;
+    }
+    this.pruneCaches();
+    if (this.isCircuitOpen(contentType)) {
+      this.logger.info("[m365connector][graph] tryGraphRead(%s): circuit open", contentType);
+      return null;
+    }
+    if (this.isDeniedCached(contentType, itemId)) {
+      this.logger.info("[m365connector][graph] tryGraphRead(%s): denied cached for %s", contentType, itemId);
+      return null;
+    }
+
+    let token = await this.graphTokenProvider.getToken(requiredScope || undefined);
+    if (!token) {
+      this.logger.info("[m365connector][graph] tryGraphRead(%s): getToken returned null (requiredScope=%s)", contentType, requiredScope);
+      return null;
+    }
+    this.logger.info("[m365connector][graph] tryGraphRead(%s): got token, proceeding with Graph API call for itemId=%s", contentType, String(itemId).substring(0, 30));
+
+    let retried401 = false;
+    let retried429 = false;
+    let retried5xx = false;
+
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      try {
+        const result = await operation(token);
+        this.recordGraphSuccess(contentType);
+        return result;
+      } catch (err) {
+        const status = Number(err?.status || 0);
+        this.logger.info("[m365connector][graph] tryGraphRead(%s): attempt %d failed, status=%d err=%s", contentType, attempt, status, err?.message || err);
+
+        if (status === 403) {
+          this.cacheDenied(contentType, itemId);
+          this.recordGraphFailure(contentType);
+          return null;
+        }
+
+        if (status === 404) {
+          this.recordGraphFailure(contentType);
+          return null;
+        }
+
+        if (status === 401 && !retried401) {
+          retried401 = true;
+          await this.graphTokenProvider.refresh();
+          token = await this.graphTokenProvider.getToken(requiredScope || undefined);
+          if (!token) {
+            break;
+          }
+          continue;
+        }
+
+        if (status === 429 && !retried429) {
+          retried429 = true;
+          const retrySeconds = Number.isFinite(err?.retryAfter) ? err.retryAfter : 2;
+          const backoffMs = Math.max(500, retrySeconds * 1000);
+          await sleep(backoffMs);
+          continue;
+        }
+
+        if (status >= 500 && status <= 599 && !retried5xx) {
+          retried5xx = true;
+          await sleep(1800 + Math.floor(Math.random() * 600));
+          continue;
+        }
+
+        break;
+      }
+    }
+
+    this.recordGraphFailure(contentType);
+    return null;
+  }
+
+  recordGraphSuccess(contentType) {
+    const state = this.circuitBreakers[contentType];
+    if (!state) {
+      return;
+    }
+    state.failures = [];
+    state.openUntil = 0;
+  }
+
+  recordGraphFailure(contentType) {
+    const state = this.circuitBreakers[contentType];
+    if (!state) {
+      return;
+    }
+
+    const now = nowMs();
+    state.failures = state.failures.filter((ts) => now - ts <= CIRCUIT_FAILURE_WINDOW_MS);
+    state.failures.push(now);
+
+    if (state.failures.length >= 3) {
+      state.openUntil = now + CIRCUIT_OPEN_MS;
+      state.failures = [];
+    }
+  }
+
+  isCircuitOpen(contentType) {
+    const state = this.circuitBreakers[contentType];
+    if (!state) {
+      return false;
+    }
+
+    if (!state.openUntil) {
+      return false;
+    }
+
+    if (state.openUntil <= nowMs()) {
+      state.openUntil = 0;
+      return false;
+    }
+
+    return true;
+  }
+
+  deniedKey(contentType, itemId) {
+    return `${contentType}:${itemId}`;
+  }
+
+  cacheDenied(contentType, itemId) {
+    if (!itemId) {
+      return;
+    }
+    const key = this.deniedKey(contentType, itemId);
+    if (this.deniedCache.has(key)) {
+      this.deniedCache.delete(key);
+    }
+    this.deniedCache.set(key, nowMs() + NEGATIVE_CACHE_MS);
+    evictOldestEntries(this.deniedCache, MAX_CACHE_ENTRIES);
+  }
+
+  isDeniedCached(contentType, itemId) {
+    if (!itemId) {
+      return false;
+    }
+    const key = this.deniedKey(contentType, itemId);
+    const expiresAt = this.deniedCache.get(key);
+    if (!expiresAt) {
+      return false;
+    }
+    if (expiresAt <= nowMs()) {
+      this.deniedCache.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  pruneCaches() {
+    const now = nowMs();
+
+    for (const [key, expiresAt] of this.deniedCache.entries()) {
+      if (!expiresAt || expiresAt <= now) {
+        this.deniedCache.delete(key);
+      }
+    }
+    evictOldestEntries(this.deniedCache, MAX_CACHE_ENTRIES);
+
+    for (const [key, entry] of this.translationCache.entries()) {
+      if (!entry?.expiresAt || entry.expiresAt <= now) {
+        this.translationCache.delete(key);
+      }
+    }
+    evictOldestEntries(this.translationCache, MAX_CACHE_ENTRIES);
+  }
+
+  /** @internal Exposed for testing only. */
+  _getCircuitBreakers() {
+    return this.circuitBreakers;
+  }
+
+  async fetchGraphJson(token, pathOrUrl, options = {}) {
+    const url = pathOrUrl.startsWith("http") ? pathOrUrl : `${GRAPH_BASE_URL}${pathOrUrl}`;
+    const headers = {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json",
+      ...(options.headers || {})
+    };
+
+    const response = await fetch(url, {
+      method: options.method || "GET",
+      headers,
+      body: options.body
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new GraphHttpError(
+        `Graph request failed (${response.status})`,
+        response.status,
+        body,
+        retryAfterSeconds(response.headers.get("retry-after"))
+      );
+    }
+
+    if (response.status === 204) {
+      return null;
+    }
+
+    return response.json();
+  }
+}
+
+export const _testable = {
+  htmlToText,
+  decodeXmlEntities,
+  extractTagValues,
+  getFileExtension,
+  isAllowedSharePointUrl,
+  base64UrlEncode,
+  retryAfterSeconds,
+  extractOutlookDeepLinkItemId,
+  evictOldestEntries,
+  decodeCodePointSafe,
+  pickContext,
+  GraphHttpError
+};