slidemind 0.3.13 → 0.3.14

package/src/bridge/client/engine-routing.mjs

@@ -0,0 +1,237 @@
+// Pane-free engine routes (the DIRECT path)
+//
+// Newer add-ins serve the whole engine surface off the CLI session:
+//   GET  /api/cli/engines                                  catalog (same path,
+//                                                          answered pane-free)
+//   POST /api/cli/searches                                 → { searchId, results }
+//   GET  /api/cli/searches/:id/results/:sel/image           stream
+//   GET  /api/cli/searches/:id/results/:sel/thumbnail       stream
+//   GET  /api/cli/searches/:id/results/:sel/slide           stream (one-slide .pptx)
+//   GET  /api/cli/searches/:id/results/:sel/source-presentation
+//
+// The searchId is SERVER-owned (per user, short TTL) rather than bound to a
+// window's pane, and a request carries only that searchId plus the selection
+// index — the server resolves the source config it stored at search time, so no
+// client ever names a file, site or drive.
+//
+// How a function picks its path: a `presId` means "relay through THAT window"
+// (the compat path old add-ins need and live insert always needs); NO presId
+// plus an explicit `backendURL`/`brandId` means "run this pane-free". Callers
+// resolve the backend once with resolveEngineBackend(), which returns null when
+// nothing paired advertises the routes — that null is the signal to fall back
+// to the pane relay, never a failure.
+
+import { deriveEnvLabel } from "../config.mjs";
+import { getDesignBundleForBrand, getDesignBundleForBrandAnyBackend } from "./brands.mjs";
+import { isSessionInvalidError, sessionsInScope, bridgeFetch, backendCapabilitiesResult, backendSupportsEngineRoutes } from "./transport.mjs";
+
+export function searchRoute(searchId, suffix = "") {
+  return `/api/cli/searches/${encodeURIComponent(String(searchId))}${suffix}`;
+}
+
+// A searchId is a number on the pane relay (the pane mints it per window) and an
+// opaque server-minted id on the direct routes — accept either, reject anything
+// else before a call goes near the network.
+export function assertSearchId(fn, searchId) {
+  const ok =
+    (typeof searchId === "number" && Number.isFinite(searchId)) ||
+    (typeof searchId === "string" && searchId.trim().length > 0);
+  if (!ok) throw new Error(`${fn}: searchId is required`);
+}
+
+// A large asset legitimately takes longer than an engine op: the server is
+// fetching from SharePoint/blob AND piping. Separate budget so raising it
+// doesn't loosen every other bridge call.
+export function downloadTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_DOWNLOAD_TIMEOUT_MS || "600000", 10) ||
+    600000
+  );
+}
+
+export function resultRoute(searchId, selection, leaf, params = null) {
+  const qs = params && [...params.keys()].length > 0 ? `?${params}` : "";
+  return `${searchRoute(searchId, `/results/${encodeURIComponent(String(selection))}/${leaf}`)}${qs}`;
+}
+
+// Per-process memo of which backend serves a brand's engine routes, so a
+// multi-environment session pays the brand probe at most once per design.
+export const engineBackendForBrand = new Map();
+
+// A searchId is opaque (server-minted, hex) on the direct routes and numeric on
+// the pane relay. The distinction routes: an opaque id names a record on the
+// backend that minted it, and the pane can NEVER serve it — its handler only
+// understands its own per-window numeric ids.
+export function isOpaqueSearchId(searchId) {
+  return (
+    typeof searchId === "string" &&
+    searchId.trim() !== "" &&
+    !/^\d+$/.test(searchId.trim())
+  );
+}
+
+// Which paired backend minted this server-owned search record. Search records
+// are oid-scoped, so a foreign environment answers the same 404 as an expired
+// id — probing every engine-routes candidate with the record's own GET is both
+// exact and cheap (2h TTL, at most a couple of environments). Returns null when
+// no candidate holds it: expired, or minted by an environment no longer in
+// scope. Never falls back to the pane — see isOpaqueSearchId.
+//
+// One failure class is NOT routing information: a 401 means the session itself
+// is dead (revoked in the add-in's Connect CLI panel, or aged past its hard
+// lifetime). Swallowing it reports a revoked session as "that search expired",
+// and the user then re-runs a search that 401s the same way. So per-candidate
+// failures are collected and a session-invalid one is rethrown instead.
+export async function resolveSearchBackend(searchId) {
+  if (!isOpaqueSearchId(searchId)) return null;
+  const failures = [];
+  for (const s of sessionsInScope()) {
+    // A revoked session 401s the capability probe too, and that answer is
+    // indistinguishable from "old add-in" unless the failure is kept.
+    const probe = await backendCapabilitiesResult(s.backendURL);
+    if (probe.error && isSessionInvalidError(probe.error)) {
+      failures.push(probe.error);
+      continue;
+    }
+    if (probe.caps?.engineRoutes !== true) continue;
+    try {
+      await bridgeFetch(searchRoute(searchId), {}, s.backendURL);
+      return s.backendURL;
+    } catch (err) {
+      // 404 (not this environment's record / expired) or unreachable — try the
+      // next candidate; the distinction doesn't matter to routing.
+      failures.push(err);
+    }
+  }
+  // The two failures that are NOT the record talking: a dead session, and a
+  // missing Microsoft 365 sign-in (the record re-read is an engine route, so
+  // it refuses with the rest of corpus search). Reported as "that search
+  // expired", both send the user to re-run a search that fails the same way —
+  // so they outrank the expired-record answer.
+  const blocking = failures.find(
+    (e) => isSessionInvalidError(e) || e?.code === "login_required",
+  );
+  if (blocking) throw blocking;
+  return null;
+}
+
+// Which paired backend runs the pane-free engine routes for this call. An
+// explicit backendURL is honoured as-is (the caller already resolved a window or
+// a deck). Otherwise: every session in scope that advertises the routes is a
+// candidate — with ONE connected environment (the normal case) that IS the
+// answer, and no probe is worth paying for it. With several connected, the
+// DECK's bound design decides, never an open window's origin. presFP/brandId is
+// content-derived, so the SAME design onboarded in two environments carries the
+// SAME id — candidates are therefore probed FIRST, and only when none serves
+// the design does the caller fall back to the pane relay (the design lives on
+// an older add-in, and searching a different corpus would fold ITS slides into
+// this deck). Returns null for that fallback and when nothing paired serves the
+// routes at all.
+export async function resolveEngineBackend({ backendURL = null, brandId = null } = {}) {
+  if (backendURL) {
+    return (await backendSupportsEngineRoutes(backendURL)) ? backendURL : null;
+  }
+  const sessions = sessionsInScope();
+  const candidates = [];
+  for (const s of sessions) {
+    if (await backendSupportsEngineRoutes(s.backendURL)) candidates.push(s.backendURL);
+  }
+  if (candidates.length === 0) return null;
+  // Exactly one CONNECTED environment: there is nothing else the deck could
+  // belong to. Note the test is on the sessions, not on the candidates — during
+  // a rollout only one of several environments serves the routes, and taking it
+  // regardless would have searched the wrong corpus.
+  if (sessions.length === 1) return candidates[0];
+  if (brandId) {
+    // The memo only stands while that environment is still a candidate.
+    const memo = engineBackendForBrand.get(brandId);
+    if (memo) return candidates.includes(memo) ? memo : null;
+    // Candidates first: an environment that serves both the design AND the
+    // engine routes wins outright, even when an older environment also has the
+    // (content-identical) design.
+    for (const be of candidates) {
+      try {
+        await getDesignBundleForBrand(brandId, { backendURL: be });
+        engineBackendForBrand.set(brandId, be);
+        return be;
+      } catch {
+        // This candidate doesn't serve the design — try the next.
+      }
+    }
+    try {
+      const { backendURL: be } = await getDesignBundleForBrandAnyBackend(brandId);
+      engineBackendForBrand.set(brandId, be);
+      // Only a non-candidate can answer here: the design's environment is an
+      // older add-in with no engine routes. null sends the caller to that
+      // environment's pane relay instead of a different corpus.
+      return null;
+    } catch {
+      // No backend owns the design (unknown brand, old add-in) — fall through
+      // rather than guessing an environment.
+    }
+  }
+  if (candidates.length === 1) return candidates[0];
+  const err = new Error(
+    `Several connected environments run engine search (${candidates
+      .map((u) => deriveEnvLabel(u))
+      .join(", ")}). Scope the command with --backend <env>, point it at a ` +
+      "bound deck (--deck) so the deck's design picks one, or name an open " +
+      "window with --to <presId> to relay through it.",
+  );
+  err.code = "engine_backend_ambiguous";
+  throw err;
+}
+
+// Which connected environments answer the pane-free engine routes — the
+// "backend authoring ready" half of the readiness picture (`doctor`, `ready`),
+// reported as ENV LABELS so no URL can reach a printed line. Pass
+// connectionStatus()'s `backends` to skip environments that are already known
+// unreachable; without it every session in scope is probed.
+export async function engineReachability({ backends = null } = {}) {
+  const urls = Array.isArray(backends)
+    ? backends.filter((b) => b?.ok && b.backendURL).map((b) => b.backendURL)
+    : sessionsInScope().map((s) => s.backendURL);
+  const envs = [];
+  for (const url of urls) {
+    if (await backendSupportsEngineRoutes(url)) envs.push(deriveEnvLabel(url));
+  }
+  return { available: envs.length > 0, envs };
+}
+
+// Resolve + verify the backend for a direct engine call. Throws a typed
+// `engine_routes_unavailable` when the caller asked for the pane-free path on a
+// backend that doesn't serve it — a programming error by then, since callers go
+// through resolveEngineBackend first, but it must never surface as a bare 404.
+export async function directEngineBackend(fn, { backendURL = null, brandId = null }) {
+  const be = backendURL ?? (await resolveEngineBackend({ brandId }));
+  if (be && (await backendSupportsEngineRoutes(be))) return be;
+  const err = new Error(
+    `${fn}: no connected slidemind add-in serves pane-free engine routes` +
+      `${be ? ` ('${deriveEnvLabel(be)}' is too old)` : ""}. ` +
+      "Open PowerPoint with the slidemind pane so the search can be relayed, or update the add-in.",
+  );
+  err.code = "engine_routes_unavailable";
+  throw err;
+}
+
+// Corpus search runs as the USER: the pane-free engine routes resolve the
+// caller's group membership live from the delegated tokens `slidemind login`
+// minted, and answer `401 { code: "login_required", action: "…" }` without
+// them. Shape it like the connection ladder's rungs — `{ code, actor, message }`
+// — so the CLI can print ONE actionable line and an agent knows it cannot clear
+// this one itself (the sign-in needs a browser and a human). Returns null for
+// any other error.
+export function loginRequiredBlocker(err) {
+  if (err?.code !== "login_required") return null;
+  const action =
+    typeof err?.body?.action === "string" && err.body.action.trim()
+      ? err.body.action.trim()
+      : "run `slidemind login` to sign in to Microsoft 365";
+  return {
+    code: "login_required",
+    actor: "user",
+    message:
+      `slidemind needs your Microsoft 365 sign-in before it can search the corpus — ${action}. ` +
+      "Everything else (render, bundle, imagery already downloaded) keeps working.",
+  };
+}

package/src/bridge/client/engine-search.mjs

@@ -0,0 +1,310 @@
+// Engine search + result download (pane-free direct path, pane relay fallback).
+
+import { deriveEnvLabel } from "../config.mjs";
+import { assertSearchId, downloadTimeoutMs, resultRoute, directEngineBackend } from "./engine-routing.mjs";
+import { pickAnyPresentationEntry } from "./pane-ops.mjs";
+import { resolveBackendForPres, engineOpWithPaneWait } from "./presentations.mjs";
+import { engineTimeoutMs, bridgeFetch, bridgeStreamToFile, envInt, delegatedBodyFields, graphHeaders } from "./transport.mjs";
+
+// Brand-engine search through the local bridge. New add-ins run this
+// server-side with the relayed user token; older add-ins may fall back to a
+// task-pane proxy. Returns a searchId + numbered results (image thumbnails, or
+// slide results carrying per-slide text + metadata). `subtype`/`intent`/`top`
+// are passed through for slide engines (image engines ignore intent); omit them
+// and the server uses its defaults (back-compat with older add-ins).
+//
+// `engineId` may also be a SCOPE sentinel (`scope:all` / `scope:sharepoint`) —
+// an unfiltered search over the whole corpus rather than one engine's saved
+// folder filter. A scope has no subtype to derive its index from, so it needs an
+// explicit `resultType`; the add-in rejects a scope search without one.
+//
+// With NO presId and a resolved `backendURL`/`brandId` this runs pane-free
+// against `POST /api/cli/searches` (same body) and tags the answer with the
+// backend that owns the searchId.
+export async function engineSearch({
+  presId = null,
+  engineId,
+  query,
+  subtype = null,
+  resultType = null,
+  intent = null,
+  top = null,
+  backendURL = null,
+  brandId = null,
+  // When the chosen pane is suspended, wait CLIENT-side for THIS window to wake
+  // (the single-window default). engineSearchAnyPane sets this false for all but
+  // the last candidate so it can fail over to another live window instead.
+  waitOnSuspend = true,
+  timeoutMs = null,
+}) {
+  if (!engineId) throw new Error("engineSearch: engineId is required");
+  if (!query) throw new Error("engineSearch: query is required");
+  const direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) throw new Error("engineSearch: presId is required");
+  const body = { engineId, query };
+  if (subtype) body.subtype = subtype;
+  // Additive: omitted unless set, so the body an older add-in sees is unchanged.
+  if (resultType) body.resultType = resultType;
+  if (intent) body.intent = intent;
+  if (typeof top === "number") body.top = top;
+  if (direct) {
+    const be = await directEngineBackend("engineSearch", { backendURL, brandId });
+    // The user's own identity: the backend resolves the caller's group
+    // membership from these tokens per request and refuses without them
+    // (login_required). Search also seeds the speculative insert cache
+    // server-side, which is why it carries the Graph token as well as the
+    // byte GETs.
+    const delegated = await delegatedBodyFields(be);
+    const res = await bridgeFetch(
+      "/api/cli/searches",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ ...body, ...delegated }),
+        timeoutMs: timeoutMs ?? engineTimeoutMs(),
+      },
+      be,
+    );
+    const data = (await res.json()) ?? {};
+    // Tag the routing state (like the brand routes do) so every follow-up pick
+    // hits the backend that owns the searchId. `env` is the printable half —
+    // callers must never surface backendURL.
+    return { ...data, backendURL: be, env: deriveEnvLabel(be) };
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const run = async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/search`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: timeoutMs ?? engineTimeoutMs(),
+      },
+      b,
+    );
+    return res.json(); // { ok, searchId, engineId, subtype, intent, resultCount, gridDataUri?, results }
+  };
+  return waitOnSuspend ? engineOpWithPaneWait(presId, be, run) : run(presId, be);
+}
+
+// A suspended/throttled background webview must not strand a window-AGNOSTIC
+// engine search: the catalog is per-user, so any connected pane can answer it.
+// Try the picked pane first, then every other connected pane on the same
+// backend (non-suspended first), failing fast past each unresponsive one; the
+// LAST candidate keeps the normal "click the pane to wake it" wait so a genuine
+// single-window/all-asleep case still surfaces the actionable prompt. Returns
+// the search result tagged with the presId/backendURL that actually answered —
+// the searchId is bound to THAT window, so callers must thread it into
+// follow-up view/insert/add-slide. An explicit presId pins the window (no
+// failover — the caller asked for that specific one).
+export async function engineSearchAnyPane({
+  registry,
+  explicitPresId = null,
+  engineId,
+  query,
+  subtype = null,
+  resultType = null,
+  intent = null,
+  top = null,
+}) {
+  const primary = pickAnyPresentationEntry(registry, explicitPresId);
+  const primaryBackend = primary.backendURL ?? null;
+  let candidates;
+  if (explicitPresId) {
+    candidates = [primary];
+  } else {
+    const others = (Array.isArray(registry) ? registry : [])
+      .filter(
+        (p) =>
+          p.presId !== primary.presId &&
+          p.connected !== false &&
+          (p.backendURL ?? null) === primaryBackend,
+      )
+      .sort((a, b) => (a.suspendedAt ? 1 : 0) - (b.suspendedAt ? 1 : 0));
+    candidates = [primary, ...others];
+  }
+  const failoverTimeout = envInt(
+    "SLIDEMIND_BRIDGE_ENGINE_FAILOVER_TIMEOUT_MS",
+    25000,
+  );
+  let lastErr = null;
+  for (let i = 0; i < candidates.length; i++) {
+    const cand = candidates[i];
+    const isLast = i === candidates.length - 1;
+    try {
+      const res = await engineSearch({
+        presId: cand.presId,
+        engineId,
+        query,
+        subtype,
+        resultType,
+        intent,
+        top,
+        backendURL: cand.backendURL ?? primaryBackend,
+        waitOnSuspend: isLast,
+        timeoutMs: isLast ? null : failoverTimeout,
+      });
+      return {
+        ...res,
+        presId: cand.presId,
+        backendURL: cand.backendURL ?? primaryBackend,
+      };
+    } catch (err) {
+      lastErr = err;
+      // A suspended/frozen/slow pane is recoverable by trying the next window;
+      // anything else (bad engineId, auth, 4xx) is real — surface it now.
+      const recoverable =
+        err?.code === "pane_suspended" ||
+        err?.code === "pane_timeout" ||
+        err?.code === "bridge_timeout" ||
+        err?.status === 503 ||
+        err?.status === 504;
+      if (isLast || !recoverable) throw err;
+    }
+  }
+  throw lastErr ?? new Error("engineSearchAnyPane: no candidate panes");
+}
+
+// Fetch a chosen engine result's bytes through the local bridge. For image
+// engines this returns SVG/PNG bytes (+ optional recoloured svgMarkup) WITHOUT
+// inserting onto a slide.
+//
+// Pane-only by design: the pane-free route table streams (see
+// engineDownloadToFile), and this base64-through-the-ack path only exists for
+// add-ins that predate streaming — which by definition predate the direct
+// routes too.
+export async function engineDownload({
+  presId,
+  searchId,
+  selection,
+  iconColor = null,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("engineDownload: presId is required");
+  assertSearchId("engineDownload", searchId);
+  if (typeof selection !== "number") {
+    throw new Error("engineDownload: selection (number) is required");
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { searchId, selection };
+  if (iconColor) body.iconColor = iconColor;
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/download`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        // Same relay path as engine/search — outlast the server's reconnect
+        // wait + pane ack timeout.
+        timeoutMs:
+          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+          90000,
+      },
+      b,
+    );
+    return res.json(); // { ok, base64, mimeType, svgMarkup }
+  });
+}
+
+// Stream a chosen engine result's bytes to `destPath`. The size-unbounded
+// download: the pane's Socket.IO ack carries only a signed source reference, and
+// the add-in server fetches it and pipes the body here — so nothing buffers the
+// whole image and there is no base64 4/3 inflation. `engineDownload` above sends
+// the bytes through the pane ack instead and is therefore capped by the relay's
+// 10 MB frame limit; prefer this for anything that might be large.
+//
+// An SVG result comes back as JSON (`{ ok, mimeType, svgMarkup }`) rather than a
+// byte stream: it is kilobytes and its recolour happens pane-side. Callers get
+// `{ svgMarkup }` in that case and `{ bytesWritten, mimeType }` otherwise, so they
+// can persist whichever arrived.
+//
+// With NO presId and a resolved `backendURL`/`brandId` this streams pane-free
+// from `GET /api/cli/searches/:searchId/results/:selection/image` — same answer
+// shape, no window involved.
+export async function engineDownloadToFile({
+  presId = null,
+  searchId,
+  selection,
+  destPath,
+  iconColor = null,
+  backendURL = null,
+  brandId = null,
+  onProgress = null,
+}) {
+  const direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) {
+    throw new Error("engineDownloadToFile: presId is required");
+  }
+  assertSearchId("engineDownloadToFile", searchId);
+  if (typeof selection !== "number") {
+    throw new Error("engineDownloadToFile: selection (number) is required");
+  }
+  if (!destPath) throw new Error("engineDownloadToFile: destPath is required");
+  // Both paths answer with the same two shapes (streamed bytes, or the inline
+  // SVG as JSON), so the response shaping is authored once.
+  const shape = (res) => {
+    if (!res.streamed) {
+      // The inline-SVG answer (kilobytes) arrives as JSON, not as a byte stream.
+      const parsed = res.body ? JSON.parse(res.body) : {};
+      return { ok: true, streamed: false, ...parsed };
+    }
+    const warningsHeader = res.headers?.["x-slidemind-warnings"];
+    let warnings;
+    if (warningsHeader) {
+      try {
+        warnings = JSON.parse(warningsHeader);
+      } catch {
+        // A malformed header must not fail a download that otherwise succeeded.
+      }
+    }
+    return {
+      ok: true,
+      streamed: true,
+      mimeType: String(res.headers?.["content-type"] ?? "") || null,
+      bytesWritten: res.bytesWritten,
+      ...(warnings ? { warnings } : {}),
+    };
+  };
+  if (direct) {
+    const b = await directEngineBackend("engineDownloadToFile", {
+      backendURL,
+      brandId,
+    });
+    // Only the recolour rides the query string — the RESOURCE is never
+    // client-supplied on this path; the server resolves it from searchId+selection.
+    const params = new URLSearchParams();
+    if (iconColor) params.set("iconColor", iconColor);
+    const res = await bridgeStreamToFile(
+      resultRoute(searchId, selection, "image", params),
+      {
+        method: "GET",
+        headers: await graphHeaders(b),
+        timeoutMs: downloadTimeoutMs(),
+        onProgress,
+      },
+      destPath,
+      b,
+    );
+    return shape(res);
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { searchId, selection };
+  if (iconColor) body.iconColor = iconColor;
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeStreamToFile(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/download-stream`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: downloadTimeoutMs(),
+        onProgress,
+      },
+      destPath,
+      b,
+    );
+    return shape(res);
+  });
+}