slidemind 0.3.20 → 0.4.1

package/src/bridge/client/transport.mjs

@@ -8,7 +8,7 @@ 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 { ensureSignedIn, getGraphToken, getSharePointToken, tokenRefreshFailure } from "../graph-auth.mjs";
 import { updateCliInstruction } from "../../install-channel.mjs";
 
 // This CLI's own version, for the add-in's minCliVersion floor (see
@@ -184,8 +184,7 @@ export function isTransientBridgeError(err) {
   return /relay unreachable/i.test(String(err.message || ""));
 }
 
-export async function withTransientRetry(fn, isRetryable = isTransientBridgeError) {
-  const delays = transientRetryDelays();
+export async function withTransientRetry(fn, isRetryable = isTransientBridgeError, delays = transientRetryDelays()) {
   for (let attempt = 0; ; attempt += 1) {
     try {
       return await fn();
@@ -283,6 +282,7 @@ export async function bridgeFetch(pathPart, init = {}, backendURL = null) {
         (detail ? `: ${detail}` : ""),
     );
     err.status = response.status;
+    err.headers = response.headers ?? {};
     const code = machineCode ?? humanError;
     if (code) err.code = code;
     if (parsed) err.body = parsed;
@@ -499,6 +499,7 @@ export async function bridgeStreamToFile(pathPart, init, destPath, backendURL =
         (detail ? `: ${detail}` : ""),
     );
     err.status = response.status;
+    err.headers = response.headers ?? {};
     const code = machineCode ?? humanError;
     if (code) err.code = code;
     if (parsed) err.body = parsed;
@@ -516,40 +517,376 @@ 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.
+// One capability probe per backend, cached for CAPABILITIES_TTL_MS. Keyed by
+// the RESOLVED backend URL (callers always resolve before probing), so
+// multiple paired backends on mixed versions each get their own answer.
+//
+// Entries are `{probe, at}`: a short-lived CLI never notices the TTL, the
+// long-lived workspace daemon does — a deployment can flip a policy flag
+// while it runs. A queued remote MUTATION passes `refresh: true` and bypasses
+// the cache outright; batch reads may take the cached answer.
+export const CAPABILITIES_TTL_MS = 60_000;
 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 () => {
+// A probe that did not get an answer is tried again before it is reported:
+// `CAPABILITY_PROBE_ATTEMPTS` requests in all, spaced by the server's
+// `Retry-After` when it sent one (it does on 429) and by this backoff otherwise.
+export const CAPABILITY_PROBE_ATTEMPTS = 3;
+export const CAPABILITY_PROBE_BACKOFF_MS = [1_000, 2_000];
+export const CAPABILITY_PROBE_MAX_DELAY_MS = 30_000;
+
+// Seconds or an HTTP date, as `Retry-After` allows; null when absent/unusable.
+function retryAfterDelayMs(err, now = Date.now()) {
+  const value = err?.headers?.["retry-after"];
+  if (value == null || value === "") return null;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
+  const date = Date.parse(String(value));
+  return Number.isFinite(date) ? Math.max(0, date - now) : null;
+}
+
+// What one failed probe request says about the backend's capabilities:
+//   absent    404 — an add-in from before /api/cli/capabilities. That IS an
+//             answer: no capabilities, and asking again will not change it.
+//   unknown   anything else — a timeout, a 5xx, a 429, an unreachable relay, a
+//             revoked session. Nothing was learned about the capabilities.
+// Of the unknowns, two are not worth a second request: a 401 (the session is
+// dead; the error already names the remediation) and the add-in's version floor
+// (the answer is "update the CLI", however often it is asked).
+export function probeOutcome(err) {
+  if (err?.status === 404) return "absent";
+  return "unknown";
+}
+
+function probeRetryable(err) {
+  if (probeOutcome(err) !== "unknown") return false;
+  if (isSessionInvalidError(err)) return false;
+  if (err?.code === "cli_update_required") return false;
+  return true;
+}
+
+// The probe result, failure included, as `{ status, caps, error, attempts }`:
+//   answered   `caps` is what the add-in advertises (`error` null)
+//   absent     the add-in predates the route (`caps` {}, `error` the 404):
+//              no capabilities — sync render, no version floor, pane relay
+//   unknown    the probe FAILED to get an answer (`caps` null, `error` the last
+//              failure). It is not an answer and is never read as one: a
+//              capability that could not be discovered is neither present nor
+//              absent. Callers that can act on the distinction read `status`;
+//              everyone else goes through `backendCapabilities`, which refuses
+//              with a typed, retryable error instead of handing back `{}`.
+//
+// Only ANSWERS are cached (answered and absent — both are facts about the
+// deployment, and good for CAPABILITIES_TTL_MS). An unknown is retried here,
+// shared with every caller that asks while it is in flight, and then dropped:
+// caching it would turn one slow second into sixty seconds of every optional
+// feature "missing" and every routing decision taking the wrong path (x103:
+// one timed-out probe sent the icon fetch to the pane relay of a closed
+// PowerPoint, and reported "No PowerPoint window" for it).
+export function backendCapabilitiesResult(
+  backendURL,
+  {
+    refresh = false,
+    maxAgeMs = CAPABILITIES_TTL_MS,
+    attempts = CAPABILITY_PROBE_ATTEMPTS,
+    sleep: wait = sleep,
+  } = {},
+) {
+  const cached = backendCapabilitiesCache.get(backendURL);
+  if (cached && !refresh && Date.now() - cached.at < maxAgeMs) return cached.probe;
+  const probe = (async () => {
+    let error = null;
+    for (let attempt = 1; ; attempt++) {
       try {
         const res = await bridgeFetch(
           "/api/cli/capabilities",
           { timeoutMs: listTimeoutMs() },
           backendURL,
         );
-        return { caps: (await res.json()) ?? {}, error: null };
+        return { status: "answered", caps: (await res.json()) ?? {}, error: null, attempts: attempt };
       } catch (err) {
-        // Older backends 404 this path (with a non-JSON body) — no
-        // capabilities: sync render, no version floor.
-        return { caps: {}, error: err };
+        error = err;
+        if (probeOutcome(err) === "absent") {
+          return { status: "absent", caps: {}, error: err, attempts: attempt };
+        }
+        const delay = retryAfterDelayMs(err) ?? CAPABILITY_PROBE_BACKOFF_MS[attempt - 1] ?? null;
+        if (!probeRetryable(err) || attempt >= attempts || delay === null || delay > CAPABILITY_PROBE_MAX_DELAY_MS) {
+          return { status: "unknown", caps: null, error: err, attempts: attempt };
+        }
+        await wait(delay);
       }
-    })();
-    backendCapabilitiesCache.set(backendURL, probe);
-  }
+    }
+  })();
+  const entry = { probe, at: Date.now() };
+  backendCapabilitiesCache.set(backendURL, entry);
+  probe.then(
+    (result) => {
+      // Drop an unknown, but only this one: a fresher probe may have replaced it.
+      if (result.status === "unknown" && backendCapabilitiesCache.get(backendURL) === entry) {
+        backendCapabilitiesCache.delete(backendURL);
+      }
+    },
+    () => {},
+  );
   return probe;
 }
 
+export function refreshBackendCapabilities(backendURL) {
+  return backendCapabilitiesResult(backendURL, { refresh: true });
+}
+
+// The error every capability reader raises for an `unknown` probe: typed,
+// retryable, and carrying the real cause — the status, headers (Retry-After)
+// and message of the request that failed — so a caller's retry ladder treats
+// it like the transport failure it is. A dead session keeps its own error:
+// "reconnect from the add-in" is the remediation, not "retry".
+export function capabilityUnknownError(backendURL, probe) {
+  const cause = probe?.error;
+  if (isSessionInvalidError(cause)) return cause;
+  if (cause?.code === "cli_update_required") return cause;
+  const attempts = probe?.attempts ?? 1;
+  const err = new Error(
+    `this slidemind add-in's capabilities could not be read` +
+      `${envPhrase(deriveEnvLabel(backendURL), "on")}` +
+      `${cause?.message ? ` (${cause.message})` : ""}` +
+      `${attempts > 1 ? ` after ${attempts} attempts` : ""}. ` +
+      "Nothing was decided from it: a capability that could not be discovered is neither present nor " +
+      "absent. Retry once the backend answers.",
+  );
+  err.code = "capability_unknown";
+  err.retryable = true;
+  err.cause = cause ?? null;
+  err.attempts = attempts;
+  if (cause?.status) err.status = cause.status;
+  if (cause?.headers) err.headers = cause.headers;
+  const retryAfter = retryAfterDelayMs(cause);
+  if (retryAfter !== null) err.retryAfterMs = retryAfter;
+  return err;
+}
+
+// The shared-record protocol a backend speaks (contracts.md §6), as a verdict
+// the sync queue can act on without re-deriving it:
+//   supported    `sharedRecords:{protocolVersion:1,kinds:[…]}` names `kind`, or
+//                is `["*"]` (any kind: the name is the client's namespace);
+//                no `kind` yet — a destination without a record — any kind will do
+//   unsupported  the backend answered and does not advertise it (older add-in:
+//                the probe 404s; or it lists other kinds)
+//   unknown      the probe FAILED for another reason (revoked session, relay
+//                down) — keep local data, block automated remote mutation;
+//                failure to discover permissions is not permission to write.
+// `sharepointPublish` (deployment write policy) rides along as a separate
+// condition; it is never folded into `status`.
+export async function sharedRecordsSupport(
+  backendURL,
+  { kind = null, protocolVersion = 1, refresh = false } = {},
+) {
+  const { status: probe, caps, error } = await backendCapabilitiesResult(backendURL, { refresh });
+  const sr = caps?.sharedRecords;
+  const advertised =
+    sr && typeof sr === "object" && sr.protocolVersion === protocolVersion &&
+    Array.isArray(sr.kinds) && (sr.kinds.includes("*") || (kind ? sr.kinds.includes(kind) : sr.kinds.length > 0));
+  let status = "unsupported";
+  if (advertised) status = "supported";
+  else if (probe === "unknown") status = "unknown";
+  return {
+    status,
+    code: status === "unknown" ? "capability_unknown" : null,
+    sharedRecords: sr && typeof sr === "object" ? sr : null,
+    sharepointPublish: caps?.sharepointPublish === true,
+    error,
+  };
+}
+
+// The capabilities a backend advertises — `{}` for an add-in that predates the
+// route — or a thrown `capability_unknown` when the probe got no answer. Every
+// `backendSupports*` reader and every raw `caps.<flag>` check goes through
+// here, so a probe failure can never be read as `false`: the one place an
+// absent flag and a failed request used to look the same.
 export async function backendCapabilities(backendURL) {
-  return (await backendCapabilitiesResult(backendURL)).caps;
+  const probe = await backendCapabilitiesResult(backendURL);
+  if (probe.status === "unknown") throw capabilityUnknownError(backendURL, probe);
+  return probe.caps;
+}
+
+// ---------------------------------------------------------------------------
+// The edit-safeguard contract (openspec `safeguard-slide-editing`, task 8.3)
+// ---------------------------------------------------------------------------
+//
+// Every OTHER capability on this page is an OPTIONAL feature: absent, the CLI
+// falls back (the pane relay instead of the pane-free engine routes) and keeps
+// working. The edit safeguards are the opposite kind of thing. They are what
+// stops an edit from silently dropping the element it was not asked to touch,
+// so when an operation depends on one, an add-in that does not enforce it is a
+// REFUSAL, never a fallback. The rule the whole change turns on applies here
+// too: `unknown` is not `passed`, and a check that is absent is not a check
+// that was satisfied.
+//
+// Two numbers are negotiated, and they are the ones the records already carry —
+// no fourth version is minted here:
+//   `records`  EDIT_OPERATION_VERSION / SLIDE_PRESERVATION_VERSION (one line:
+//              the operation and preservation sidecars are written together)
+//   `verdict`  PRESERVATION_VERDICT_VERSION
+// Both must EQUAL this CLI's. A backend behind us cannot honour a record it
+// does not parse; a backend ahead of us may have changed what a field means,
+// and guessing compatibility in that direction is how a safeguard becomes
+// decorative. Neither direction is a version-FLOOR matter: `minCliVersion` is a
+// hard bar for every command and must never exceed what npm has published,
+// while this refuses exactly the operations that need the contract.
+export const EDIT_SAFEGUARD_CAP_KEY = "editSafeguards";
+
+/**
+ * The named safeguards a command can require. One vocabulary, shared with the
+ * add-in's advertisement — an operation asks for what it depends on, and the
+ * backend lists what it actually enforces.
+ *
+ *   preservation-verdict  the verdict is enforced at final delivery, so a
+ *                         render that lost a required element is refused
+ *   operation-scope       the backend honours the operation record's scope
+ *                         (targeted edit ≠ licence to rewrite the slide)
+ *   bounded-repair        repair runs inside the declared budget, or not at all
+ */
+export const EDIT_SAFEGUARDS = Object.freeze([
+  "preservation-verdict",
+  "operation-scope",
+  "bounded-repair",
+]);
+
+function contractVersions() {
+  // Imported lazily: transport.mjs is on the hot path of every command, and the
+  // record contracts pull in the whole validator graph.
+  return import("../../lib/edit-operations.mjs").then(async (ops) => ({
+    records: ops.EDIT_OPERATION_VERSION,
+    verdict: (await import("../../lib/preservation-verdict.mjs")).PRESERVATION_VERDICT_VERSION,
+  }));
+}
+
+const versionOf = (value) => (Number.isInteger(value) ? value : null);
+
+/**
+ * Does `backendURL` enforce the safeguards `need` names?
+ *
+ * Four outcomes, three statuses — the precision lives in `code` so the shape
+ * matches {@link sharedRecordsSupport}, the other versioned capability:
+ *
+ *   supported                     it advertises our contract and enforces all of `need`
+ *   unsupported/`…unsupported`    it answered, and does not (older add-in, or a
+ *                                 deployment that enforces only some of them)
+ *   unsupported/`…contract_ahead` it speaks a NEWER contract than this CLI
+ *   unsupported/`…contract_behind` it speaks an OLDER one
+ *   unknown/`…unknown`            the probe failed for any reason but a 404 —
+ *                                 a revoked session, a relay that is down.
+ *                                 Discovering nothing is not discovering that
+ *                                 the check is unnecessary.
+ *
+ * `need` defaults to EVERY safeguard: a caller that forgets to say what it
+ * depends on gets the strictest answer, not a free pass. A name this CLI does
+ * not know is refused for the same reason — the backend cannot be advertising
+ * something neither side has a definition of.
+ */
+export async function editSafeguardSupport(
+  backendURL,
+  { need = EDIT_SAFEGUARDS, refresh = false } = {},
+) {
+  const wanted = (Array.isArray(need) ? need : [need]).filter(Boolean);
+  const ours = await contractVersions();
+  const base = { contract: null, ours, enforces: [], missing: wanted, error: null };
+
+  const unknownNames = wanted.filter((n) => !EDIT_SAFEGUARDS.includes(n));
+  if (unknownNames.length > 0) {
+    return { ...base, status: "unsupported", code: "safeguards_unsupported", missing: unknownNames };
+  }
+
+  const { status: probe, caps, error } = await backendCapabilitiesResult(backendURL, { refresh });
+  if (probe === "unknown") {
+    return { ...base, status: "unknown", code: "safeguards_unknown", error };
+  }
+
+  const advertised = caps?.[EDIT_SAFEGUARD_CAP_KEY];
+  if (!advertised || typeof advertised !== "object") {
+    return { ...base, status: "unsupported", code: "safeguards_unsupported", error };
+  }
+
+  const contract = {
+    records: versionOf(advertised.records),
+    verdict: versionOf(advertised.verdict),
+  };
+  // A malformed advertisement is an add-in that does not speak this contract,
+  // not one to be met halfway.
+  if (contract.records === null || contract.verdict === null) {
+    return { ...base, status: "unsupported", code: "safeguards_unsupported", contract, error };
+  }
+  if (contract.records > ours.records || contract.verdict > ours.verdict) {
+    return { ...base, status: "unsupported", code: "safeguards_contract_ahead", contract, error };
+  }
+  if (contract.records < ours.records || contract.verdict < ours.verdict) {
+    return { ...base, status: "unsupported", code: "safeguards_contract_behind", contract, error };
+  }
+
+  const enforces = Array.isArray(advertised.enforces)
+    ? advertised.enforces.filter((n) => typeof n === "string")
+    : [];
+  const missing = wanted.filter((n) => !enforces.includes(n));
+  if (missing.length > 0) {
+    return { ...base, status: "unsupported", code: "safeguards_unsupported", contract, enforces, missing, error };
+  }
+  return { ...base, status: "supported", code: null, contract, enforces, missing: [], error };
+}
+
+function safeguardError(verdict, { need }) {
+  const names = need.join(", ");
+  const ours = `records=${verdict.ours.records} verdict=${verdict.ours.verdict}`;
+  const theirs = verdict.contract
+    ? `records=${verdict.contract.records} verdict=${verdict.contract.verdict}`
+    : "no contract at all";
+  const nothing = "Nothing was written.";
+  let message;
+  switch (verdict.code) {
+    case "safeguards_unknown":
+      message =
+        `this add-in's capabilities could not be read` +
+        `${verdict.error?.message ? ` (${verdict.error.message})` : ""}, so whether it enforces ` +
+        `${names} is unknown. ${nothing} A check that could not be discovered is not a check ` +
+        `that passed — retry once the backend answers.`;
+      break;
+    case "safeguards_contract_ahead":
+      message =
+        `this add-in speaks a NEWER edit-safeguard contract (${theirs}) than this CLI (${ours}), ` +
+        `so ${names} cannot be requested safely. ${nothing} ${updateCliInstruction()}`;
+      break;
+    case "safeguards_contract_behind":
+      message =
+        `this add-in speaks an OLDER edit-safeguard contract (${theirs}) than this CLI (${ours}), ` +
+        `so it cannot honour ${names}. ${nothing} Wait for the deployment to update the slidemind ` +
+        `add-in — the safeguard is not something to work around.`;
+      break;
+    default:
+      message =
+        `this slidemind add-in does not enforce ${verdict.missing.join(", ") || names}, which this ` +
+        `operation depends on. ${nothing} Update the slidemind add-in to a build that advertises ` +
+        `\`${EDIT_SAFEGUARD_CAP_KEY}\`, or run an operation that does not require it.`;
+  }
+  const err = new Error(message);
+  err.code = verdict.code ?? "safeguards_unsupported";
+  err.safeguards = { need, missing: verdict.missing, contract: verdict.contract, ours: verdict.ours };
+  return err;
+}
+
+/**
+ * Refuse unless `backendURL` enforces every safeguard in `need`.
+ *
+ * `refresh` defaults to TRUE: this gate runs immediately before an operation
+ * that depends on the answer, and the 60s capability cache may predate a
+ * deployment that rolled back. The same rule the remote-mutation path follows —
+ * a write re-probes, a batch read may take the cached answer.
+ */
+export async function assertEditSafeguards(
+  backendURL,
+  { need = EDIT_SAFEGUARDS, refresh = true } = {},
+) {
+  const wanted = (Array.isArray(need) ? need : [need]).filter(Boolean);
+  const verdict = await editSafeguardSupport(backendURL, { need: wanted, refresh });
+  if (verdict.status === "supported") return verdict;
+  throw safeguardError(verdict, { need: wanted });
 }
 
 export async function backendSupportsRenderJobs(backendURL) {
@@ -571,11 +908,119 @@ export async function backendSupportsBrandRoutes(backendURL) {
 // 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".
+// Whether a backend exports the native line directives (`data-connector` with
+// `data-prst`/sites, `data-sm-line`, `data-sm-line-group` — the nativeLinesV1
+// contract). The CLI writes ONLY that vocabulary, so an add-in that answered
+// without the flag is a refusal, never a fallback to older markup.
+//   supported / unsupported (answered, no flag) / unknown (probe failed, not a 404)
+export async function nativeLinesSupport(backendURL) {
+  if (!backendURL) return "unknown";
+  const { status, caps } = await backendCapabilitiesResult(backendURL, { refresh: true });
+  if (caps?.nativeLinesV1 === true) return "supported";
+  return status === "unknown" ? "unknown" : "unsupported";
+}
+
 export async function backendSupportsConceptImages(backendURL) {
   const caps = await backendCapabilities(backendURL);
   return caps?.conceptImages === true;
 }
 
+// Whether a backend extracts concept specs (a vision inventory of a mockup)
+// over `/api/cli/brands/:brandId/concept-specs`. Older add-ins omit the flag
+// and `slidemind concepts` writes PNGs only.
+export async function backendSupportsConceptSpecs(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.conceptSpecs === true;
+}
+
+// The same question as a verdict a command can print, naming WHICH add-in
+// answered: a warning that only says "this add-in" leaves a user with several
+// paired environments guessing which one lags (the 2026-10-06 proposal sim ran
+// against prod while dev already read specs).
+//   supported / unsupported (answered without the flag) / unknown (no backend
+//   to ask, or the probe failed for a reason other than a 404)
+export async function conceptSpecSupport(backendURL) {
+  if (!backendURL) return { status: "unknown", env: null, backendURL: null };
+  const probe = await backendCapabilitiesResult(backendURL);
+  let status = "unsupported";
+  if (probe.caps?.conceptSpecs === true) status = "supported";
+  else if (probe.status === "unknown") status = "unknown";
+  return { status, env: deriveEnvLabel(backendURL), backendURL };
+}
+
+// Whether a backend runs concept-spec extraction as a polled job
+// (`/api/cli/brands/:brandId/concept-spec-jobs`): no ingress timeout, an
+// 8-minute per-slide budget server-side. Older add-ins answer the sync route.
+export async function backendSupportsConceptSpecJobs(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.conceptSpecJobs === true;
+}
+
+// ---------------------------------------------------------------------------
+// The image-intent contract (openspec `preserve-image-intent-across-generation`)
+// ---------------------------------------------------------------------------
+//
+// `imageIntentV1` says the add-in understands the `imageIntent` envelope on the
+// concept, spec, render and translate routes AND returns an
+// `imageIntentValidation` verdict for it. Like the edit safeguards next door,
+// and unlike every optional capability above it, this is a REFUSAL rather than
+// a fallback: an add-in that ignores the envelope would generate and render a
+// deck whose approved original never reached a slide, and report success.
+//
+// It is required only where an envelope actually travels. A deck whose plan
+// records no image uses builds no envelope, so nothing about a legacy deck
+// changes — no probe, no gate, the same request bytes as before.
+export const IMAGE_INTENT_CAP_KEY = "imageIntentV1";
+
+const IMAGE_INTENT_NOTHING =
+  "Nothing was generated and nothing was written — the deck's plan, its registry and its imported " +
+  "sources are exactly as they were.";
+
+/**
+ * Does `backendURL` speak the image-intent contract?
+ *
+ *   supported     it advertises `imageIntentV1`
+ *   unsupported   it answered, and does not (an older add-in deployment)
+ *   unknown       the probe failed for any reason but a 404 — discovering
+ *                 nothing is not discovering that the check is unnecessary
+ */
+export async function imageIntentSupport(backendURL, { refresh = false } = {}) {
+  const { status, caps, error } = await backendCapabilitiesResult(backendURL, { refresh });
+  if (caps?.[IMAGE_INTENT_CAP_KEY] === true) {
+    return { status: "supported", code: null, error: null };
+  }
+  if (status === "unknown") {
+    return { status: "unknown", code: "image_intent_unsupported", error };
+  }
+  return { status: "unsupported", code: "image_intent_unsupported", error };
+}
+
+/**
+ * Refuse, before the request, unless `backendURL` speaks the contract.
+ *
+ * `refresh` defaults to TRUE for the same reason the safeguard gate re-probes:
+ * this runs immediately before the one operation that depends on the answer,
+ * and the 60s capability cache may predate a rolled-back deployment.
+ */
+export async function assertImageIntentSupported(backendURL, { refresh = true } = {}) {
+  const verdict = await imageIntentSupport(backendURL, { refresh });
+  if (verdict.status === "supported") return verdict;
+  const err = new Error(
+    verdict.status === "unknown"
+      ? `this slidemind add-in's capabilities could not be read` +
+        `${verdict.error?.message ? ` (${verdict.error.message})` : ""}, so whether it preserves this ` +
+        `deck's approved image uses is unknown. ${IMAGE_INTENT_NOTHING} A capability that could not be ` +
+        `discovered is not one that is present — retry once the backend answers.`
+      : `this slidemind add-in does not support image intent (\`${IMAGE_INTENT_CAP_KEY}\`), which this ` +
+        `deck's approved image uses depend on: it would drop the envelope, place no original and report ` +
+        `success. ${IMAGE_INTENT_NOTHING} Wait for the deployment to update the slidemind add-in, or ` +
+        `work in a deck whose plan records no image uses — those are unaffected.`,
+  );
+  err.code = "image_intent_unsupported";
+  err.imageIntent = { capability: IMAGE_INTENT_CAP_KEY, status: verdict.status };
+  throw err;
+}
+
 // Whether a backend generates regular images over the pane-free
 // `/api/cli/brands/:brandId/images` route (see generateImageForBrand).
 // Advertised by newer add-ins only.
@@ -623,6 +1068,18 @@ export async function backendSupportsGraphDelegated(backendURL) {
   return caps?.graphDelegated === true;
 }
 
+// Whether the deployment's POLICY allows the CLI to publish back to SharePoint
+// (`slidemind publish`). A policy flag and nothing more: it does NOT prove the
+// user's token carries AllSites.Write, that admin consent was granted, or that
+// this item is writable. Those three are found at REQUEST time — a
+// `consent_required` challenge, a 403 on the write itself — never inferred from
+// a capability literal. Gating the command on it only keeps a deployment that
+// has switched the feature off from being asked in the first place.
+export async function backendSupportsSharePointPublish(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.sharepointPublish === 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
@@ -654,9 +1111,27 @@ export async function engineGraphToken(backendURL, { signIn = true } = {}) {
   if (!token && signIn && (await ensureSignedIn(backendURL))) {
     token = await getGraphToken(backendURL);
   }
+  if (!token) assertTokenRefreshed(backendURL, "graph");
   return token;
 }
 
+// A stored sign-in whose token could not be refreshed just now is an outage to
+// retry, not a missing sign-in: nothing is sent without the token, because the
+// backend would answer `login_required` and the agent would send the user to
+// `slidemind login` for nothing (graph-auth.tokenRefreshFailure).
+function assertTokenRefreshed(backendURL, resource) {
+  const cause = tokenRefreshFailure(backendURL, resource);
+  if (!cause) return;
+  const err = new Error(
+    `the Microsoft 365 sign-in${envPhrase(deriveEnvLabel(backendURL), "for")} is intact, but its ` +
+      `${resource === "sharepoint" ? "SharePoint" : "Graph"} token could not be refreshed just now ` +
+      `(${cause}). Nothing was sent; retry the command.`,
+  );
+  err.code = "token_refresh_failed";
+  err.retryable = true;
+  throw err;
+}
+
 // 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.
@@ -667,6 +1142,7 @@ export async function engineSpToken(backendURL, { signIn = true } = {}) {
   if (!token && signIn && (await ensureSignedIn(backendURL))) {
     token = await getSharePointToken(backendURL);
   }
+  if (!token) assertTokenRefreshed(backendURL, "sharepoint");
   return token;
 }
 

package/src/bridge/client.mjs

@@ -15,6 +15,8 @@ export {
   getDesignBundleForBrandAnyBackend,
   listBrands,
   generateConceptImagesForBrand,
+  extractConceptSpecsForBrand,
+  fitCopyForBrand,
   resolveConceptBackend,
   generateImageForBrand,
   backendSupportsConvertPptx,
@@ -33,6 +35,7 @@ export {
   engineSearchAnyPane,
   engineDownload,
   engineDownloadToFile,
+  pickAssets,
 } from "./client/engine-search.mjs";
 export {
   extractSlideToFile,
@@ -79,10 +82,17 @@ export {
   isSessionInvalidError,
   backendSupportsBrandRoutes,
   backendSupportsConceptImages,
+  conceptSpecSupport,
+  nativeLinesSupport,
   backendSupportsImageGeneration,
   backendSupportsBrandsList,
   backendSupportsSourcePresentation,
   backendSupportsEngineRoutes,
   backendSupportsGraphDelegated,
+  backendSupportsSharePointPublish,
   assertCliVersionSupported,
+  EDIT_SAFEGUARDS,
+  EDIT_SAFEGUARD_CAP_KEY,
+  editSafeguardSupport,
+  assertEditSafeguards,
 } from "./client/transport.mjs";