@okostream/mcp 0.12.12 → 0.12.13

package/dist/server.js

@@ -116291,7 +116291,7 @@ function sanitizeScopes(scopes) {
 }
 
 // build/version.js
-var OKO_MCP_VERSION = "0.12.12";
+var OKO_MCP_VERSION = "0.12.13";
 
 // build/auth.js
 var state = null;
@@ -116702,7 +116702,16 @@ var MAX_CARD_BUTTON_LABEL_LENGTH = 80;
 var MAX_CARD_BUTTON_URL_LENGTH = 1e3;
 var MAX_SOURCE_IMAGE_BYTES = 15 * 1024 * 1024;
 var REMOTE_IMAGE_TIMEOUT_MS = 15e3;
+var REMOTE_IMAGE_TOTAL_TIMEOUT_MS = 4e4;
 var REMOTE_IMAGE_MAX_REDIRECTS = 3;
+function remoteImageHopBudget(deadlineAt, now, perHopMs) {
+  const left = deadlineAt - now;
+  if (left <= 0)
+    return { kind: "exhausted" };
+  if (left < perHopMs)
+    return { kind: "budget", ms: left, capped: true };
+  return { kind: "budget", ms: perHopMs, capped: false };
+}
 var ALLOWED_REMOTE_IMAGE_TYPES = /* @__PURE__ */ new Set(["image/jpeg", "image/jpg", "image/png", "image/webp", "image/gif", "image/avif"]);
 function storagePathFromDownloadUrl(downloadUrl) {
   if (!downloadUrl)
@@ -116816,7 +116825,7 @@ function shareLinkHint(url) {
   }
   return " Use a direct link to the image file (right-click the image \u2192 copy image address), or download the file and pass source.path.";
 }
-async function readRemoteImage(rawUrl, redirects = 0, notes = []) {
+async function readRemoteImage(rawUrl, redirects = 0, notes = [], deadlineAt = Date.now() + REMOTE_IMAGE_TOTAL_TIMEOUT_MS) {
   if (redirects > REMOTE_IMAGE_MAX_REDIRECTS) {
     throw new Error("Image URL has too many redirects.");
   }
@@ -116827,21 +116836,28 @@ async function readRemoteImage(rawUrl, redirects = 0, notes = []) {
   }
   let lastConnectError = null;
   for (const candidate of pinned.addresses) {
-    const attempt = await readRemoteImageFrom(url, rawUrl, candidate, redirects);
+    const attempt = await readRemoteImageFrom(url, rawUrl, candidate, redirects, deadlineAt);
     if ("buffer" in attempt)
       return attempt.buffer;
     if ("redirectTo" in attempt)
-      return readRemoteImage(attempt.redirectTo, redirects + 1, notes);
+      return readRemoteImage(attempt.redirectTo, redirects + 1, notes, deadlineAt);
     lastConnectError = attempt.connectError;
   }
   throw new Error(`Image URL host ${url.hostname} could not be reached at any of its addresses (${pinned.addresses.map((item) => item.address).join(", ")}): ${lastConnectError?.message ?? "connection failed"}.`);
 }
-async function readRemoteImageFrom(url, rawUrl, candidate, redirects) {
+function totalBudgetMessage() {
+  return `Image URL did not finish loading within ${REMOTE_IMAGE_TOTAL_TIMEOUT_MS / 1e3} seconds, including redirects.`;
+}
+async function readRemoteImageFrom(url, rawUrl, candidate, redirects, deadlineAt) {
+  const budget = remoteImageHopBudget(deadlineAt, Date.now(), REMOTE_IMAGE_TIMEOUT_MS);
+  if (budget.kind === "exhausted") {
+    throw new Error(totalBudgetMessage());
+  }
   const dispatcher = new import_undici.Agent({
     connect: { lookup: pinnedLookup(candidate.address, candidate.family) }
   });
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), REMOTE_IMAGE_TIMEOUT_MS);
+  const timeout = setTimeout(() => controller.abort(), budget.ms);
   try {
     let response;
     try {
@@ -116853,7 +116869,7 @@ async function readRemoteImageFrom(url, rawUrl, candidate, redirects) {
       });
     } catch (err) {
       if (err instanceof Error && err.name === "AbortError") {
-        throw new Error("Image URL fetch timed out.");
+        throw new Error(budget.capped ? totalBudgetMessage() : `Image URL did not respond within ${REMOTE_IMAGE_TIMEOUT_MS / 1e3} seconds.`);
       }
       return { connectError: err instanceof Error ? err : new Error(String(err)) };
     }
@@ -118047,6 +118063,27 @@ function markdownMetric(label, value, suffix = "") {
   const metric = value === null || value === void 0 || value === "" ? "n/a" : String(value);
   return `- ${label}: ${metric}${suffix}`;
 }
+function reportQualityCaveats(dataQuality) {
+  if (!dataQuality || typeof dataQuality !== "object" || Array.isArray(dataQuality))
+    return [];
+  const marks = dataQuality;
+  const caveats = [];
+  if (marks.baselineSource === "none")
+    caveats.push("baselineMissing");
+  if (marks.startedAtSource === "end_time")
+    caveats.push("startTimeUnknown");
+  if (marks.watchTime === "unavailable")
+    caveats.push("watchTimeUnmeasured");
+  if (marks.watchTime === "unknown_duration")
+    caveats.push("watchTimeUncapped");
+  return caveats;
+}
+var REPORT_QUALITY_CAVEAT_TEXT = {
+  baselineMissing: "The session baseline was not saved: every figure below is counted from zero and includes everything the event accumulated before this broadcast.",
+  startTimeUnknown: "The broadcast start time was not saved: the report is stamped with the moment it ended and its duration reads zero.",
+  watchTimeUnmeasured: "Watch time was not measured: the engagement snapshot could not be read.",
+  watchTimeUncapped: "Watch time is not capped by the broadcast length \u2014 it is unknown, so nothing vouches for the total, average and median times."
+};
 function sessionReportMarkdown({ eventId, event, sessionId, session }) {
   const lines = [
     `# OKO session report`,
@@ -118076,6 +118113,12 @@ function sessionReportMarkdown({ eventId, event, sessionId, session }) {
     markdownMetric("CTA clicks", session.ctaClicks),
     markdownMetric("Cards clicks", session.cardsClicks)
   ];
+  const caveats = reportQualityCaveats(session.dataQuality);
+  if (caveats.length > 0) {
+    lines.push("", "## What this report did not measure");
+    for (const caveat of caveats)
+      lines.push(`- ${REPORT_QUALITY_CAVEAT_TEXT[caveat]}`);
+  }
   return lines.join("\n");
 }
 var TELEGRAM_COPYABLE_KEYS = ["enabled", "channelIds", "autoReminder"];
@@ -118434,10 +118477,32 @@ async function addEventWithRtdbMirror(eventData) {
   try {
     const ensureRuntime = httpsCallable(functions, "ensureEventRuntime");
     await ensureRuntime({ eventId: eventRef.id });
+    return { ref: eventRef, runtime: { status: "ready" } };
   } catch (error3) {
-    console.error(`[OKO MCP] RTDB mirror deferred to onEventCreated for event ${eventRef.id}:`, error3);
+    const rawCode = error3?.code;
+    const code = typeof rawCode === "string" ? rawCode : "unknown";
+    console.error(`[OKO MCP] ensureEventRuntime failed for event ${eventRef.id}:`, error3);
+    return {
+      ref: eventRef,
+      runtime: {
+        status: "failed",
+        code,
+        message: error3 instanceof Error ? error3.message : String(error3)
+      }
+    };
   }
-  return eventRef;
+}
+function eventRuntimeHint(runtime) {
+  if (runtime.status === "ready")
+    return [];
+  if (runtime.code === "functions/not-found") {
+    return [
+      "The event document was created, but the server reports the event as already gone and could not confirm its runtime. Do not hand the links out: re-read it with oko_get_event and tell the organizer the creation did not complete."
+    ];
+  }
+  return [
+    `The event was created, but the server could not confirm its runtime mirrors (${runtime.code}). Chat and access rules may lag behind: run oko_validate_event_setup before relying on the links, and say so to the organizer.`
+  ];
 }
 
 // build/tools/setupValidation.js
@@ -118787,7 +118852,7 @@ function registerEventTools(server2) {
     const workspaceId = args.workspaceId ?? uid;
     await assertCanCreateInWorkspace(uid, workspaceId);
     const video = normalizeVideo(args.videoUrl);
-    const docRef = await addEventWithRtdbMirror(buildCreateWebinarDocument({
+    const created = await addEventWithRtdbMirror(buildCreateWebinarDocument({
       uid,
       workspaceId,
       title: args.title,
@@ -118798,11 +118863,14 @@ function registerEventTools(server2) {
       chatEnabled: args.chatEnabled,
       createdAt: serverTimestamp2()
     }));
+    const docRef = created.ref;
     return textResult({
       id: docRef.id,
       ...eventLinks(docRef.id),
       workspaceId,
+      runtime: created.runtime,
       hints: [
+        ...eventRuntimeHint(created.runtime),
         "The page is live at publicUrl immediately; OKO has no draft state.",
         "Next: oko_configure_blocks for chat/CTA/placeholder, oko_configure_cards for cards, image uploads, then oko_validate_event_setup.",
         'The video placeholder (countdown/cover) is only shown to viewers after oko_set_block_visibility with block "placeholder" and visible true; enabling it in oko_configure_blocks alone keeps it hidden.'
@@ -119317,7 +119385,6 @@ var MCP_AUDIT_TARGET_KEYS = /* @__PURE__ */ new Set([
   "postId",
   "messageId",
   "leadId",
-  "participantUid",
   "uid",
   "channelId",
   "cardId",
@@ -119733,7 +119800,7 @@ function registerLifecycleTools(server2) {
     await assertCanCreateInWorkspace(uid, workspaceId);
     const sourceHasTelegram = !!source.telegram && typeof source.telegram === "object";
     const mayCopyTelegram = sourceHasTelegram && currentScopes().includes("telegram:write") && await eventGrantsMode(eventId, uid, "notify");
-    const newRef = await addEventWithRtdbMirror({
+    const duplicated = await addEventWithRtdbMirror({
       ownerId: uid,
       workspaceId,
       createdAt: serverTimestamp2(),
@@ -119750,14 +119817,17 @@ function registerLifecycleTools(server2) {
       // (review 02.09, R3b-5).
       ...mayCopyTelegram ? { telegram: copyableTelegram(source.telegram) } : {}
     });
+    const newRef = duplicated.ref;
     return textResult({
       id: newRef.id,
       sourceEventId: eventId,
       workspaceId,
+      runtime: duplicated.runtime,
       ...eventLinks(newRef.id),
       liveStateNotCopied: ["chatMode", "placeholderVisible", "liveBadge", "block visibility overrides"],
       telegramCopied: mayCopyTelegram,
       hints: [
+        ...eventRuntimeHint(duplicated.runtime),
         ...sourceHasTelegram && !mayCopyTelegram ? ["Telegram config was NOT copied: this key needs telegram:write and the notification permission on the source event. The copy starts with Telegram off; ask the event owner to grant the permission, then configure channels on the copy."] : [],
         "Live state was not copied: chat mode is public and the placeholder is hidden on the copy. If the source had chat off or the placeholder shown, set them again with oko_set_chat_mode and oko_set_block_visibility on the new event.",
         "The copy is live at publicUrl immediately; edit title, eventDate, and video with oko_update_event, then run oko_validate_event_setup."
@@ -120132,6 +120202,63 @@ function summarizeSessionRepair(input) {
 }
 
 // build/tools/sessions.js
+function sessionBaselineFromRead(read) {
+  if (!read.ok)
+    return "unread";
+  return read.exists ? "present" : "absent";
+}
+function sessionRepairAction(input) {
+  if (input.liveSessionBaseline === "unread")
+    return "unknown";
+  return input.liveSessionBaseline === "present" ? "end" : "release";
+}
+function sessionRepairRefusal(action) {
+  if (action === "end") {
+    return "This session still has working state in RTDB, so clearing its pointers would leave a running broadcast without a report. End it instead: oko_end_session saves the report and clears the pointers itself.";
+  }
+  if (action === "unknown") {
+    return "Could not read the session working state (events/{eventId}/sessions/{sessionId}/baseline), so it is unknown whether the session is still running. Nothing was changed; retry, or end the session with oko_end_session.";
+  }
+  return null;
+}
+async function assertSessionHasNothingToEnd(eventId, sessionId) {
+  if (!sessionId)
+    return;
+  let read;
+  try {
+    const snap = await get(ref(rtdb, `events/${eventId}/sessions/${sessionId}/baseline`));
+    read = { ok: true, exists: snap.exists() };
+  } catch {
+    read = { ok: false };
+  }
+  const refusal = sessionRepairRefusal(sessionRepairAction({ liveSessionBaseline: sessionBaselineFromRead(read) }));
+  if (refusal)
+    throw new Error(refusal);
+}
+async function attemptCleanup(path, run) {
+  try {
+    await run();
+    return { path, status: "fulfilled" };
+  } catch (error3) {
+    return { path, status: "rejected", error: error3 instanceof Error ? error3.message : String(error3) };
+  }
+}
+async function releaseSessionPointers(eventId, sessionId) {
+  const rtdbUpdates = {
+    [`events/${eventId}/ctrl/activeSessionId`]: null
+  };
+  if (sessionId)
+    rtdbUpdates[`activeSessions/${sessionId}`] = null;
+  const rtdbPaths = sessionId ? ["ctrl/activeSessionId", `activeSessions/${sessionId}`] : ["ctrl/activeSessionId"];
+  const rtdbOutcome = await attemptCleanup("rtdb", () => update(ref(rtdb), rtdbUpdates));
+  const attempts = rtdbPaths.map((path) => ({ ...rtdbOutcome, path }));
+  if (rtdbOutcome.status === "rejected") {
+    attempts.push({ path: "events.activeAnalyticsSessionId", status: "rejected", error: "skipped: RTDB pointers were not released" });
+    return attempts;
+  }
+  attempts.push(await attemptCleanup("events.activeAnalyticsSessionId", () => updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() })));
+  return attempts;
+}
 function registerSessionTools(server2) {
   server2.registerTool("oko_start_session", {
     title: "Start analytics session",
@@ -120193,7 +120320,11 @@ function registerSessionTools(server2) {
       ],
       returns: "eventId, cleared sessionId if found, and cleaned paths.",
       examples: ["Use when oko_end_session says the baseline is missing or dashboard shows a stuck/orphan session."],
-      notes: ["This does not stop the video stream; OKO Start/End controls analytics sessions only."]
+      notes: [
+        "This does not stop the video stream; OKO Start/End controls analytics sessions only.",
+        "Refuses when the session still has working state in RTDB: clearing the pointers would leave a running broadcast without a report. Use oko_end_session for that case.",
+        "Both RTDB pointers are cleared in one atomic update, and the Firestore pointer only after it succeeds: the repair leaves either all pointers cleared or none."
+      ]
     }),
     inputSchema: {
       eventId: eventIdField,
@@ -120208,41 +120339,11 @@ function registerSessionTools(server2) {
     const ctrlSnap = await get(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`));
     const sessionId = safeString(event.activeAnalyticsSessionId) || safeString(ctrlSnap.val());
     requireConfirm(confirm, "oko_fix_orphan_session", { eventId, sessionId: sessionId || null, deleteRtdbSessionData });
-    const cleanup = [
-      {
-        path: "events.activeAnalyticsSessionId",
-        promise: updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() })
-      },
-      {
-        path: "ctrl/activeSessionId",
-        promise: remove(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`))
-      }
-    ];
-    if (sessionId) {
-      cleanup.push({
-        path: `activeSessions/${sessionId}`,
-        promise: remove(ref(rtdb, `activeSessions/${sessionId}`))
-      });
-    }
+    await assertSessionHasNothingToEnd(eventId, sessionId);
+    const attempts = await releaseSessionPointers(eventId, sessionId);
     if (sessionId && deleteRtdbSessionData) {
-      cleanup.push({
-        path: `events/${eventId}/sessions/${sessionId}`,
-        promise: remove(ref(rtdb, `events/${eventId}/sessions/${sessionId}`))
-      });
+      attempts.push(await attemptCleanup(`events/${eventId}/sessions/${sessionId}`, () => remove(ref(rtdb, `events/${eventId}/sessions/${sessionId}`))));
     }
-    const settled = await Promise.allSettled(cleanup.map((operation) => operation.promise));
-    const attempts = settled.map((result, index) => {
-      const operation = cleanup[index];
-      if (!operation)
-        throw new Error("Session repair result has no matching cleanup operation.");
-      return {
-        path: operation.path,
-        status: result.status,
-        ...result.status === "rejected" ? {
-          error: result.reason instanceof Error ? result.reason.message : String(result.reason)
-        } : {}
-      };
-    });
     let firestorePointer = null;
     let rtdbPointer = null;
     let verificationError;
@@ -120278,7 +120379,11 @@ function registerSessionTools(server2) {
       ],
       returns: "eventId, sessionId, deleted=true, and cleaned paths.",
       examples: ["Use only after confirming the exact session id with the organizer."],
-      notes: ["Destructive. If the session is active, active pointers are cleared first. RTDB session data cleanup is best-effort because rules may deny deleting historical session snapshots."]
+      notes: [
+        "Destructive. If the session is active, all three pointers are released first \u2014 atomically in RTDB, then in Firestore \u2014 and only then is the document deleted; the platform refuses to delete the report of a session it still considers active.",
+        "Refuses an active session that still has working state in RTDB: end it with oko_end_session, which saves the report.",
+        "RTDB session data cleanup is best-effort because rules may deny deleting historical session snapshots."
+      ]
     }),
     inputSchema: {
       eventId: eventIdField,
@@ -120293,17 +120398,19 @@ function registerSessionTools(server2) {
     const event = await readEvent(eventId, uid, "session");
     requireConfirm(confirm, "oko_delete_session", { eventId, sessionId, deleteRtdbData });
     const isActive = safeString(event.activeAnalyticsSessionId) === sessionId;
-    const cleanup = [];
+    const warnings = [];
     if (isActive) {
-      cleanup.push(updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() }));
-      cleanup.push(remove(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`)));
-      cleanup.push(remove(ref(rtdb, `activeSessions/${sessionId}`)));
-    }
-    cleanup.push(deleteDoc(doc(firestore, "events", eventId, "analyticsSessions", sessionId)));
-    const results = await Promise.allSettled(cleanup);
-    const warnings = results.filter((result) => result.status === "rejected").map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason));
-    if (warnings.length > 0)
-      throw new Error(`Session delete partially failed: ${warnings.join("; ")}`);
+      await assertSessionHasNothingToEnd(eventId, sessionId);
+      const attempts = await releaseSessionPointers(eventId, sessionId);
+      warnings.push(...attempts.filter((attempt) => attempt.status === "rejected").map((attempt) => `${attempt.path}: ${attempt.error || "cleanup failed"}`));
+      if (warnings.length > 0)
+        throw new Error(`Session delete partially failed: ${warnings.join("; ")}`);
+    }
+    try {
+      await deleteDoc(doc(firestore, "events", eventId, "analyticsSessions", sessionId));
+    } catch (error3) {
+      throw new Error(`Session delete partially failed: ${error3 instanceof Error ? error3.message : String(error3)}`);
+    }
     const rtdbCleanupWarnings = [];
     if (deleteRtdbData) {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.12.12",
+  "version": "0.12.13",
   "description": "Control OKO Stream webinars from Claude, Codex, and other MCP clients.",
   "license": "UNLICENSED",
   "author": {