slidemind 0.3.13 → 0.3.14

package/src/bridge/client/transport.mjs

@@ -0,0 +1,695 @@
+// HTTP transport to the add-in's cloud relay: sessions in scope, bridgeFetch /
+// bridgeStreamToFile, the CLI version floor, capability probes, transient retry,
+// and the delegated Graph/SharePoint token attach.
+
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { deriveEnvLabel, envPhrase, getSessionFor, readSessions } from "../config.mjs";
+import { ensureSignedIn, getGraphToken, getSharePointToken } from "../graph-auth.mjs";
+import { updateCliInstruction } from "../../install-channel.mjs";
+
+// This CLI's own version, for the add-in's minCliVersion floor (see
+// assertCliVersionSupported). Read lazily from the package manifest so the
+// module stays importable even from an odd install layout.
+let cliVersionCache = null;
+
+export function cliVersion() {
+  if (cliVersionCache) return cliVersionCache;
+  try {
+    const pkgPath = path.join(
+      path.dirname(fileURLToPath(import.meta.url)),
+      "..",
+      "..",
+      "..",
+      "package.json",
+    );
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    cliVersionCache = typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    cliVersionCache = "0.0.0";
+  }
+  return cliVersionCache;
+}
+
+// Numeric-aware dotted-version compare (no prerelease semantics — the CLI
+// releases plain X.Y.Z). Returns <0 / 0 / >0 like a comparator.
+export function compareCliVersions(a, b) {
+  const pa = String(a ?? "").split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b ?? "").split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+// The one error every version-floor check raises, so the probe path
+// (assertCliVersionSupported) and the per-response header path are
+// indistinguishable to callers and to the skills that relay the text.
+export function cliUpdateRequiredError(min) {
+  const err = new Error(
+    `slidemind CLI ${cliVersion()} is older than the minimum this add-in ` +
+      `supports (${min}). ${updateCliInstruction()}`,
+  );
+  err.code = "cli_update_required";
+  return err;
+}
+
+// `doctor` and `ready` exist to EXPLAIN a broken connection, version skew
+// included — they render it as a structured blocker with an `actor` and a
+// nextAction. Throwing the raw error out of bridgeFetch would break the one
+// command that diagnoses the problem, so they opt out of the header check
+// (their own ladder still reports cli_update_required, terminally).
+let diagnosticMode = false;
+
+export function setDiagnosticMode(on) {
+  diagnosticMode = on !== false;
+}
+
+// Every add-in response carries the version floor in `x-slidemind-min-cli`.
+// Checking it here covers routes no capability probe guards — the pane ops
+// (search/read/insert) and pairing itself — for zero extra round-trips, and it
+// fires BEFORE the status handling below so a stale CLI hitting a route that
+// does not exist yet reads "run slidemind update" instead of a bare 404.
+export function enforceVersionFloor(response) {
+  if (diagnosticMode) return;
+  const min = response?.headers?.["x-slidemind-min-cli"];
+  if (typeof min !== "string" || !min) return;
+  if (compareCliVersions(cliVersion(), min) >= 0) return;
+  throw cliUpdateRequiredError(min);
+}
+
+export function isLoopbackHostname(hostname) {
+  return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
+}
+
+// The fan-out probe (listing presentations across every paired backend) uses a
+// shorter timeout than ordinary calls so one dead/slow backend — a local relay
+// that isn't running — can't stall the whole sweep for the full 35s default.
+export function listTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_LIST_TIMEOUT_MS || "8000", 10) || 8000
+  );
+}
+
+// Engine ops (list / search / download / extract) are RELAYED through the task
+// pane: the server waits up to ~25s for a suspended pane to reconnect, then up
+// to 60s for the pane's ack. Budget above that sum so a typed pane error
+// (pane_suspended / pane_timeout) wins over a client timeout. Note `ls engines`
+// is pane-relayed too — using the 8s list timeout there masked the real
+// pane_suspended as a bare "timed out after 8000ms".
+export function engineTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+    90000
+  );
+}
+
+export function readinessTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_READY_TIMEOUT_MS || "20000", 10) ||
+    20000
+  );
+}
+
+export const NOT_PAIRED_MESSAGE =
+  "slidemind is not connected. In PowerPoint open slidemind → Settings → " +
+  "General → Connect CLI, press the link button, and run the command it shows.";
+
+// The one-command remedy every host-precondition error now points at:
+// `slidemind ready` runs authorization → reachability → version → window →
+// design ladder and materializes the bundle, so a stuck author has a single
+// next step instead of a scavenger hunt across doctor/presentations/download.
+// Appended (never substituted) to the existing prose so callers' assert.match
+// on the original text keeps passing.
+export const READY_HINT =
+  "Run `slidemind ready` to check the connection and set up in one step.";
+
+// pickPresentationEntry's variant: the caller already HAS a host, it's just
+// ambiguous — `ready` resolves the window AND the design in one shot.
+export const READY_HINT_PICK =
+  "Or run `slidemind ready` first — it resolves the window and design in one step.";
+
+// One transient blip — a pane mid-reconnect after a backend deploy, a stale
+// registration the pane is about to refresh — should not fail a whole skill
+// step. Idempotent reads retry a couple of times; mutations never do (the
+// request may already have been delivered).
+export function transientRetryDelays() {
+  const raw = process.env.SLIDEMIND_BRIDGE_RETRY_DELAYS_MS || "1500,4000";
+  return raw
+    .split(",")
+    .map((s) => parseInt(s.trim(), 10))
+    .filter((n) => Number.isFinite(n) && n >= 0);
+}
+
+// A 401 from either bridge transport. Carries the remediation as its message
+// AND a machine-readable shape, because callers that probe several backends in
+// a row have to tell "this environment doesn't have that record" (routing
+// information) from "this session is dead" (the user's problem) — see
+// resolveSearchBackend.
+export function sessionInvalidError() {
+  // Deliberately does NOT say `logout --all`: a 401 means the add-in answered
+  // "no such session" (revoked in Settings → Connect CLI, or expired). Running
+  // `setup` with a fresh command replaces this backend's record in place, so
+  // nothing has to be wiped first — and a user with two environments who wipes
+  // everything on every 401 is how the 2026-08-27 reconnect loop happened.
+  const err = new Error(
+    "slidemind session is invalid or expired: the add-in no longer knows this session " +
+      "(revoked under Settings → General → Connect CLI, or expired). Reconnect with a fresh " +
+      "command from that panel; other environments and your Microsoft 365 sign-in stay as they are.",
+  );
+  err.status = 401;
+  err.code = "session_invalid";
+  return err;
+}
+
+// True for the 401 class above, and for anything else that arrives with a 401
+// status (an older path, or a rethrown response error).
+export function isSessionInvalidError(err) {
+  if (!err) return false;
+  if (err.status === 401 || err.code === "session_invalid") return true;
+  return /slidemind session is invalid or expired/i.test(String(err.message ?? ""));
+}
+
+export function isTransientBridgeError(err) {
+  if (!err) return false;
+  // pane_suspended needs the user (foreground PowerPoint), not a blind retry —
+  // the relay already waited for a reconnect before returning it.
+  if (err.code === "pane_suspended") return false;
+  if (err.status === 404 || err.status === 502 || err.status === 503) return true;
+  if (err.status === 409 && err.code === "pane_disconnected") return true;
+  return /relay unreachable/i.test(String(err.message || ""));
+}
+
+export async function withTransientRetry(fn, isRetryable = isTransientBridgeError) {
+  const delays = transientRetryDelays();
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (attempt >= delays.length || !isRetryable(err)) throw err;
+      await new Promise((resolve) => setTimeout(resolve, delays[attempt]));
+    }
+  }
+}
+
+// The paired backends in scope for this invocation. Defaults to every paired
+// session (fan-out); `SLIDEMIND_BACKEND` narrows it to one (the CLI sets that
+// env from a `--backend <url|env>` flag) for speed or to disambiguate. Throws
+// the same actionable message as a missing pairing when nothing matches.
+export function sessionsInScope() {
+  const all = readSessions();
+  if (all.length === 0) throw new Error(NOT_PAIRED_MESSAGE);
+  const scope = process.env.SLIDEMIND_BACKEND;
+  if (scope && scope.trim()) {
+    const want = scope.trim();
+    const match = all.filter(
+      (s) =>
+        s.backendURL === want ||
+        s.label === want ||
+        deriveEnvLabel(s.backendURL) === want ||
+        s.backendURL.includes(want),
+    );
+    if (match.length === 0) {
+      throw new Error(
+        `slidemind is not paired with '${want}'. Run 'slidemind whoami' to see paired environments.`,
+      );
+    }
+    return match;
+  }
+  return all;
+}
+
+// Resolve the credential for one backend (or the default session when no
+// backendURL is given — the back-compat single-session path).
+export function sessionForBackend(backendURL) {
+  if (backendURL) {
+    const s = getSessionFor(backendURL);
+    if (!s)
+      throw new Error(
+        `slidemind is not paired with '${deriveEnvLabel(backendURL)}'.`,
+      );
+    return s;
+  }
+  const all = readSessions();
+  if (all.length === 0) throw new Error(NOT_PAIRED_MESSAGE);
+  return all[0];
+}
+
+export async function bridgeFetch(pathPart, init = {}, backendURL = null) {
+  const session = sessionForBackend(backendURL);
+  const url = `${session.backendURL}${pathPart}`;
+  const headers = {
+    accept: "application/json",
+    ...init.headers,
+    authorization: `Bearer ${session.sessionToken}`,
+  };
+
+  let response;
+  try {
+    response = await nodeRequest(url, { ...init, headers });
+  } catch (err) {
+    if (err && /ECONNREFUSED|ECONNRESET|ENOTFOUND|self-signed|fetch failed/i.test(String(err.message || err))) {
+      throw new Error(
+        `slidemind relay unreachable${envPhrase(deriveEnvLabel(session.backendURL), "on")}. Check your connection; ` +
+          "if it persists, reconnect from the add-in's Connect CLI panel.",
+      );
+    }
+    throw err;
+  }
+  enforceVersionFloor(response);
+  if (response.status === 401) throw sessionInvalidError();
+  if (response.status < 200 || response.status >= 300) {
+    let parsed = null;
+    try {
+      parsed = response.body ? JSON.parse(response.body) : null;
+    } catch {
+      /* non-JSON error body — fall back to the raw text */
+    }
+    // Prefer the machine-readable `code` (e.g. "pane_suspended",
+    // "engine_auth_expired"); fall back to the human `error` string for routes
+    // that don't emit a discrete code yet. Keep the human text in the message.
+    const machineCode =
+      parsed && typeof parsed.code === "string" ? parsed.code : null;
+    const humanError =
+      parsed && typeof parsed.error === "string" ? parsed.error : null;
+    const detail =
+      humanError ?? (response.body ? response.body.slice(0, 400) : "");
+    const err = new Error(
+      `slidemind bridge ${response.status} ${response.statusText} for ${pathPart}` +
+        (detail ? `: ${detail}` : ""),
+    );
+    err.status = response.status;
+    const code = machineCode ?? humanError;
+    if (code) err.code = code;
+    if (parsed) err.body = parsed;
+    throw err;
+  }
+  return {
+    json: async () => (response.body ? JSON.parse(response.body) : null),
+    text: async () => response.body,
+    // Exposed for routes that carry their answer partly in headers (the
+    // source-presentation read reports slide counts and truncation there, so a
+    // caller learns the deck was windowed without parsing the Markdown).
+    headers: response.headers ?? {},
+  };
+}
+
+export function nodeRequest(urlString, init = {}) {
+  const url = new URL(urlString);
+  const isHttps = url.protocol === "https:";
+  const transport = isHttps ? https : http;
+  const body = init.body ?? null;
+  const headers = { ...(init.headers ?? {}) };
+  if (body && headers["content-length"] === undefined && headers["Content-Length"] === undefined) {
+    headers["content-length"] = Buffer.byteLength(body);
+  }
+
+  const timeoutMs =
+    init.timeoutMs ??
+    (parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) || 35000);
+  return new Promise((resolve, reject) => {
+    const req = transport.request(
+      url,
+      {
+        method: init.method ?? "GET",
+        headers,
+        // Validate the cloud's real cert; only skip for a loopback dev backend
+        // (self-signed) when pointing the CLI at a local add-in for development.
+        rejectUnauthorized: isHttps ? !isLoopbackHostname(url.hostname) : undefined,
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        res.on("end", () => {
+          resolve({
+            status: res.statusCode ?? 0,
+            statusText: res.statusMessage ?? "",
+            headers: res.headers,
+            body: Buffer.concat(chunks).toString("utf8"),
+          });
+        });
+      },
+    );
+    // Default 35s > the relay's 25s wait-for-pane-reconnect, so a suspended
+    // pane surfaces a typed `pane_suspended` rather than a client timeout. A
+    // real timeout is tagged `bridge_timeout` so non-idempotent callers
+    // (insert) know the request may already have been delivered and must NOT
+    // auto-retry it.
+    req.setTimeout(timeoutMs, () => {
+      const err = new Error(
+        `slidemind bridge request timed out after ${timeoutMs}ms`,
+      );
+      err.code = "bridge_timeout";
+      req.destroy(err);
+    });
+    req.on("error", reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+// A streaming sibling of `nodeRequest`, for responses too large to hold in
+// memory. `nodeRequest` concatenates the whole body and decodes it as UTF-8 —
+// fine for JSON, but it would both balloon memory and CORRUPT binary. This pipes
+// a success response straight to `destPath` and never materializes it.
+//
+// Error and JSON bodies are still buffered: both are small by construction (an
+// error message, or the inline SVG the download route answers with), and the
+// caller needs them whole to act on.
+export function nodeRequestToFile(urlString, init = {}, destPath) {
+  const url = new URL(urlString);
+  const isHttps = url.protocol === "https:";
+  const transport = isHttps ? https : http;
+  const body = init.body ?? null;
+  const headers = { ...(init.headers ?? {}) };
+  if (
+    body &&
+    headers["content-length"] === undefined &&
+    headers["Content-Length"] === undefined
+  ) {
+    headers["content-length"] = Buffer.byteLength(body);
+  }
+  const timeoutMs =
+    init.timeoutMs ??
+    (parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) || 35000);
+
+  return new Promise((resolve, reject) => {
+    const req = transport.request(
+      url,
+      {
+        method: init.method ?? "GET",
+        headers,
+        rejectUnauthorized: isHttps
+          ? !isLoopbackHostname(url.hostname)
+          : undefined,
+      },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        const contentType = String(res.headers["content-type"] ?? "");
+        const buffered = status < 200 || status >= 300 || contentType.includes("application/json");
+        if (buffered) {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(Buffer.from(c)));
+          res.on("end", () =>
+            resolve({
+              status,
+              statusText: res.statusMessage ?? "",
+              headers: res.headers,
+              body: Buffer.concat(chunks).toString("utf8"),
+              streamed: false,
+            }),
+          );
+          res.on("error", reject);
+          return;
+        }
+        const out = fs.createWriteStream(destPath);
+        let bytesWritten = 0;
+        const total = Number.parseInt(
+          String(res.headers["content-length"] ?? ""),
+          10,
+        );
+        res.on("data", (c) => {
+          bytesWritten += c.length;
+          init.onProgress?.(bytesWritten, Number.isFinite(total) ? total : null);
+        });
+        res.pipe(out);
+        // A stream that dies mid-flight must reject, not resolve with a truncated
+        // file — the caller deletes the partial and surfaces the failure.
+        res.on("error", (err) => {
+          out.destroy();
+          reject(err);
+        });
+        out.on("error", reject);
+        out.on("finish", () =>
+          resolve({
+            status,
+            statusText: res.statusMessage ?? "",
+            headers: res.headers,
+            bytesWritten,
+            streamed: true,
+          }),
+        );
+      },
+    );
+    req.setTimeout(timeoutMs, () => {
+      const err = new Error(
+        `slidemind bridge request timed out after ${timeoutMs}ms`,
+      );
+      err.code = "bridge_timeout";
+      req.destroy(err);
+    });
+    req.on("error", reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+// `bridgeFetch` for a response streamed to disk. Shares the session lookup,
+// auth header and non-2xx error mapping so a streaming call fails exactly like
+// every other bridge call.
+export async function bridgeStreamToFile(pathPart, init, destPath, backendURL = null) {
+  const session = sessionForBackend(backendURL);
+  const url = `${session.backendURL}${pathPart}`;
+  const headers = {
+    accept: "application/octet-stream, application/json",
+    ...init.headers,
+    authorization: `Bearer ${session.sessionToken}`,
+  };
+  let response;
+  try {
+    response = await nodeRequestToFile(url, { ...init, headers }, destPath);
+  } catch (err) {
+    if (
+      err &&
+      /ECONNREFUSED|ECONNRESET|ENOTFOUND|self-signed|fetch failed/i.test(
+        String(err.message || err),
+      )
+    ) {
+      throw new Error(
+        `slidemind relay unreachable${envPhrase(deriveEnvLabel(session.backendURL), "on")}. Check your connection; ` +
+          "if it persists, reconnect from the add-in's Connect CLI panel.",
+      );
+    }
+    throw err;
+  }
+  enforceVersionFloor(response);
+  if (response.status === 401) throw sessionInvalidError();
+  if (response.status < 200 || response.status >= 300) {
+    let parsed = null;
+    try {
+      parsed = response.body ? JSON.parse(response.body) : null;
+    } catch {
+      /* non-JSON error body */
+    }
+    const machineCode =
+      parsed && typeof parsed.code === "string" ? parsed.code : null;
+    const humanError =
+      parsed && typeof parsed.error === "string" ? parsed.error : null;
+    const detail =
+      humanError ?? (response.body ? response.body.slice(0, 400) : "");
+    const err = new Error(
+      `slidemind bridge ${response.status} ${response.statusText} for ${pathPart}` +
+        (detail ? `: ${detail}` : ""),
+    );
+    err.status = response.status;
+    const code = machineCode ?? humanError;
+    if (code) err.code = code;
+    if (parsed) err.body = parsed;
+    throw err;
+  }
+  return response;
+}
+
+export function envInt(name, fallback) {
+  const n = parseInt(process.env[name] || "", 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// One capability probe per backend per process. Keyed by the RESOLVED backend
+// URL (callers always resolve before probing), so multiple paired backends on
+// mixed versions each get their own answer.
+export const backendCapabilitiesCache = new Map();
+
+// The probe result, failure included. Every ordinary caller wants the graceful
+// `{}` (an older backend simply 404s this path), but a caller that is DIAGNOSING
+// has to see a 401 — "this session is revoked" must never be reported as "this
+// add-in is too old". Kept as one cached promise so the distinction costs no
+// extra round-trip.
+export function backendCapabilitiesResult(backendURL) {
+  let probe = backendCapabilitiesCache.get(backendURL);
+  if (!probe) {
+    probe = (async () => {
+      try {
+        const res = await bridgeFetch(
+          "/api/cli/capabilities",
+          { timeoutMs: listTimeoutMs() },
+          backendURL,
+        );
+        return { caps: (await res.json()) ?? {}, error: null };
+      } catch (err) {
+        // Older backends 404 this path (with a non-JSON body) — no
+        // capabilities: sync render, no version floor.
+        return { caps: {}, error: err };
+      }
+    })();
+    backendCapabilitiesCache.set(backendURL, probe);
+  }
+  return probe;
+}
+
+export async function backendCapabilities(backendURL) {
+  return (await backendCapabilitiesResult(backendURL)).caps;
+}
+
+export async function backendSupportsRenderJobs(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.renderJobs === true;
+}
+
+// Pane-free brand-scoped routes (/api/cli/brands/:brandId/*): design-bundle,
+// translate and render keyed by the brandId the deck's .bundle-ref.json already
+// stores (presFP == brandId), instead of the pane registry — so a bound deck
+// keeps building after every pane key aged out of the add-in's registry (or
+// with PowerPoint closed entirely). Advertised by newer add-ins only.
+export async function backendSupportsBrandRoutes(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.brandRoutes === true;
+}
+
+// Whether a backend generates concept mockup images for a brand over the
+// pane-free `/api/cli/brands/:brandId/concept-images` route (see
+// generateConceptImagesForBrand). Advertised by newer add-ins only; older ones
+// omit the flag and the caller degrades to "continue without".
+export async function backendSupportsConceptImages(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.conceptImages === true;
+}
+
+// Whether a backend generates regular images over the pane-free
+// `/api/cli/brands/:brandId/images` route (see generateImageForBrand).
+// Advertised by newer add-ins only.
+export async function backendSupportsImageGeneration(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.imageGeneration === true;
+}
+
+// Whether a backend can list the corporate designs a user may build against
+// (`GET /api/cli/brands`). It is what lets `ready` bind a deck with PowerPoint
+// closed — without it the only way to learn a design's identity is an open
+// window. Advertised by newer add-ins only.
+export async function backendSupportsBrandsList(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.brandsList === true;
+}
+
+// Whether a backend can read the SOURCE deck behind a chosen slide search
+// result (`/api/cli/presentations/:presId/source-presentation`). Advertised by
+// newer add-ins only; older ones omit the flag and the caller must say so
+// rather than surfacing a bare 404.
+export async function backendSupportsSourcePresentation(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.sourcePresentation === true;
+}
+
+// Pane-free ENGINE routes (`/api/cli/engines`, `/api/cli/searches/*`): engine
+// discovery, search and every per-result fetch answered off the CLI session
+// itself instead of being relayed through the task-pane webview — the one
+// transport that a backgrounded PowerPoint is free to suspend mid-run.
+// Advertised by newer add-ins only; older ones keep the pane relay, which stays
+// as the compat path (see the direct-route block further down).
+export async function backendSupportsEngineRoutes(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.engineRoutes === true;
+}
+
+// Whether a backend honours a delegated Microsoft Graph token on the pane-free
+// engine routes — the CLI's own identity for SharePoint-backed content
+// (`slidemind login`, src/bridge/graph-auth.mjs). Gates BOTH the attach and the
+// remediation text: naming `slidemind login` on an add-in that ignores the token
+// would send a user through a browser flow that changes nothing.
+export async function backendSupportsGraphDelegated(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.graphDelegated === true;
+}
+
+// The add-in's hard version floor: /api/cli/capabilities advertises the oldest
+// CLI it still speaks (`minCliVersion`). An older CLI must refuse to proceed —
+// mid-rollout skew otherwise surfaces as confusing route/contract errors deep
+// in a render — and prompt the one actionable fix. No-op when the backend
+// doesn't advertise a floor (older add-ins) or the CLI meets it.
+export async function assertCliVersionSupported(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  const min = typeof caps?.minCliVersion === "string" ? caps.minCliVersion : null;
+  if (!min || compareCliVersions(cliVersion(), min) >= 0) return;
+  throw cliUpdateRequiredError(min);
+}
+
+// The user's delegated tokens for a backend, or nulls. Attached ONLY to the
+// pane-free engine ops: they are the user's own Entra identity, and render,
+// bundle, whoami and the pane relay have no business carrying them (the pane
+// signs its own requests with a browser token that is strictly fresher).
+//
+// When nothing is stored, the sign-in RUNS HERE — browser opens, the command
+// blocks until the human finishes (graph-auth.ensureSignedIn, once per
+// process). So login is not a separate ritual: the first engine command of a
+// fresh machine walks the user through it, and every later one rides the
+// stored refresh token silently. Null only when the add-in doesn't honour the
+// tokens, or the sign-in was refused/abandoned — the backend then answers its
+// typed `login_required`, which the blocker below renders.
+export async function engineGraphToken(backendURL, { signIn = true } = {}) {
+  if (!backendURL) return null;
+  if (!(await backendSupportsGraphDelegated(backendURL))) return null;
+  let token = await getGraphToken(backendURL);
+  if (!token && signIn && (await ensureSignedIn(backendURL))) {
+    token = await getGraphToken(backendURL);
+  }
+  return token;
+}
+
+// The SharePoint-resource sibling (same sign-in, same refresh token): the
+// backend resolves `sg:` site-group membership from the PAIR, and on a
+// SharePoint-configured deployment refuses corpus search without it.
+export async function engineSpToken(backendURL, { signIn = true } = {}) {
+  if (!backendURL) return null;
+  if (!(await backendSupportsGraphDelegated(backendURL))) return null;
+  let token = await getSharePointToken(backendURL);
+  if (!token && signIn && (await ensureSignedIn(backendURL))) {
+    token = await getSharePointToken(backendURL);
+  }
+  return token;
+}
+
+// Both delegated tokens as body fields, for the POST routes. Empty when there
+// is nothing to attach, so an older backend sees the body it always did.
+export async function delegatedBodyFields(backendURL) {
+  const [graphToken, spToken] = await Promise.all([
+    engineGraphToken(backendURL),
+    engineSpToken(backendURL),
+  ]);
+  return {
+    ...(graphToken ? { graphApiToken: graphToken } : {}),
+    ...(spToken ? { spApiToken: spToken } : {}),
+  };
+}
+
+// The byte routes are GETs, so the delegated tokens ride headers instead of
+// body fields. Empty (not absent-valued) when there is no token, so the request
+// headers are unchanged for everyone who never signed in.
+export async function graphHeaders(backendURL, { signIn = true } = {}) {
+  const [graphToken, spToken] = await Promise.all([
+    engineGraphToken(backendURL, { signIn }),
+    engineSpToken(backendURL, { signIn }),
+  ]);
+  return {
+    ...(graphToken ? { "x-slidemind-graph-token": graphToken } : {}),
+    ...(spToken ? { "x-slidemind-sp-token": spToken } : {}),
+  };
+}