slidemind 0.1.4 → 0.1.6

package/src/bridge/client.mjs

@@ -28,6 +28,26 @@ function listTimeoutMs() {
   );
 }
 
+// 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".
+function engineTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+    90000
+  );
+}
+
+function readinessTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_READY_TIMEOUT_MS || "20000", 10) ||
+    20000
+  );
+}
+
 const NOT_PAIRED_MESSAGE =
   'slidemind is not paired. In the slidemind add-in, click "Connect CLI" ' +
   "and run the shown `slidemind pair …` command, then retry.";
@@ -238,6 +258,69 @@ async function listPresentationsForBackend(backendURL) {
   });
 }
 
+async function readinessForBackend(backendURL) {
+  const env = deriveEnvLabel(backendURL);
+  try {
+    const res = await bridgeFetch(
+      "/api/cli/readiness",
+      { timeoutMs: listTimeoutMs() },
+      backendURL,
+    );
+    const data = (await res.json()) ?? {};
+    const presentations = Array.isArray(data.presentations)
+      ? data.presentations.map((p) => ({ ...p, backendURL, env }))
+      : [];
+    return {
+      env,
+      backendURL,
+      ok: true,
+      readinessV1: data.readinessV1 === true,
+      capabilities: data.capabilities ?? null,
+      presentations,
+      summary: data.summary ?? null,
+    };
+  } catch (err) {
+    if (err?.status !== 404) throw err;
+    // Older add-ins do not serve /readiness. Fall back to the legacy
+    // presentations route and mark the result as a compatibility response.
+    const presentations = await listPresentationsForBackend(backendURL);
+    return {
+      env,
+      backendURL,
+      ok: true,
+      readinessV1: false,
+      capabilities: null,
+      presentations,
+      summary: null,
+    };
+  }
+}
+
+export async function connectionStatus() {
+  const sessions = sessionsInScope();
+  const settled = await Promise.allSettled(
+    sessions.map((s) => readinessForBackend(s.backendURL)),
+  );
+  const backends = settled.map((r, i) => {
+    const backendURL = sessions[i].backendURL;
+    const env = deriveEnvLabel(backendURL);
+    if (r.status === "fulfilled") return r.value;
+    return {
+      env,
+      backendURL,
+      ok: false,
+      error: r.reason?.message ? r.reason.message : String(r.reason),
+      presentations: [],
+    };
+  });
+  return {
+    paired: sessions.length > 0,
+    backendCount: sessions.length,
+    backends,
+    presentations: backends.flatMap((b) => b.presentations ?? []),
+  };
+}
+
 // Fan out across every backend in scope, concurrently. Never rejects: each
 // backend's outcome is partitioned into merged presentations vs. a failure
 // record, so one unreachable environment can't hide the others.
@@ -339,6 +422,93 @@ export async function requireHost() {
   );
 }
 
+function hasReadinessFields(p) {
+  return (
+    p &&
+    (typeof p.connectionState === "string" ||
+      typeof p.designState === "string" ||
+      (p.capabilities && typeof p.capabilities === "object"))
+  );
+}
+
+export function isRenderReadyPresentation(p) {
+  if (!p) return false;
+  if (!hasReadinessFields(p)) return true;
+  if (p.capabilities?.render === true) return true;
+  if (p.designState === "ready" && p.capabilities?.render !== false) return true;
+  return false;
+}
+
+export function isPaneReadyPresentation(p) {
+  if (!p) return false;
+  if (!hasReadinessFields(p)) return p.connected !== false && !p.suspendedAt;
+  if (p.capabilities?.paneOps === true) return true;
+  return (
+    p.connectionState === "connected" &&
+    p.connected !== false &&
+    !p.suspendedAt &&
+    p.connectionState !== "stale"
+  );
+}
+
+async function waitForReadyPresentation(predicate, { timeoutMs = null } = {}) {
+  const waitMs = timeoutMs ?? readinessTimeoutMs();
+  const pollMs = envInt("SLIDEMIND_BRIDGE_READY_POLL_MS", 1500);
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const { presentations, unreachable } = await listOpenPresentationsDetailed();
+    if (presentations.some(predicate)) return presentations;
+    // Do not wait when nothing is registered at all. Waiting helps only for an
+    // already-open pane that is still hydrating brand/readiness metadata.
+    if (presentations.length === 0 || Date.now() >= deadline) {
+      return { presentations, unreachable, timedOut: presentations.length > 0 };
+    }
+    await sleep(pollMs);
+  }
+}
+
+export async function requireRenderHost({ timeoutMs = null } = {}) {
+  const first = await listOpenPresentationsDetailed();
+  if (first.presentations.some(isRenderReadyPresentation)) {
+    return first.presentations;
+  }
+  if (first.presentations.length > 0) {
+    const waited = await waitForReadyPresentation(isRenderReadyPresentation, {
+      timeoutMs,
+    });
+    if (Array.isArray(waited)) return waited;
+    if (waited.presentations.some(isRenderReadyPresentation)) {
+      return waited.presentations;
+    }
+    throw new Error(
+      "PowerPoint is registered with the slidemind add-in, but no window is render-ready yet. " +
+        "Wait for the corporate design to finish matching, or pick/create a corporate design in the add-in, then retry.",
+    );
+  }
+  return requireHost();
+}
+
+export async function requirePaneHost({ timeoutMs = null } = {}) {
+  const first = await listOpenPresentationsDetailed();
+  if (first.presentations.some(isPaneReadyPresentation)) {
+    return first.presentations;
+  }
+  if (first.presentations.length > 0) {
+    const waited = await waitForReadyPresentation(isPaneReadyPresentation, {
+      timeoutMs,
+    });
+    if (Array.isArray(waited)) return waited;
+    if (waited.presentations.some(isPaneReadyPresentation)) {
+      return waited.presentations;
+    }
+    throw new Error(
+      "PowerPoint is registered with the slidemind add-in, but the task pane is not ready for pane operations. " +
+        "Bring PowerPoint forward and click or reopen the slidemind pane, then retry.",
+    );
+  }
+  return requireHost();
+}
+
 // Tie-break a multi-backend presId collision without bothering the user when
 // only one candidate can actually serve the deck:
 //   (a) exactly one CONNECTED pane whose active CD matches the deck's bundle
@@ -348,7 +518,7 @@ export async function requireHost() {
 //       e.g. a local dev backend connected without a CD next to prod with one.
 // Returns the winning entry or null when genuinely ambiguous.
 function tieBreakMatches(matches, preferBrandId) {
-  const live = matches.filter((m) => m.connected !== false && !m.suspendedAt);
+  const live = matches.filter(isPaneReadyPresentation);
   if (preferBrandId) {
     const want = live.filter((m) => m.brandId === preferBrandId);
     if (want.length === 1) return want[0];
@@ -420,7 +590,7 @@ export async function waitForPaneReady(
       /* transient list failure — poll again until the deadline */
     }
     const connected = list.filter(
-      (p) => p.connected !== false && !p.suspendedAt,
+      (p) => isPaneReadyPresentation(p),
     );
     const same = connected.find((p) => p.presId === presId);
     if (same) return same;
@@ -483,7 +653,9 @@ async function listEnginesForBackend(backendURL, { type = null, subtype = null }
     const qs = params.toString();
     const res = await bridgeFetch(
       `/api/cli/engines${qs ? `?${qs}` : ""}`,
-      { timeoutMs: listTimeoutMs() },
+      // Pane-relayed on the add-in side — needs the engine budget, not the 8s
+      // list timeout (which bailed before the pane could ever answer).
+      { timeoutMs: engineTimeoutMs() },
       backendURL,
     );
     const data = await res.json();
@@ -837,6 +1009,11 @@ export async function engineSearch({
   intent = null,
   top = null,
   backendURL = 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 (!presId) throw new Error("engineSearch: presId is required");
   if (!engineId) throw new Error("engineSearch: engineId is required");
@@ -846,24 +1023,96 @@ export async function engineSearch({
   if (subtype) body.subtype = subtype;
   if (intent) body.intent = intent;
   if (typeof top === "number") body.top = top;
-  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+  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),
-        // Engine ops relay through the pane: the server may wait up to ~25s for
-        // a suspended pane to reconnect, then up to 60s for the pane's ack —
-        // stay above that sum so typed errors win over client timeouts.
-        timeoutMs:
-          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
-          90000,
+        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,
+  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,
+        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
@@ -1016,6 +1265,46 @@ export async function viewSlide({
   });
 }
 
+// Read the CURRENT content of an open presentation (the "pull content" path
+// behind `slidemind read` / slidemind_read_presentation). `mode` selects the
+// depth: "summary" returns a per-slide outline (index, layout, title, subtitle);
+// "raw" (default) returns each slide's full plain text — NOT the add-in's editing
+// markup. Unlike engine ops, content is WINDOW-BOUND: it reads THAT presentation,
+// so we resolve the origin backend from the presId and relay through that
+// window's pane. It's an idempotent read, so engineOpWithPaneWait's single
+// pane_suspended client-wait + retry against the live entry is safe (like viewSlide).
+export async function getPresentationContent({
+  presId,
+  mode = "raw",
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("getPresentationContent: presId is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { mode: mode === "summary" ? "summary" : "raw" };
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/content`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        timeoutMs: engineTimeoutMs(),
+      },
+      b,
+    );
+    return res.json(); // { ok, mode, slideCount, slides }
+  });
+}
+
+function ensurePaneAckOk(data, operation) {
+  if (!data || data.ok !== false) return data ?? {};
+  const detail = data.error || `${operation} failed`;
+  const err = new Error(detail);
+  err.code = data.code || `${operation}_failed`;
+  err.body = data;
+  throw err;
+}
+
 export async function insertSlides({
   presId,
   base64,
@@ -1040,7 +1329,7 @@ export async function insertSlides({
     },
     be,
   );
-  return res.json().catch(() => ({}));
+  return ensurePaneAckOk(await res.json().catch(() => ({})), "insert");
 }
 
 export async function replaceSlides({
@@ -1064,7 +1353,7 @@ export async function replaceSlides({
     },
     be,
   );
-  return res.json().catch(() => ({}));
+  return ensurePaneAckOk(await res.json().catch(() => ({})), "replace");
 }
 
 // Pick a target presentation given the (possibly multi-backend) registry and an
@@ -1146,7 +1435,9 @@ export function pickAnyPresentationEntry(registry, explicitPresId, opts = {}) {
     );
   }
   return (
-    registry.find((p) => p.connected !== false && !p.suspendedAt) ?? registry[0]
+    registry.find(isPaneReadyPresentation) ??
+    registry.find((p) => p.connected !== false && !p.suspendedAt) ??
+    registry[0]
   );
 }
 

package/src/installers/codex.mjs

@@ -23,6 +23,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import {
   expandHome,
   installDir,
@@ -40,7 +41,10 @@ const TOML_MARK_BEGIN = "# slidemind:begin";
 const TOML_MARK_END = "# slidemind:end";
 
 function codexRoot() {
-  return expandHome("~/.codex");
+  // Codex reads everything (skills, AGENTS.md, config.toml) from $CODEX_HOME
+  // when set, defaulting to ~/.codex — mirror that so our artifacts land where
+  // it actually looks.
+  return process.env.CODEX_HOME || expandHome("~/.codex");
 }
 
 function promptsDir() {
@@ -81,38 +85,102 @@ function configTomlFile() {
   return path.join(codexRoot(), "config.toml");
 }
 
-function writeMcpServerBlock(packageRoot) {
+// Register the slidemind MCP server. Prefer Codex's own `codex mcp add`, which
+// is TOML-aware and idempotent: it sets `[mcp_servers.slidemind]` by key, so a
+// re-install/upgrade — or a pre-existing entry added manually or by an earlier
+// `codex mcp add` — is REPLACED in place rather than duplicated, while unrelated
+// tables, top-level keys, and comments survive.
+//
+// The previous hand-rolled writer wrapped its block in `# slidemind:begin/end`
+// comment markers and deduped by them; a `[mcp_servers.slidemind]` table that
+// lacked those markers (manual edit, or a Codex-side config rewrite that dropped
+// the comments) was invisible to it, so it appended a SECOND table — a
+// duplicate-key TOML that broke config.toml. Delegating to Codex removes that
+// whole failure mode.
+//
+// `codex mcp` landed around Codex 0.128. If the binary is missing or too old
+// (spawn error / non-zero exit) we fall back to a minimal, non-destructive
+// writer that never duplicates.
+export function registerMcpServer(packageRoot) {
   const mcpServer = path.join(packageRoot, "src", "mcp", "server.mjs");
-  const block =
-    `${TOML_MARK_BEGIN}\n` +
-    `[mcp_servers.slidemind]\n` +
+  const viaCli = spawnSync(
+    "codex",
+    ["mcp", "add", NAMESPACE, "--", "node", mcpServer],
+    { stdio: "ignore", shell: process.platform === "win32" },
+  );
+  if (!viaCli.error && viaCli.status === 0) {
+    sweepLegacyMarkers();
+    return "registered via codex mcp";
+  }
+  return fallbackWriteMcpServerBlock(mcpServer);
+}
+
+export function unregisterMcpServer() {
+  const viaCli = spawnSync(
+    "codex",
+    ["mcp", "remove", NAMESPACE],
+    { stdio: "ignore", shell: process.platform === "win32" },
+  );
+  if (!viaCli.error && viaCli.status === 0) return "unregistered via codex mcp";
+  return fallbackClearMcpServerBlock();
+}
+
+function mcpServerBlock(mcpServer) {
+  return (
+    `[mcp_servers.${NAMESPACE}]\n` +
     `command = "node"\n` +
-    `args = ["${mcpServer.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]\n` +
-    `${TOML_MARK_END}\n`;
+    `args = ["${mcpServer.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]\n`
+  );
+}
 
+// Fallback for when `codex mcp` is unavailable. Minimal and non-destructive:
+// never append a second entry — if a `[mcp_servers.slidemind]` already exists
+// (ours or the user's) we leave it untouched; otherwise we append our block.
+export function fallbackWriteMcpServerBlock(mcpServer) {
   const file = configTomlFile();
-  let existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
-  const re = new RegExp(
-    `${TOML_MARK_BEGIN}[\\s\\S]*?${TOML_MARK_END}\\n?`,
-    "g",
-  );
-  if (re.test(existing)) {
-    existing = existing.replace(re, "");
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  if (existing.includes(`[mcp_servers.${NAMESPACE}]`)) {
+    return "already registered (left as-is)";
   }
-  const sep = existing.length && !existing.endsWith("\n") ? "\n\n" : existing.length ? "\n" : "";
-  fs.writeFileSync(file, existing + sep + block);
+  const sep =
+    existing.length && !existing.endsWith("\n") ? "\n\n" : existing.length ? "\n" : "";
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, existing + sep + mcpServerBlock(mcpServer));
+  return "registered (fallback)";
 }
 
-function clearMcpServerBlock() {
+// Fallback uninstall: strip a legacy marker-wrapped block if one is present;
+// otherwise point the user at `codex mcp remove` (we won't guess at the bounds
+// of a marker-less table without Codex's TOML parser).
+export function fallbackClearMcpServerBlock() {
+  const file = configTomlFile();
+  if (!fs.existsSync(file)) return "unregistered";
+  const existing = fs.readFileSync(file, "utf8");
+  const re = new RegExp(`${TOML_MARK_BEGIN}[\\s\\S]*?${TOML_MARK_END}\\n?`, "g");
+  const stripped = existing.replace(re, "");
+  if (stripped !== existing) {
+    fs.writeFileSync(file, stripped);
+    return "unregistered (fallback)";
+  }
+  return "run `codex mcp remove slidemind` to remove the entry";
+}
+
+// After Codex rewrites the `[mcp_servers.slidemind]` table, an upgrader's old
+// slidemind block can leave orphan `# slidemind:begin` / `# slidemind:end`
+// comment lines behind. Drop just those literal lines (valid TOML either way —
+// purely cosmetic).
+function sweepLegacyMarkers() {
   const file = configTomlFile();
   if (!fs.existsSync(file)) return;
-  let existing = fs.readFileSync(file, "utf8");
-  const re = new RegExp(
-    `${TOML_MARK_BEGIN}[\\s\\S]*?${TOML_MARK_END}\\n?`,
-    "g",
-  );
-  existing = existing.replace(re, "");
-  fs.writeFileSync(file, existing);
+  const before = fs.readFileSync(file, "utf8");
+  const after = before
+    .split("\n")
+    .filter(
+      (line) =>
+        line.trim() !== TOML_MARK_BEGIN && line.trim() !== TOML_MARK_END,
+    )
+    .join("\n");
+  if (after !== before) fs.writeFileSync(file, after);
 }
 
 function writeAgentsBlock() {
@@ -194,8 +262,8 @@ export async function install({ packageRoot, flags }) {
 
   // Register the slidemind MCP server so agents can list/push into open
   // PowerPoint windows via slidemind_list_open_presentations / slidemind_push_deck.
-  writeMcpServerBlock(packageRoot);
-  ui.step({ status: "ok", label: "mcp server", value: configTomlFile() });
+  const mcpNote = registerMcpServer(packageRoot);
+  ui.step({ status: "ok", label: "mcp server", value: mcpNote });
 
   ui.note("restart Codex to pick up the skill + MCP server");
 }
@@ -224,6 +292,6 @@ export async function uninstall() {
   }
   clearAgentsBlock();
   ui.step({ status: "remove", label: "AGENTS.md", value: agentsFile() });
-  clearMcpServerBlock();
-  ui.step({ status: "info", label: "mcp server", value: "unregistered" });
+  const mcpNote = unregisterMcpServer();
+  ui.step({ status: "info", label: "mcp server", value: mcpNote });
 }