@chrischall/office-outlook-mcp 0.6.1 → 0.6.2

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Outlook / Microsoft 365 — mail, calendar, contacts and tasks via natural language",
-    "version": "0.6.1"
+    "version": "0.6.2"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Outlook (Microsoft 365)",
       "source": "./",
       "description": "MCP server for Outlook / Microsoft 365 — triage unread mail, reply, answer meeting invites and schedule meetings, plus folders, calendar, contacts and tasks, with confirmation before anything is sent",
-      "version": "0.6.1",
+      "version": "0.6.2",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "office-outlook-mcp",
   "displayName": "Outlook (Microsoft 365)",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Outlook / Microsoft 365 for Claude — triage unread mail, reply, answer meeting invites and schedule meetings, plus folders, calendar, contacts and tasks, with confirmation before anything is sent, using your signed-in browser session",
   "author": {
     "name": "Chris Hall",

package/dist/auth-fetchproxy.js

@@ -24,9 +24,19 @@
  * cannot drive. Capture is the only path, which is why a failed capture is a
  * hard error with actionable guidance rather than a fallback.
  */
-import { createBootstrapOpts, createFetchproxyTransport, } from '@chrischall/mcp-utils/fetchproxy';
+import { captureBearerHeader } from '@chrischall/mcp-utils/fetchproxy';
 import { readPortEnv, readTtlMsEnv } from '@chrischall/mcp-utils';
 import { PACKAGE_NAME, VERSION } from './version.js';
+/**
+ * `raceCaptures` settles the per-host attempts under ONE overall deadline:
+ * `Promise.any` alone is not enough, because the bridge serializes the two
+ * hosts behind its single connection, so the wait was the sum rather than the
+ * max — measured live at 14.4s for a 5s window and 36s for a 20s one. At the
+ * 30s default that lands past the 60s request timeout an MCP client uses by
+ * default. Re-exported (it is mcp-utils', lifted from here) for the test that
+ * pins that bound.
+ */
+export { raceCaptures, stripBearer } from '@chrischall/mcp-utils/fetchproxy';
 /**
  * The fetchproxy concentrator port.
  *
@@ -87,81 +97,6 @@ export const TRUST_DOMAINS = [...CAPTURE_HOSTS];
  * enough that an idle tab does not hang a tool call for minutes.
  */
 const CAPTURE_TIMEOUT_MS = readTtlMsEnv('OUTLOOK_CAPTURE_TIMEOUT', 30_000);
-/**
- * The transport-wide deadline, derived from the capture window rather than left
- * at the library default.
- *
- * `captureRequestHeader`'s own `timeoutMs` is silently capped by
- * `fetchTimeoutMs`: a window raised past the deadline fails early at the
- * deadline's number, which reads as a timeout nobody configured. Deriving it
- * means the two cannot disagree.
- */
-const BRIDGE_DEADLINE_MS = Math.max(CAPTURE_TIMEOUT_MS + 15_000, 30_000);
-/**
- * Shortest plausible token. Real ones are ~5 KB of JWT; this only guards
- * against an empty or echoed header, not against a wrong-audience token.
- */
-const MIN_TOKEN_LENGTH = 100;
-/**
- * Add `fetch` to the derived capability set.
- *
- * `createBootstrapOpts` infers capabilities from the bootstrap DECLARATIONS and
- * the field REPLACES the server's defaults rather than extending them, so a
- * declaration-only set can silently lose `fetch`.
- */
-function withFetch(opts) {
-    const derived = opts.capabilities ?? [];
-    return {
-        ...opts,
-        capabilities: derived.includes('fetch')
-            ? derived
-            : [...derived, 'fetch'],
-    };
-}
-/**
- * Settle a set of per-host capture attempts under ONE overall deadline.
- *
- * `Promise.any` alone is not enough. The two declared hosts are documented as
- * raced, but the bridge serializes them behind its single connection, so the
- * wait was the sum rather than the max — measured live at 14.4s for a 5s window
- * and 36s for a 20s one. At the 30s default that lands past the 60s request
- * timeout an MCP client uses by default, so the host gave up before this code
- * could report the real reason. The window is a promise about total wait, and
- * this is what keeps it.
- *
- * Exported for the test that pins that bound.
- */
-export async function raceCaptures(attempts, windowMs) {
-    // A rejection that loses the race must not surface as an unhandled rejection
-    // once the winner has already settled the caller.
-    for (const a of attempts)
-        a.catch(() => { });
-    let timer;
-    const expiry = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new Error(`timed out after ${Math.round(windowMs / 1000)}s waiting for the page to ` +
-            'make a request we could read')), windowMs);
-    });
-    try {
-        // `any` resolves on the first SUCCESS rather than the first settle, so the
-        // host the user is not on failing does not sink the one they are on.
-        return await Promise.race([
-            Promise.any(attempts).catch((e) => {
-                throw new Error(e instanceof AggregateError
-                    ? e.errors.map((x) => x.message).join('; ')
-                    : e.message);
-            }),
-            expiry,
-        ]);
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-/** Normalise a captured header to a bare token, dropping any `Bearer ` prefix. */
-export function stripBearer(raw) {
-    const m = /^\s*Bearer\s+(.+)$/i.exec(raw);
-    return (m ? m[1] : raw).trim();
-}
 /**
  * Capture an Outlook access token from the user's signed-in browser tab.
  *
@@ -171,54 +106,23 @@ export function stripBearer(raw) {
  * Returns the bare token (no `Bearer ` prefix).
  */
 export async function captureTokenViaFetchproxy() {
-    const transport = createFetchproxyTransport({
-        ...withFetch(createBootstrapOpts({
-            domains: [...TRUST_DOMAINS],
-            bootstrap: {
-                captureHeaders: [{ ...CAPTURE_DECL_CLOUD }, { ...CAPTURE_DECL_OFFICE }],
-            },
-        })),
+    // `captureBearerHeader` declares only `capture_request_header` beside the
+    // `fetch` base verb, derives the bridge deadline from the window (window +
+    // 15 s, never under 30 s) so a raised window is not cut off early, starts the
+    // transport (skipping `start()` makes the first verb throw "ensureConnected
+    // called before listen()", which reads like a pairing problem), rejects a
+    // header too short to be a token (real ones are ~5 KB of JWT), and closes
+    // the transport whatever happened.
+    return captureBearerHeader({
+        captures: [CAPTURE_DECL_CLOUD, CAPTURE_DECL_OFFICE],
+        domains: TRUST_DOMAINS,
+        windowMs: CAPTURE_TIMEOUT_MS,
         port: getWsPort(),
-        fetchTimeoutMs: BRIDGE_DEADLINE_MS,
         serverName: PACKAGE_NAME,
         version: VERSION,
+        what: 'an Outlook token',
+        guidance: 'Open a signed-in Outlook tab (outlook.cloud.microsoft or ' +
+            'outlook.office.com), leave it in the foreground for a moment so the ' +
+            'page makes a request, and retry.',
     });
-    try {
-        // `start()` loads the identity keypair. It does not bind the port or dial —
-        // that stays lazy until the first verb — but skipping it makes the first
-        // verb throw "ensureConnected called before listen()", which reads exactly
-        // like a pairing problem and is not one.
-        await transport.start();
-        const attempts = [CAPTURE_DECL_CLOUD, CAPTURE_DECL_OFFICE].map((decl) => transport.server
-            .captureRequestHeader({ ...decl, timeoutMs: CAPTURE_TIMEOUT_MS })
-            .then((raw) => {
-            if (typeof raw !== 'string') {
-                throw new Error(`${decl.host}: capture returned no header`);
-            }
-            const token = stripBearer(raw);
-            if (token.length < MIN_TOKEN_LENGTH) {
-                throw new Error(`${decl.host}: authorization header was present but too short to be a ` +
-                    `token (${token.length} chars)`);
-            }
-            return token;
-        }));
-        try {
-            return await raceCaptures(attempts, CAPTURE_TIMEOUT_MS);
-        }
-        catch (e) {
-            const detail = e.message;
-            throw new Error(`could not capture an Outlook token from the browser (${detail}). ` +
-                'Open a signed-in Outlook tab (outlook.cloud.microsoft or ' +
-                'outlook.office.com), leave it in the foreground for a moment so the ' +
-                'page makes a request, and retry.');
-        }
-    }
-    finally {
-        try {
-            await transport.close();
-        }
-        catch {
-            /* the token, or the original failure, is what matters */
-        }
-    }
 }

package/dist/bundle.js

@@ -35421,10 +35421,33 @@ function redactJsonCookie(quote) {
 function redactSecrets(text) {
   return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(GOOGLE_OAUTH_TOKEN_RE, "[REDACTED]").replace(HEADER_SECRET_RE, "$1[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(OAUTH_CODE_RE, "$1[REDACTED]").replace(FORM_PASSWORD_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_COOKIE_DQ_RE, redactJsonCookie('"')).replace(JSON_COOKIE_SQ_RE, redactJsonCookie("'")).replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_NUM_RE, "$1[REDACTED]").replace(JWT_RE, "[REDACTED]");
 }
-function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
+function redactValues(text, values, opts = {}) {
+  const placeholder = opts.placeholder ?? "[REDACTED]";
+  const minLength = Math.max(1, opts.minLength ?? 1);
+  const needles = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (typeof value !== "string" || value.length < minLength)
+      continue;
+    needles.add(value);
+    if (opts.jsonEscaped !== false) {
+      const escaped = JSON.stringify(value).slice(1, -1);
+      if (escaped !== value && escaped.length >= minLength)
+        needles.add(escaped);
+    }
+  }
+  let out = String(text ?? "");
+  for (const needle of [...needles].sort((a, b) => b.length - a.length)) {
+    if (out.includes(needle))
+      out = out.split(needle).join(placeholder);
+  }
+  return out;
+}
+function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX, opts = {}) {
   const str = text === null || text === void 0 ? "" : String(text);
   const cap = Math.max(ERROR_REDACTION_INPUT_MAX, max);
-  const redacted = redactSecrets(str.length > cap ? str.slice(0, cap) : str);
+  const capped = str.length > cap ? str.slice(0, cap) : str;
+  const scrubbed = opts.values !== void 0 ? redactValues(capped, opts.values, opts.placeholder !== void 0 ? { placeholder: opts.placeholder } : {}) : capped;
+  const redacted = redactSecrets(scrubbed);
   if (redacted.length <= max)
     return redacted;
   return `${redacted.slice(0, max)}\u2026 [truncated]`;
@@ -35573,6 +35596,16 @@ var init_zod = __esm({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/response/media.js
+var MEDIA_NOUN, MEDIA_QUALIFIER, MEDIA_KEY;
+var init_media = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/response/media.js"() {
+    MEDIA_NOUN = "(?:avatar|picture|photo|thumbnail|thumb|image|icon|banner|profile_pic(?:ture)?|logo)";
+    MEDIA_QUALIFIER = "(?:primary|secondary|main|default|cover|hero|profile|master|rendered|small|medium|large|full|original|tall)";
+    MEDIA_KEY = new RegExp(`^(?:(?:${MEDIA_QUALIFIER}|${MEDIA_NOUN})[_-]?)?${MEDIA_NOUN}s?(?:[_-]?(?:link|uri|url|src)s?)?$`, "i");
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/response/view.js
 function viewParam(honoured, opts = {}) {
   if (honoured.length < 2) {
@@ -35611,6 +35644,7 @@ var VIEWS, DEFAULT_VIEW, BLURB;
 var init_view = __esm({
   "node_modules/@chrischall/mcp-utils/dist/response/view.js"() {
     init_zod();
+    init_media();
     VIEWS = ["compact", "full", "raw"];
     DEFAULT_VIEW = "compact";
     BLURB = {
@@ -35621,16 +35655,6 @@ var init_view = __esm({
   }
 });
 
-// node_modules/@chrischall/mcp-utils/dist/response/media.js
-var MEDIA_NOUN, MEDIA_QUALIFIER, MEDIA_KEY;
-var init_media = __esm({
-  "node_modules/@chrischall/mcp-utils/dist/response/media.js"() {
-    MEDIA_NOUN = "(?:avatar|picture|photo|thumbnail|thumb|image|icon|banner|profile_pic(?:ture)?|logo)";
-    MEDIA_QUALIFIER = "(?:primary|secondary|main|default|cover|hero|profile|master|rendered|small|medium|large|full|original|tall)";
-    MEDIA_KEY = new RegExp(`^(?:(?:${MEDIA_QUALIFIER}|${MEDIA_NOUN})[_-]?)?${MEDIA_NOUN}s?(?:[_-]?(?:link|uri|url|src)s?)?$`, "i");
-  }
-});
-
 // node_modules/@chrischall/mcp-utils/dist/response/untrusted.js
 function isPlainObject3(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value))
@@ -36892,6 +36916,126 @@ var init_url_safety = __esm({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/http/transport-failure.js
+function codeOf(e) {
+  if (e === null || typeof e !== "object")
+    return void 0;
+  const code2 = e.code;
+  return typeof code2 === "string" && code2 !== "" ? code2 : void 0;
+}
+function causes(err) {
+  const out = [];
+  let at = err;
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && at !== void 0 && at !== null; depth++) {
+    out.push(at);
+    if (at instanceof AggregateError)
+      out.push(...at.errors);
+    at = at.cause;
+  }
+  return out;
+}
+function transportCauseCode(err) {
+  for (const e of causes(err)) {
+    const code2 = codeOf(e);
+    if (code2 !== void 0)
+      return code2;
+  }
+  return void 0;
+}
+function causeMessage(err) {
+  const chain = causes(err).slice(1);
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const e = chain[i];
+    if (e instanceof Error && e.message !== "")
+      return e.message;
+  }
+  return void 0;
+}
+function isFetchFailedError(err) {
+  return err instanceof TypeError && err.message === "fetch failed";
+}
+function proxyRefusalStatus(err) {
+  for (const e of causes(err)) {
+    if (codeOf(e) === "ERR_PROXY_TUNNEL") {
+      const m = /\b(\d{3})\b/.exec(e instanceof Error ? e.message.slice(0, 500) : "");
+      return m ? Number(m[1]) : "unknown";
+    }
+    if (e instanceof Error) {
+      const m = /^Proxy response \((\d{3})\) !== 200 when HTTP Tunneling/.exec(e.message);
+      if (m)
+        return Number(m[1]);
+    }
+  }
+  return void 0;
+}
+function classify(err, code2) {
+  const refused = proxyRefusalStatus(err);
+  if (refused !== void 0) {
+    return { cls: refused === 403 || refused === 407 || refused === "unknown" ? "egress" : "proxy", proxyStatus: refused };
+  }
+  if (code2 !== void 0 && DNS_CODES.has(code2))
+    return { cls: "dns" };
+  if (code2 !== void 0 && CERT_CODES.has(code2))
+    return { cls: "tls" };
+  if (code2 !== void 0 && CONNECT_CODES.has(code2))
+    return { cls: "connect" };
+  return { cls: "other" };
+}
+function describeTransportFailure(err, url2, service, opts = {}) {
+  if (!isFetchFailedError(err))
+    return void 0;
+  let host;
+  try {
+    host = new URL(url2).hostname;
+  } catch {
+    host = "(unknown host)";
+  }
+  const code2 = transportCauseCode(err);
+  const detail = [code2, causeMessage(err)].filter((s) => s !== void 0);
+  const why = detail.length > 0 ? ` (${[...new Set(detail)].join(": ")})` : "";
+  const { cls, proxyStatus } = classify(err, code2);
+  const ctx = { host, service, code: code2, ...proxyStatus !== void 0 ? { proxyStatus } : {} };
+  const hint = (opts.hints?.[cls] ?? DEFAULT_HINTS[cls])(host, ctx);
+  return new McpToolError(`Could not reach ${service} at ${host}${why}.`, { kind: "transport", hint, cause: err });
+}
+var MAX_CAUSE_DEPTH, DNS_CODES, CONNECT_CODES, CERT_CODES, DEFAULT_HINTS;
+var init_transport_failure = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/http/transport-failure.js"() {
+    init_errors3();
+    MAX_CAUSE_DEPTH = 5;
+    DNS_CODES = /* @__PURE__ */ new Set(["ENOTFOUND", "EAI_AGAIN", "EAI_FAIL", "EAI_NONAME"]);
+    CONNECT_CODES = /* @__PURE__ */ new Set([
+      "ECONNREFUSED",
+      "ECONNRESET",
+      "ETIMEDOUT",
+      "ENETUNREACH",
+      "EHOSTUNREACH",
+      "EPIPE",
+      "UND_ERR_CONNECT_TIMEOUT",
+      "UND_ERR_SOCKET",
+      "UND_ERR_HEADERS_TIMEOUT"
+    ]);
+    CERT_CODES = /* @__PURE__ */ new Set([
+      "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+      "UNABLE_TO_GET_ISSUER_CERT",
+      "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+      "SELF_SIGNED_CERT_IN_CHAIN",
+      "DEPTH_ZERO_SELF_SIGNED_CERT",
+      "CERT_HAS_EXPIRED",
+      "CERT_NOT_YET_VALID",
+      "ERR_TLS_CERT_ALTNAME_INVALID"
+    ]);
+    DEFAULT_HINTS = {
+      egress: (host) => `The outbound proxy this server runs behind refused the connection to ${host}: its egress policy does not allow that host. On a hosted (mcp-host) registration, the host must be on the registration's egress allow-list \u2014 the owner accepts the manifest's egress proposal (or adds the host) on the registration, then retries. Elsewhere, ask whoever runs the proxy to allow it.`,
+      proxy: (host, ctx) => `The outbound proxy this server runs behind could not open a connection to ${host} (it answered ${String(ctx.proxyStatus)}). Retry; if it persists, check the proxy can reach the host.`,
+      dns: (host) => `This machine could not resolve ${host}. Check DNS and VPN: a split-tunnel VPN that resolves some of a service's hosts but not others fails exactly like this. \`nslookup ${host}\` on the machine running this server tells you which.`,
+      tls: (host) => `Node did not trust the TLS certificate ${host} presented. On a corporate network this is usually TLS inspection: export your proxy's root CA as PEM and start this server with NODE_EXTRA_CA_CERTS=/path/to/ca.pem (Node does not read the system keychain). If the certificate is expired or not yet valid, also check the machine's clock.`,
+      connect: (host, ctx) => `The connection to ${host} was refused, reset or timed out before ${ctx.service} answered \u2014 usually a firewall, or a network that only lets traffic out through a proxy. Node's fetch ignores proxy settings unless told: start this server with HTTPS_PROXY=<your proxy URL> and NODE_USE_ENV_PROXY=1 (Node 22.21+ / 24.5+), or allow the host through the firewall.`,
+      other: (host) => `No response from ${host}. Check this machine can reach it (VPN, proxy, firewall); \`curl -sI https://${host}/\` from the same machine is a quick test.`
+    };
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/internal/retry-after.js
 function retryAfterToMs(header, now = Date.now()) {
   if (header == null)
@@ -36941,6 +37085,27 @@ function cancelBody(res) {
   } catch {
   }
 }
+function writeOutcomeStatus(err) {
+  const status = err.cause?.status;
+  return typeof status === "number" ? status : void 0;
+}
+function unknownOutcomeReason(err, opts = {}) {
+  if (err.timedOut)
+    return "it did not answer in time";
+  const status = writeOutcomeStatus(err);
+  if (status !== void 0)
+    return `it answered HTTP ${status} after ${opts.sent ?? "the request"} was sent`;
+  return "the connection dropped";
+}
+async function writeOrUnknown(run, onUnknown) {
+  try {
+    return { ok: true, value: await run() };
+  } catch (err) {
+    if (!(err instanceof WriteOutcomeUnknownError))
+      throw err;
+    return { ok: false, result: await onUnknown(err, unknownOutcomeReason(err)) };
+  }
+}
 function headerOf(headers, name) {
   if (headers === void 0)
     return void 0;
@@ -37209,7 +37374,7 @@ function createApiClient(opts) {
       const headers = {
         Accept: "application/json",
         ...withBody && contentType !== void 0 ? { "Content-Type": contentType } : {},
-        ...opts.baseHeaders,
+        ...typeof opts.baseHeaders === "function" ? opts.baseHeaders() : opts.baseHeaders,
         ...authHeader(token || void 0),
         ...opt.headers
       };
@@ -37323,24 +37488,62 @@ function createApiClient(opts) {
       throw err;
     }
   }
-  const fetchJson = (method, path, opt = {}) => guardWrite(method, opt, (dispatch) => fetchJsonOnce(method, path, opt, dispatch));
-  const fetchHtml = (method, path, opt = {}) => guardWrite(method, opt, (dispatch) => fetchHtmlOnce(method, path, opt, dispatch));
-  const fetchRaw = (method, path, opt = {}) => guardWrite(method, opt, (dispatch) => fetchRawOnce(method, path, opt, dispatch));
+  function withIdempotency(opt) {
+    const name = opts.idempotencyHeader;
+    if (name === void 0 || name === "")
+      return opt;
+    const lower2 = name.toLowerCase();
+    if (opt.headers && Object.keys(opt.headers).some((k) => k.toLowerCase() === lower2))
+      return opt;
+    const key = opt.idempotencyKey ?? globalThis.crypto.randomUUID();
+    return { ...opt, headers: { ...opt.headers, [name]: key } };
+  }
+  async function errorFor(res, text, method, path, retried) {
+    const edge = detectEdgeBlock({ body: text, headers: res.headers, status: res.status });
+    if (edge)
+      return new EdgeBlockedError(res.status, edge.vendor, { service, method, path });
+    if (opts.onErrorResponse) {
+      const decision = await opts.onErrorResponse({ status: res.status, method, path, headers: res.headers, body: text, retried });
+      if (decision instanceof Error)
+        return decision;
+      if (decision === "retry" && !retried)
+        return "retry";
+    }
+    return httpError(res, text, method, path, service);
+  }
+  const fetchJson = (method, path, opt = {}) => {
+    const o = withIdempotency(opt);
+    return guardWrite(method, o, (dispatch) => fetchJsonOnce(method, path, o, dispatch));
+  };
+  const fetchHtml = (method, path, opt = {}) => {
+    const o = withIdempotency(opt);
+    return guardWrite(method, o, (dispatch) => fetchHtmlOnce(method, path, o, dispatch));
+  };
+  const fetchRaw = (method, path, opt = {}) => {
+    const o = withIdempotency(opt);
+    return guardWrite(method, o, (dispatch) => fetchRawOnce(method, path, o, dispatch));
+  };
   async function fetchJsonOnce(method, path, opt, dispatch) {
     const maxBytes = capOf(opt);
-    const attempt = await send(method, path, opt, dispatch);
-    const res = attempt.res;
-    if (res.status === 401)
-      throw await unauthorizedOrEdge(attempt, method, path, maxBytes);
-    if (res.status === 429)
-      throw await rateLimitedError(attempt, method, path, maxBytes);
-    if (res.status === 204) {
-      discard(attempt);
-      return parseJsonBody("", { expect: opt.expect, service, method, path, status: 204 });
-    }
-    if (!res.ok) {
-      throw httpError(res, await readErrorText(attempt, maxBytes), method, path, service);
+    let attempt;
+    for (let retried = false; ; retried = true) {
+      attempt = await send(method, path, opt, dispatch);
+      const res2 = attempt.res;
+      if (res2.status === 401)
+        throw await unauthorizedOrEdge(attempt, method, path, maxBytes);
+      if (res2.status === 429)
+        throw await rateLimitedError(attempt, method, path, maxBytes);
+      if (res2.status === 204) {
+        discard(attempt);
+        return parseJsonBody("", { expect: opt.expect, service, method, path, status: 204 });
+      }
+      if (res2.ok)
+        break;
+      const failure2 = await errorFor(res2, await readErrorText(attempt, maxBytes), method, path, retried);
+      if (failure2 !== "retry")
+        throw failure2;
     }
+    const res = attempt.res;
     const text = await readText(attempt, maxBytes);
     return parseJsonBody(text, {
       expect: opt.expect,
@@ -37354,34 +37557,43 @@ function createApiClient(opts) {
   async function fetchHtmlOnce(method, path, opt, dispatch) {
     const maxBytes = capOf(opt);
     const headers = { Accept: "text/html,*/*", ...opt.headers };
-    const attempt = await send(method, path, { ...opt, headers }, dispatch);
-    const res = attempt.res;
-    if (res.status === 401)
-      throw await unauthorizedOrEdge(attempt, method, path, maxBytes);
-    if (res.status === 429)
-      throw await rateLimitedError(attempt, method, path, maxBytes);
-    if (!res.ok) {
-      throw httpError(res, await readErrorText(attempt, maxBytes), method, path, service);
+    for (let retried = false; ; retried = true) {
+      const attempt = await send(method, path, { ...opt, headers }, dispatch);
+      const res = attempt.res;
+      if (res.status === 401)
+        throw await unauthorizedOrEdge(attempt, method, path, maxBytes);
+      if (res.status === 429)
+        throw await rateLimitedError(attempt, method, path, maxBytes);
+      if (res.ok)
+        return readText(attempt, maxBytes);
+      const failure2 = await errorFor(res, await readErrorText(attempt, maxBytes), method, path, retried);
+      if (failure2 !== "retry")
+        throw failure2;
     }
-    return readText(attempt, maxBytes);
   }
   async function fetchRawOnce(method, path, opt, dispatch) {
     const maxBytes = capOf(opt);
     const headers = { Accept: "*/*", ...opt.headers };
-    const attempt = await send(method, path, { ...opt, headers }, dispatch);
-    const res = attempt.res;
-    if (res.status === 401)
-      throw await unauthorizedOrEdge(attempt, method, path, maxBytes);
-    if (res.status === 429)
-      throw await rateLimitedError(attempt, method, path, maxBytes);
-    if (!res.ok) {
+    let attempt;
+    for (let retried = false; ; retried = true) {
+      attempt = await send(method, path, { ...opt, headers }, dispatch);
+      const res2 = attempt.res;
+      if (res2.status === 401)
+        throw await unauthorizedOrEdge(attempt, method, path, maxBytes);
+      if (res2.status === 429)
+        throw await rateLimitedError(attempt, method, path, maxBytes);
+      if (res2.ok)
+        break;
       const text = await readText(attempt, maxBytes).catch((err) => {
         if (err instanceof RequestTimeoutError)
           throw err;
         return "";
       });
-      throw httpError(res, text, method, path, service);
+      const failure2 = await errorFor(res2, text, method, path, retried);
+      if (failure2 !== "retry")
+        throw failure2;
     }
+    const res = attempt.res;
     const bytes = await readBytes(attempt, maxBytes);
     return {
       status: res.status,
@@ -37462,6 +37674,7 @@ var init_http = __esm({
     init_net_atoms();
     init_fetch_bounded();
     init_url_safety();
+    init_transport_failure();
     init_body_limit();
     init_net_atoms();
     init_url_safety();
@@ -37709,7 +37922,7 @@ var init_version = __esm({
   "src/version.ts"() {
     "use strict";
     PACKAGE_NAME = "office-outlook-mcp";
-    VERSION = "0.6.1";
+    VERSION = "0.6.2";
   }
 });
 
@@ -48055,6 +48268,71 @@ function createBootstrapOpts(args) {
     ...nonEmpty(b.domSelectors) ? { domSelectors: b.domSelectors } : {}
   };
 }
+function stripBearer(raw) {
+  const m = /^\s*Bearer\s+(.+)$/i.exec(raw);
+  return (m?.[1] ?? raw).trim();
+}
+async function raceCaptures(attempts, windowMs) {
+  for (const a of attempts)
+    a.catch(() => {
+    });
+  let timer;
+  const expiry = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`timed out after ${Math.round(windowMs / 1e3)}s waiting for the page to make a request we could read`)), windowMs);
+  });
+  try {
+    return await Promise.race([
+      Promise.any(attempts).catch((e) => {
+        throw new Error(e instanceof AggregateError ? e.errors.map((x) => messageOf(x)).join("; ") : messageOf(e));
+      }),
+      expiry
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function captureBearerHeader(opts) {
+  if (opts.captures.length === 0)
+    throw new Error("captureBearerHeader: at least one capture declaration is required.");
+  const minLength = opts.minLength ?? 100;
+  const normalise = opts.normalise ?? stripBearer;
+  const domains = opts.domains ?? [...new Set(opts.captures.map((c) => c.host))];
+  const build2 = opts.createTransport ?? ((o) => createFetchproxyTransport(o));
+  const transport = build2({
+    ...opts.transportOptions,
+    ...createBootstrapOpts({ domains: [...domains], bootstrap: { captureHeaders: opts.captures.map((c) => ({ ...c })) } }),
+    ...opts.port !== void 0 ? { port: opts.port } : {},
+    // Both: the explicit deadline for every bridge version, and the declared
+    // window so the transport's own derivation agrees with it.
+    fetchTimeoutMs: deadlineForCaptureWindow(void 0, opts.windowMs) ?? SERVER_DEFAULT_FETCH_TIMEOUT_MS,
+    captureWindowMs: opts.windowMs,
+    serverName: opts.serverName,
+    version: opts.version
+  });
+  const one = async (decl) => {
+    const raw = await transport.server.captureRequestHeader({ ...decl, timeoutMs: opts.windowMs });
+    if (typeof raw !== "string")
+      throw new Error(`${decl.host}: capture returned no header`);
+    const token = normalise(raw);
+    if (token.length < minLength) {
+      throw new Error(`${decl.host}: ${decl.headerName} header was present but too short to be a token (${token.length} chars)`);
+    }
+    return token;
+  };
+  try {
+    await transport.start();
+    try {
+      return opts.captures.length === 1 ? await one(opts.captures[0]) : await raceCaptures(opts.captures.map(one), opts.windowMs);
+    } catch (e) {
+      throw new Error(`could not capture ${opts.what} from the browser (${messageOf(e)}). ${opts.guidance}`);
+    }
+  } finally {
+    try {
+      await transport.close();
+    } catch {
+    }
+  }
+}
 var PLACEHOLDER_RE2, SERVER_DEFAULT_FETCH_TIMEOUT_MS, CAPTURE_DEADLINE_MARGIN_MS;
 var init_fetchproxy = __esm({
   "node_modules/@chrischall/mcp-utils/dist/fetchproxy/index.js"() {
@@ -48083,97 +48361,26 @@ __export(auth_fetchproxy_exports, {
 function getWsPort() {
   return readPortEnv("OUTLOOK_WS_PORT", DEFAULT_WS_PORT);
 }
-function withFetch(opts) {
-  const derived2 = opts.capabilities ?? [];
-  return {
-    ...opts,
-    capabilities: derived2.includes("fetch") ? derived2 : [...derived2, "fetch"]
-  };
-}
-async function raceCaptures(attempts, windowMs) {
-  for (const a of attempts) a.catch(() => {
-  });
-  let timer;
-  const expiry = new Promise((_, reject) => {
-    timer = setTimeout(
-      () => reject(
-        new Error(
-          `timed out after ${Math.round(windowMs / 1e3)}s waiting for the page to make a request we could read`
-        )
-      ),
-      windowMs
-    );
-  });
-  try {
-    return await Promise.race([
-      Promise.any(attempts).catch((e) => {
-        throw new Error(
-          e instanceof AggregateError ? e.errors.map((x) => x.message).join("; ") : e.message
-        );
-      }),
-      expiry
-    ]);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-function stripBearer(raw) {
-  const m = /^\s*Bearer\s+(.+)$/i.exec(raw);
-  return (m ? m[1] : raw).trim();
-}
 async function captureTokenViaFetchproxy() {
-  const transport = createFetchproxyTransport({
-    ...withFetch(
-      createBootstrapOpts({
-        domains: [...TRUST_DOMAINS],
-        bootstrap: {
-          captureHeaders: [{ ...CAPTURE_DECL_CLOUD }, { ...CAPTURE_DECL_OFFICE }]
-        }
-      })
-    ),
+  return captureBearerHeader({
+    captures: [CAPTURE_DECL_CLOUD, CAPTURE_DECL_OFFICE],
+    domains: TRUST_DOMAINS,
+    windowMs: CAPTURE_TIMEOUT_MS,
     port: getWsPort(),
-    fetchTimeoutMs: BRIDGE_DEADLINE_MS,
     serverName: PACKAGE_NAME,
-    version: VERSION
+    version: VERSION,
+    what: "an Outlook token",
+    guidance: "Open a signed-in Outlook tab (outlook.cloud.microsoft or outlook.office.com), leave it in the foreground for a moment so the page makes a request, and retry."
   });
-  try {
-    await transport.start();
-    const attempts = [CAPTURE_DECL_CLOUD, CAPTURE_DECL_OFFICE].map(
-      (decl) => transport.server.captureRequestHeader({ ...decl, timeoutMs: CAPTURE_TIMEOUT_MS }).then((raw) => {
-        if (typeof raw !== "string") {
-          throw new Error(`${decl.host}: capture returned no header`);
-        }
-        const token = stripBearer(raw);
-        if (token.length < MIN_TOKEN_LENGTH) {
-          throw new Error(
-            `${decl.host}: authorization header was present but too short to be a token (${token.length} chars)`
-          );
-        }
-        return token;
-      })
-    );
-    try {
-      return await raceCaptures(attempts, CAPTURE_TIMEOUT_MS);
-    } catch (e) {
-      const detail = e.message;
-      throw new Error(
-        `could not capture an Outlook token from the browser (${detail}). Open a signed-in Outlook tab (outlook.cloud.microsoft or outlook.office.com), leave it in the foreground for a moment so the page makes a request, and retry.`
-      );
-    }
-  } finally {
-    try {
-      await transport.close();
-    } catch {
-    }
-  }
 }
-var DEFAULT_WS_PORT, CAPTURE_DECL_CLOUD, CAPTURE_DECL_OFFICE, CAPTURE_HOSTS, TRUST_DOMAINS, CAPTURE_TIMEOUT_MS, BRIDGE_DEADLINE_MS, MIN_TOKEN_LENGTH;
+var DEFAULT_WS_PORT, CAPTURE_DECL_CLOUD, CAPTURE_DECL_OFFICE, CAPTURE_HOSTS, TRUST_DOMAINS, CAPTURE_TIMEOUT_MS;
 var init_auth_fetchproxy = __esm({
   "src/auth-fetchproxy.ts"() {
     "use strict";
     init_fetchproxy();
     init_dist2();
     init_version();
+    init_fetchproxy();
     DEFAULT_WS_PORT = 37149;
     CAPTURE_DECL_CLOUD = {
       host: "outlook.cloud.microsoft",
@@ -48188,8 +48395,6 @@ var init_auth_fetchproxy = __esm({
     CAPTURE_HOSTS = [CAPTURE_DECL_CLOUD.host, CAPTURE_DECL_OFFICE.host];
     TRUST_DOMAINS = [...CAPTURE_HOSTS];
     CAPTURE_TIMEOUT_MS = readTtlMsEnv("OUTLOOK_CAPTURE_TIMEOUT", 3e4);
-    BRIDGE_DEADLINE_MS = Math.max(CAPTURE_TIMEOUT_MS + 15e3, 3e4);
-    MIN_TOKEN_LENGTH = 100;
   }
 });
 
@@ -48771,6 +48976,46 @@ var TokenManager = class {
     return res;
   }
 };
+var RECAPTURE_SENTINEL = "fetchproxy:recapture";
+var UNKNOWN_CAPTURED_TOKEN_TTL_MS = 10 * 60 * 1e3;
+function capturedBearerTokens(accessToken, opts = {}) {
+  const now = opts.now ?? Date.now;
+  let expiresAt;
+  try {
+    expiresAt = decodeJwtExp(accessToken) * 1e3;
+  } catch {
+    expiresAt = now() + (opts.unknownTtlMs ?? UNKNOWN_CAPTURED_TOKEN_TTL_MS);
+  }
+  return { accessToken, refreshToken: RECAPTURE_SENTINEL, expiresAt };
+}
+function createCapturedTokenManager(opts) {
+  const { direct } = opts;
+  const wrap = (token) => capturedBearerTokens(token, {
+    ...opts.unknownTtlMs !== void 0 ? { unknownTtlMs: opts.unknownTtlMs } : {},
+    ...opts.now !== void 0 ? { now: opts.now } : {}
+  });
+  const persistence = direct === void 0 ? opts.persistence ?? void 0 : void 0;
+  return new TokenManager({
+    initial: async () => wrap(direct ?? await opts.capture()),
+    refresh: async () => {
+      if (direct !== void 0) {
+        throw opts.onDirectRejected ? opts.onDirectRejected() : new McpToolError("The directly supplied access token was rejected (401).", {
+          status: 401,
+          kind: "credential_rejected",
+          hint: "A directly supplied token cannot be refreshed automatically. Replace it with a current one, or unset it to capture from a signed-in browser tab instead."
+        });
+      }
+      return wrap(await opts.capture());
+    },
+    ...persistence !== void 0 ? { persistence } : {},
+    // Never fatal: the token is in hand and re-capturable.
+    onPersistError: (err) => {
+      opts.onPersistError?.(err);
+    },
+    ...opts.skewMs !== void 0 ? { skewMs: opts.skewMs } : {},
+    ...opts.now !== void 0 ? { now: opts.now } : {}
+  });
+}
 
 // src/token-cache.ts
 init_dist2();
@@ -48782,11 +49027,6 @@ function tokenCachePath(env = process.env) {
     fileName: "token.json"
   });
 }
-function isToken(raw) {
-  if (raw === null || typeof raw !== "object") return false;
-  const t = raw;
-  return typeof t.accessToken === "string" && t.accessToken !== "" && typeof t.expiresAt === "number" && (t.refreshToken === void 0 || typeof t.refreshToken === "string");
-}
 function bindingFor(env) {
   if (readEnvVar("OUTLOOK_ACCESS_TOKEN", { env }) !== void 0) return null;
   if (parseBoolEnv("OUTLOOK_DISABLE_FETCHPROXY", { env })) return null;
@@ -48799,7 +49039,7 @@ function createTokenCache(env = process.env) {
   return createFileStatePersistence({
     filePath: tokenCachePath(env),
     boundTo,
-    validate: (raw) => isToken(raw) ? raw : null
+    validate: (raw) => isBearerTokens(raw) ? raw : null
   });
 }
 function reportCacheWriteFailure(err) {
@@ -48815,16 +49055,9 @@ async function captureTokenLazily() {
   return mod.captureTokenViaFetchproxy();
 }
 var DEFAULT_API_BASE = "https://outlook.office.com/api/v2.0";
-var UNKNOWN_TOKEN_TTL_MS = 10 * 60 * 1e3;
-var RECAPTURE_SENTINEL = "fetchproxy:recapture";
-function toBearerTokens(accessToken) {
-  let expiresAt;
-  try {
-    expiresAt = decodeJwtExp(accessToken) * 1e3;
-  } catch {
-    expiresAt = Date.now() + UNKNOWN_TOKEN_TTL_MS;
-  }
-  return { accessToken, refreshToken: RECAPTURE_SENTINEL, expiresAt };
+function urlOf(input2) {
+  if (typeof input2 === "string") return input2;
+  return input2 instanceof URL ? input2.href : input2.url;
 }
 function isCredentialFailure(e) {
   const kind = errorKindOf(e);
@@ -48849,7 +49082,14 @@ var OutlookClient = class {
   constructor(opts = {}) {
     this.#env = opts.env ?? process.env;
     this.#capture = opts.captureToken ?? captureTokenLazily;
-    this.#fetchImpl = opts.fetchImpl ?? ((input2, init) => fetch(input2, init));
+    const fetchImpl = opts.fetchImpl ?? ((input2, init) => fetch(input2, init));
+    this.#fetchImpl = async (input2, init) => {
+      try {
+        return await fetchImpl(input2, init);
+      } catch (e) {
+        throw describeTransportFailure(e, urlOf(input2), "Outlook") ?? e;
+      }
+    };
     this.#baseUrl = readEnvVar("OUTLOOK_API_BASE", { env: this.#env }) ?? DEFAULT_API_BASE;
     const direct = readEnvVar("OUTLOOK_ACCESS_TOKEN", { env: this.#env });
     const bridgeOff = parseBoolEnv("OUTLOOK_DISABLE_FETCHPROXY", { env: this.#env });
@@ -48872,51 +49112,17 @@ var OutlookClient = class {
     if (this.#configError) throw this.#configError;
   }
   #tokenManager() {
-    if (this.#tokens) return this.#tokens;
     const direct = readEnvVar("OUTLOOK_ACCESS_TOKEN", { env: this.#env });
-    const persistence = direct === void 0 ? createTokenCache(this.#env) : null;
-    const mint = async () => toBearerTokens(direct ?? await this.#capture());
-    this.#tokens = new TokenManager({
-      initial: mint,
-      // There is no refresh grant — re-capture instead. The sentinel argument
-      // is ignored by design.
-      //
-      // But a token supplied as OUTLOOK_ACCESS_TOKEN must NOT be "refreshed" by
-      // reaching for the browser: that silently swaps the credential the
-      // operator chose for whichever account a tab happens to be signed into,
-      // and on a machine with no bridge it just hangs for the capture window on
-      // every 401. Say what is wrong instead.
-      refresh: async () => {
-        if (direct !== void 0) {
-          throw new McpToolError("OUTLOOK_ACCESS_TOKEN was rejected by Outlook.", {
-            hint: "A directly-supplied token cannot be refreshed automatically. Replace OUTLOOK_ACCESS_TOKEN with a current one, or unset it to capture from a signed-in Outlook browser tab instead.",
-            status: 401,
-            kind: "credential_rejected"
-          });
-        }
-        return toBearerTokens(await this.#capture());
-      },
-      // A failed cache write must not fail the call that triggered it: the
-      // token is in hand and re-capturable, so a read-only data dir should cost
-      // the next cold start a capture, not this request.
-      ...persistence ? {
-        persistence: {
-          load: () => persistence.load(),
-          save: (t) => {
-            try {
-              persistence.save(t);
-            } catch (e) {
-              reportCacheWriteFailure(e);
-            }
-          },
-          clear: () => {
-            try {
-              persistence.clear();
-            } catch {
-            }
-          }
-        }
-      } : {}
+    this.#tokens ??= createCapturedTokenManager({
+      capture: () => this.#capture(),
+      direct,
+      onDirectRejected: () => new McpToolError("OUTLOOK_ACCESS_TOKEN was rejected by Outlook.", {
+        hint: "A directly-supplied token cannot be refreshed automatically. Replace OUTLOOK_ACCESS_TOKEN with a current one, or unset it to capture from a signed-in Outlook browser tab instead.",
+        status: 401,
+        kind: "credential_rejected"
+      }),
+      persistence: direct === void 0 ? createTokenCache(this.#env) : null,
+      onPersistError: reportCacheWriteFailure
     });
     return this.#tokens;
   }
@@ -50098,19 +50304,14 @@ function dateTimeTimeZone2(value, zone) {
   return { DateTime: value, TimeZone: zone };
 }
 var TIMEOUT_SENTENCE = 'If Outlook does not answer in time (or the connection drops) the result has status "unknown": the write may well have gone through, so check before retrying \u2014 never resend blindly.';
-async function writeOrUnknown(run, checkWhere) {
-  try {
-    return { ok: true, value: await run() };
-  } catch (e) {
-    if (!(e instanceof WriteOutcomeUnknownError)) throw e;
-    return {
-      ok: false,
-      result: minifiedResult({
-        status: "unknown",
-        warning: `Outlook did not confirm this write (${e.timedOut ? "it did not answer in time" : "the connection dropped"}), so it may already have happened. Check ${checkWhere} before retrying; do not resend blindly.`
-      })
-    };
-  }
+function writeOrUnknown2(run, checkWhere) {
+  return writeOrUnknown(
+    run,
+    (e) => minifiedResult({
+      status: "unknown",
+      warning: `Outlook did not confirm this write (${unknownOutcomeReason(e)}), so it may already have happened. Check ${checkWhere} before retrying; do not resend blindly.`
+    })
+  );
 }
 var INVITE_EVENT_SELECT = "Id,Subject,IsOrganizer,IsCancelled,Start,End,Organizer,ResponseStatus";
 var DELETE_EVENT_SELECT = "Id,Subject,IsOrganizer,IsCancelled,ResponseStatus,Type,SeriesMasterId,Start,End,Organizer,Attendees";
@@ -50218,7 +50419,7 @@ function registerWriteTools(server, client2) {
         confirmToken
       });
       if (gate) return gate;
-      const sent = await writeOrUnknown(() => client2.write("POST", "/me/sendmail", payload), "Sent Items");
+      const sent = await writeOrUnknown2(() => client2.write("POST", "/me/sendmail", payload), "Sent Items");
       if (!sent.ok) return sent.result;
       return minifiedResult({ sent: true, subject, recipients: recipients || null });
     }
@@ -50244,7 +50445,7 @@ function registerWriteTools(server, client2) {
         ToRecipients: toRecipients(to),
         ...cc?.length ? { CcRecipients: toRecipients(cc) } : {}
       };
-      const create = await writeOrUnknown(
+      const create = await writeOrUnknown2(
         () => client2.write("POST", "/me/messages", payload),
         "Drafts"
       );
@@ -50440,7 +50641,7 @@ function registerWriteTools(server, client2) {
         confirmToken
       });
       if (gate) return gate;
-      const write = await writeOrUnknown(
+      const write = await writeOrUnknown2(
         () => client2.write("POST", "/me/events", payload),
         "the calendar (outlook_list_events)"
       );
@@ -50661,7 +50862,7 @@ function registerWriteTools(server, client2) {
         });
         if (gate) return gate;
       }
-      const write = await writeOrUnknown(
+      const write = await writeOrUnknown2(
         () => client2.write("POST", path, payload),
         "the event's response (outlook_get_event)"
       );
@@ -50744,7 +50945,7 @@ function registerWriteTools(server, client2) {
         });
         if (gate) return gate;
       }
-      const write = await writeOrUnknown(
+      const write = await writeOrUnknown2(
         () => client2.write("DELETE", path),
         "the calendar (outlook_get_event)"
       );
@@ -50797,7 +50998,7 @@ function registerWriteTools(server, client2) {
       const base = `/me/messages/${encodeURIComponent(messageId)}`;
       const forwardTo = mode === "forward" ? { ToRecipients: toRecipients(to) } : {};
       if (draftOnly === true) {
-        const create = await writeOrUnknown(
+        const create = await writeOrUnknown2(
           () => client2.write(
             "POST",
             `${base}/${draft}`,
@@ -50864,7 +51065,7 @@ function registerWriteTools(server, client2) {
         confirmToken
       });
       if (gate) return gate;
-      const sent = await writeOrUnknown(() => client2.write("POST", path, payload), "Sent Items");
+      const sent = await writeOrUnknown2(() => client2.write("POST", path, payload), "Sent Items");
       if (!sent.ok) return sent.result;
       return mailboxUntrusted({
         sent: true,

package/dist/client.js

@@ -6,8 +6,8 @@
  * held, every request is a plain Node `fetch` — the bridge is never on the hot
  * path.
  */
-import { createApiClient, decodeJwtExp, errorKindOf, errorStatusOf, McpToolError, parseBoolEnv, readEnvVar, } from '@chrischall/mcp-utils';
-import { TokenManager } from '@chrischall/mcp-utils/session';
+import { createApiClient, describeTransportFailure, errorKindOf, errorStatusOf, McpToolError, parseBoolEnv, readEnvVar, } from '@chrischall/mcp-utils';
+import { createCapturedTokenManager } from '@chrischall/mcp-utils/session';
 import { createTokenCache, reportCacheWriteFailure } from './token-cache.js';
 /**
  * Load the bridge bootstrap lazily.
@@ -34,35 +34,11 @@ async function captureTokenLazily() {
  * is the host that answers. Verified live 2026-09-20.
  */
 export const DEFAULT_API_BASE = 'https://outlook.office.com/api/v2.0';
-/**
- * Fallback lifetime for a token whose `exp` we cannot read.
- *
- * Real Outlook tokens are JWTs carrying `exp` (~25h out), so this is only
- * reached for a hand-supplied opaque `OUTLOOK_ACCESS_TOKEN`. Deliberately
- * short: being wrong in this direction costs one extra 401-and-replay, while
- * being wrong the other way makes every call fail until a restart.
- */
-const UNKNOWN_TOKEN_TTL_MS = 10 * 60 * 1000;
-/**
- * Sentinel standing in for a refresh token this flow does not have.
- *
- * Outlook Web's token comes from MSAL's hidden-iframe flow; there is no refresh
- * grant we can drive. "Refreshing" therefore means capturing a new one. The
- * sentinel exists because `TokenManager` only calls `refresh` when a refresh
- * token is present, and without it an expired token would have no path back
- * short of restarting the process.
- */
-const RECAPTURE_SENTINEL = 'fetchproxy:recapture';
-function toBearerTokens(accessToken) {
-    let expiresAt;
-    try {
-        // decodeJwtExp returns seconds; a non-JWT throws.
-        expiresAt = decodeJwtExp(accessToken) * 1000;
-    }
-    catch {
-        expiresAt = Date.now() + UNKNOWN_TOKEN_TTL_MS;
-    }
-    return { accessToken, refreshToken: RECAPTURE_SENTINEL, expiresAt };
+/** The URL a `fetch` was called with, for naming its host in a transport failure. */
+function urlOf(input) {
+    if (typeof input === 'string')
+        return input;
+    return input instanceof URL ? input.href : input.url;
 }
 /**
  * Whether `e` is about the credential rather than the request: no token
@@ -97,7 +73,20 @@ export class OutlookClient {
         // and calling it as `this.#fetchImpl(...)` binds `this` to the client, and
         // older undici (Node 18-20, which several MCP hosts still bundle) throws
         // `Illegal invocation` for any receiver that is not `globalThis`.
-        this.#fetchImpl = opts.fetchImpl ?? ((input, init) => fetch(input, init));
+        const fetchImpl = opts.fetchImpl ?? ((input, init) => fetch(input, init));
+        // undici reports every transport failure (DNS, refused/reset connection,
+        // untrusted TLS, a proxy refusing the tunnel) as a bare `TypeError('fetch
+        // failed')`; name the host, the cause code and what to check instead. The
+        // client still marks it a transport failure, so a sent write whose
+        // connection drops stays outcome-unknown.
+        this.#fetchImpl = async (input, init) => {
+            try {
+                return await fetchImpl(input, init);
+            }
+            catch (e) {
+                throw describeTransportFailure(e, urlOf(input), 'Outlook') ?? e;
+            }
+        };
         this.#baseUrl = readEnvVar('OUTLOOK_API_BASE', { env: this.#env }) ?? DEFAULT_API_BASE;
         const direct = readEnvVar('OUTLOOK_ACCESS_TOKEN', { env: this.#env });
         const bridgeOff = parseBoolEnv('OUTLOOK_DISABLE_FETCHPROXY', { env: this.#env });
@@ -119,59 +108,31 @@ export class OutlookClient {
             throw this.#configError;
     }
     #tokenManager() {
-        if (this.#tokens)
-            return this.#tokens;
         const direct = readEnvVar('OUTLOOK_ACCESS_TOKEN', { env: this.#env });
-        const persistence = direct === undefined ? createTokenCache(this.#env) : null;
-        const mint = async () => toBearerTokens(direct ?? (await this.#capture()));
-        this.#tokens = new TokenManager({
-            initial: mint,
-            // There is no refresh grant — re-capture instead. The sentinel argument
-            // is ignored by design.
-            //
-            // But a token supplied as OUTLOOK_ACCESS_TOKEN must NOT be "refreshed" by
-            // reaching for the browser: that silently swaps the credential the
-            // operator chose for whichever account a tab happens to be signed into,
-            // and on a machine with no bridge it just hangs for the capture window on
-            // every 401. Say what is wrong instead.
-            refresh: async () => {
-                if (direct !== undefined) {
-                    throw new McpToolError('OUTLOOK_ACCESS_TOKEN was rejected by Outlook.', {
-                        hint: 'A directly-supplied token cannot be refreshed automatically. Replace ' +
-                            'OUTLOOK_ACCESS_TOKEN with a current one, or unset it to capture from a ' +
-                            'signed-in Outlook browser tab instead.',
-                        status: 401,
-                        kind: 'credential_rejected',
-                    });
-                }
-                return toBearerTokens(await this.#capture());
-            },
-            // A failed cache write must not fail the call that triggered it: the
-            // token is in hand and re-capturable, so a read-only data dir should cost
-            // the next cold start a capture, not this request.
-            ...(persistence
-                ? {
-                    persistence: {
-                        load: () => persistence.load(),
-                        save: (t) => {
-                            try {
-                                persistence.save(t);
-                            }
-                            catch (e) {
-                                reportCacheWriteFailure(e);
-                            }
-                        },
-                        clear: () => {
-                            try {
-                                persistence.clear();
-                            }
-                            catch {
-                                /* nothing useful to do; the next capture overwrites it */
-                            }
-                        },
-                    },
-                }
-                : {}),
+        // Captures on first use (or loads a still-valid cached capture); there is
+        // no refresh grant, so a 401 or an expiring token re-captures instead.
+        //
+        // But a token supplied as OUTLOOK_ACCESS_TOKEN is never cached and never
+        // "refreshed" by reaching for the browser: that silently swaps the
+        // credential the operator chose for whichever account a tab happens to be
+        // signed into, and on a machine with no bridge it just hangs for the
+        // capture window on every 401. Say what is wrong instead.
+        //
+        // A failed cache write must not fail the call that triggered it: the
+        // token is in hand and re-capturable, so a read-only data dir should cost
+        // the next cold start a capture, not this request.
+        this.#tokens ??= createCapturedTokenManager({
+            capture: () => this.#capture(),
+            direct,
+            onDirectRejected: () => new McpToolError('OUTLOOK_ACCESS_TOKEN was rejected by Outlook.', {
+                hint: 'A directly-supplied token cannot be refreshed automatically. Replace ' +
+                    'OUTLOOK_ACCESS_TOKEN with a current one, or unset it to capture from a ' +
+                    'signed-in Outlook browser tab instead.',
+                status: 401,
+                kind: 'credential_rejected',
+            }),
+            persistence: direct === undefined ? createTokenCache(this.#env) : null,
+            onPersistError: reportCacheWriteFailure,
         });
         return this.#tokens;
     }

package/dist/token-cache.js

@@ -1,4 +1,4 @@
-import { createFileStatePersistence, resolveStateFile, } from '@chrischall/mcp-utils/session';
+import { createFileStatePersistence, isBearerTokens, resolveStateFile, } from '@chrischall/mcp-utils/session';
 import { readEnvVar, parseBoolEnv } from '@chrischall/mcp-utils';
 /**
  * Where the captured Outlook access token is cached between runs.
@@ -15,15 +15,6 @@ export function tokenCachePath(env = process.env) {
         fileName: 'token.json',
     });
 }
-function isToken(raw) {
-    if (raw === null || typeof raw !== 'object')
-        return false;
-    const t = raw;
-    return (typeof t.accessToken === 'string' &&
-        t.accessToken !== '' &&
-        typeof t.expiresAt === 'number' &&
-        (t.refreshToken === undefined || typeof t.refreshToken === 'string'));
-}
 /**
  * What a cached token is bound to, or `null` when there is nothing worth
  * caching.
@@ -51,7 +42,7 @@ export function createTokenCache(env = process.env) {
     return createFileStatePersistence({
         filePath: tokenCachePath(env),
         boundTo,
-        validate: (raw) => (isToken(raw) ? raw : null),
+        validate: (raw) => (isBearerTokens(raw) ? raw : null),
     });
 }
 /**

package/dist/tools/writes.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { CONFIRM_FLOW_SENTENCE, CONFIRM_INJECTION_RULE, confirmTokenParam, confirmWrite, errorKindOf, errorStatusOf, mapWithConcurrency, McpToolError, minifiedResult, WriteOutcomeUnknownError, } from '@chrischall/mcp-utils';
+import { CONFIRM_FLOW_SENTENCE, CONFIRM_INJECTION_RULE, confirmTokenParam, confirmWrite, errorKindOf, errorStatusOf, mapWithConcurrency, McpToolError, minifiedResult, unknownOutcomeReason, writeOrUnknown as runWriteOrUnknown, WriteOutcomeUnknownError, } from '@chrischall/mcp-utils';
 import { isCredentialFailure } from '../client.js';
 import { mailboxTimeZone } from '../timezone.js';
 import { cappedRecipients, MAX_RECIPIENTS } from '../view.js';
@@ -80,21 +80,11 @@ const TIMEOUT_SENTENCE = 'If Outlook does not answer in time (or the connection
  * send a second identical email. Any other failure is a real failure and
  * still throws.
  */
-async function writeOrUnknown(run, checkWhere) {
-    try {
-        return { ok: true, value: await run() };
-    }
-    catch (e) {
-        if (!(e instanceof WriteOutcomeUnknownError))
-            throw e;
-        return {
-            ok: false,
-            result: minifiedResult({
-                status: 'unknown',
-                warning: `Outlook did not confirm this write (${e.timedOut ? 'it did not answer in time' : 'the connection dropped'}), so it may already have happened. Check ${checkWhere} before retrying; do not resend blindly.`,
-            }),
-        };
-    }
+function writeOrUnknown(run, checkWhere) {
+    return runWriteOrUnknown(run, (e) => minifiedResult({
+        status: 'unknown',
+        warning: `Outlook did not confirm this write (${unknownOutcomeReason(e)}), so it may already have happened. Check ${checkWhere} before retrying; do not resend blindly.`,
+    }));
 }
 const INVITE_EVENT_SELECT = 'Id,Subject,IsOrganizer,IsCancelled,Start,End,Organizer,ResponseStatus';
 const DELETE_EVENT_SELECT = 'Id,Subject,IsOrganizer,IsCancelled,ResponseStatus,Type,SeriesMasterId,Start,End,Organizer,Attendees';

package/dist/version.js

@@ -10,4 +10,4 @@
  * line below and nowhere else — not even in prose.
  */
 export const PACKAGE_NAME = 'office-outlook-mcp';
-export const VERSION = '0.6.1'; // x-release-please-version
+export const VERSION = '0.6.2'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/office-outlook-mcp",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "mcpName": "io.github.chrischall/office-outlook-mcp",
   "description": "Outlook / Microsoft 365 MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -45,7 +45,7 @@
     "typecheck": "tsc -p tsconfig.check.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^3.0.3",
+    "@chrischall/mcp-utils": "^3.1.0",
     "@fetchproxy/server": "^3.6.2",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.1",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/office-outlook-mcp",
     "source": "github"
   },
-  "version": "0.6.1",
+  "version": "0.6.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/office-outlook-mcp",
-      "version": "0.6.1",
+      "version": "0.6.2",
       "transport": {
         "type": "stdio"
       },