@okostream/mcp 0.16.0 → 0.17.0

package/dist/server.js

@@ -116311,7 +116311,7 @@ function sanitizeScopes(scopes) {
 }
 
 // build/version.js
-var OKO_MCP_VERSION = "0.16.0";
+var OKO_MCP_VERSION = "0.17.0";
 
 // build/auth.js
 var state = null;
@@ -119025,6 +119025,10 @@ function buildCreateWebinarDocument(input) {
     createdAt: input.createdAt,
     title: input.title.trim(),
     pinned: false,
+    // The auto start is ON in every new page (release "sessions", `docs/planning/sessions-and-show-billing.md` §9.5):
+    // the session starts by itself at the start of its plan — the event time until Setup sets another. The flag is a
+    // page setting (organizer-writable), not server state; the canary writes this exact shape through the rules.
+    analyticsSessionMode: "schedule",
     video: input.video,
     meta: {
       eventDate: input.eventDate,
@@ -119045,6 +119049,12 @@ function buildCreateWebinarDocument(input) {
     }
   };
 }
+function withoutSessionPlan(meta2) {
+  if (!meta2 || typeof meta2 !== "object" || Array.isArray(meta2))
+    return void 0;
+  const { sessionStartAt: _start, sessionEndAt: _end, ...rest } = meta2;
+  return rest;
+}
 var DUPLICATE_TITLE_SUFFIX = " (copy)";
 var MAX_EVENT_TITLE_LENGTH = 300;
 function duplicateEventTitle(sourceTitle) {
@@ -119060,8 +119070,13 @@ function buildDuplicateEventDocument(input) {
     title: duplicateEventTitle(safeString(source.title, "Untitled event")),
     duplicatedFrom: input.sourceEventId,
     pinned: false,
+    // A copy is a NEW page: the auto start is ON like everywhere else (§9.5), whatever the source's mode was.
+    analyticsSessionMode: "schedule",
     video: source.video ?? { originalUrl: null, embedUrl: null },
-    meta: source.meta ?? { eventDate: null, speakerName: null, description: null },
+    // 🔴 The session plan (`meta.sessionStartAt`/`sessionEndAt`) is NOT copied (R6): a copy is a second show with another
+    // date, and a plan set by hand for the old date would read as «the session time does not match the show» on a page
+    // that never had one. The copy's plan is its event time until Setup sets another.
+    meta: withoutSessionPlan(source.meta) ?? { eventDate: null, speakerName: null, description: null },
     blocks: source.blocks ?? {},
     ...Array.isArray(source.forms) ? { forms: source.forms } : {},
     // 🔴 The copy does NOT inherit server-owned Telegram markers.
@@ -119105,6 +119120,124 @@ function eventRuntimeHint(runtime) {
   ];
 }
 
+// build/tools/scheduleWindow.js
+var SCHEDULED_SESSION_DEFAULT_MINUTES = 120;
+var SCHEDULED_SESSION_MIN_MINUTES = 15;
+var SCHEDULED_SESSION_MAX_MINUTES = 1440;
+function scheduledDurationMs(raw) {
+  const minutes = typeof raw === "number" && Number.isFinite(raw) ? Math.min(SCHEDULED_SESSION_MAX_MINUTES, Math.max(SCHEDULED_SESSION_MIN_MINUTES, Math.round(raw))) : SCHEDULED_SESSION_DEFAULT_MINUTES;
+  return minutes * 60 * 1e3;
+}
+function scheduleWindowPassed(sessionMode, eventDateMs, rawDurationMinutes, nowMs) {
+  if (sessionMode !== "schedule")
+    return false;
+  if (eventDateMs === null)
+    return false;
+  return nowMs >= eventDateMs + scheduledDurationMs(rawDurationMinutes);
+}
+
+// build/tools/sessionPlan.js
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function timestampMillis(value) {
+  if (value instanceof Date)
+    return value.getTime();
+  if (value && typeof value === "object" && typeof value.toMillis === "function") {
+    return value.toMillis();
+  }
+  return null;
+}
+function readSessionPlan(event, durationMsOf) {
+  const meta2 = isRecord(event.meta) ? event.meta : {};
+  const startMs = timestampMillis(meta2.sessionStartAt);
+  const endMs = timestampMillis(meta2.sessionEndAt);
+  if (startMs !== null && endMs !== null && endMs > startMs)
+    return { startMs, endMs, source: "meta" };
+  const eventDateMs = timestampMillis(meta2.eventDate);
+  if (eventDateMs === null)
+    return null;
+  return { startMs: eventDateMs, endMs: eventDateMs + durationMsOf(meta2.durationMinutes), source: "event" };
+}
+function sessionPlanOf(event) {
+  return readSessionPlan(event, scheduledDurationMs);
+}
+var iso = (ms) => new Date(ms).toISOString();
+function sessionPlanWarnings(event) {
+  const plan = sessionPlanOf(event);
+  if (!plan || plan.source !== "meta")
+    return [];
+  const meta2 = isRecord(event.meta) ? event.meta : {};
+  const eventDateMs = timestampMillis(meta2.eventDate);
+  if (eventDateMs === null)
+    return [];
+  const eventEndMs = eventDateMs + scheduledDurationMs(meta2.durationMinutes);
+  if (plan.startMs === eventDateMs && plan.endMs === eventEndMs)
+    return [];
+  return [{
+    code: "session_plan_differs_from_event",
+    message: `The session plan (${iso(plan.startMs)} to ${iso(plan.endMs)}) is not the event time (${iso(eventDateMs)} to ${iso(eventEndMs)}). The automatic start and the automatic stop follow the PLAN. If the event moved and the session should follow it, clear the plan with oko_update_event sessionStartAt: null and sessionEndAt: null (the plan then equals the event time).`
+  }];
+}
+function sessionOutlookWarnings(outlook) {
+  if (outlook.moneyMode === "off")
+    return [];
+  const warnings = [];
+  if (!outlook.entitlement.ok) {
+    warnings.push({
+      code: "session_tier_has_no_sessions",
+      message: outlook.entitlement.reason === "tier" ? `The plan that pays for this page (${outlook.entitlement.currentTier ?? "unknown"}) has no analytics sessions: they come with ${outlook.entitlement.requiredTier ?? "pro"} and above. Start is refused, and the automatic start is skipped silently.` : "The subscription that pays for this page is not active, so Start is refused and the automatic start will not happen. The subscription owner can renew it in the OKO cabinet."
+    });
+    return warnings;
+  }
+  if (outlook.lumens.enoughForPlan === false && outlook.lumens.neededForPlan !== null) {
+    warnings.push({
+      code: "session_lumens_not_enough_for_plan",
+      message: `A session that runs to the end of its plan costs about ${outlook.lumens.neededForPlan} lumens (1 per minute, taken when it ends). The wallet that pays for this workspace holds less: the session would be stopped when the lumens run out. Its owner can top it up. Lumens are checked at Start (a wallet at zero refuses it) and every minute while it runs.`
+    });
+  }
+  return warnings;
+}
+function sessionExplanation(args) {
+  const lines = [];
+  if (args.billingMode === "metered") {
+    lines.push("A session costs 1 lumen per minute, taken from the wallet that pays when the session ends (minutes are rounded; under 30 seconds is free). There is no debt: if the wallet runs dry the session is stopped and the rest is forgiven.");
+  } else if (args.billingMode === "free") {
+    lines.push("Session minutes are not being charged for this page right now.");
+  }
+  if (typeof args.plannedEndAt === "number") {
+    lines.push(`The session ends by itself at ${iso(args.plannedEndAt)} (its plan). Move the end with oko_extend_session, or end it earlier with oko_end_session.`);
+  }
+  if (args.clamped) {
+    lines.push("The requested end was moved back to the end of the page's show window: a session cannot run past it.");
+  }
+  return lines;
+}
+
+// build/tools/sessionOutlook.js
+async function fetchSessionOutlook(eventId) {
+  try {
+    const preview = httpsCallable(functions, "previewAnalyticsSession");
+    const result = await preview({ eventId });
+    return { outlook: result.data };
+  } catch (error3) {
+    return { error: error3 instanceof Error ? error3.message : String(error3) };
+  }
+}
+async function collectSessionWarnings(eventId, event) {
+  const warnings = sessionPlanWarnings(event);
+  const fetched = await fetchSessionOutlook(eventId);
+  if ("outlook" in fetched) {
+    warnings.push(...sessionOutlookWarnings(fetched.outlook));
+  } else {
+    warnings.push({
+      code: "session_outlook_unavailable",
+      message: `Could not check the payer's plan and lumens for this page's session (${fetched.error}). The write itself went through.`
+    });
+  }
+  return warnings;
+}
+
 // build/tools/liveLayer.js
 var LIVE_FIELDS_HINT = "blocks.promoBanner.visibility, blocks.primaryCta.visibility, blocks.cards.visibility and blocks.video.placeholder.enabled are SETUP values. What viewers see right now is `live.<block>.visibleNow` \u2014 `decidedBy` says whether a live override (oko_set_block_visibility) or the setup default decided it. For the chat, `live.chat.accepting` is whether viewers can send a message right now; `blocks.chat.intake` is only the starting state. The live badge and the active analytics session are not resolved here: read oko_get_live_state (ctrl.liveBadge, ctrl.activeSessionId).";
 var liveUnreadableHint = (reason) => `blocks.*.visibility and .enabled above are SETUP values, not what viewers see now \u2014 and the live overrides could not be read (${reason}; a key without analytics:read or live:control is always refused here). Do not report a block as shown or hidden from these fields; read oko_get_live_state with a key that holds the scope.`;
@@ -119166,23 +119299,15 @@ async function readLiveLayer(eventId, data, nowMs) {
   return { live, hints };
 }
 
-// build/tools/scheduleWindow.js
-var SCHEDULED_SESSION_DEFAULT_MINUTES = 120;
-var SCHEDULED_SESSION_MIN_MINUTES = 15;
-var SCHEDULED_SESSION_MAX_MINUTES = 1440;
-function scheduledDurationMs(raw) {
-  const minutes = typeof raw === "number" && Number.isFinite(raw) ? Math.min(SCHEDULED_SESSION_MAX_MINUTES, Math.max(SCHEDULED_SESSION_MIN_MINUTES, Math.round(raw))) : SCHEDULED_SESSION_DEFAULT_MINUTES;
-  return minutes * 60 * 1e3;
-}
-function scheduleWindowPassed(sessionMode, eventDateMs, rawDurationMinutes, nowMs) {
-  if (sessionMode !== "schedule")
-    return false;
-  if (eventDateMs === null)
+// build/tools/setupValidation.js
+function scheduleWindowPassedByPlan(event, eventDateMs, rawDurationMinutes, nowMs) {
+  if (event.analyticsSessionMode !== "schedule")
     return false;
-  return nowMs >= eventDateMs + scheduledDurationMs(rawDurationMinutes);
+  const plan = sessionPlanOf(event);
+  if (plan && plan.source === "meta")
+    return nowMs >= plan.endMs;
+  return scheduleWindowPassed(event.analyticsSessionMode, eventDateMs, rawDurationMinutes, nowMs);
 }
-
-// build/tools/setupValidation.js
 function validateEventSetup(eventId, event, nowMs = Date.now()) {
   const errors = [];
   const warnings = [];
@@ -119204,13 +119329,16 @@ function validateEventSetup(eventId, event, nowMs = Date.now()) {
   const eventDateMs = toMillis(meta2.eventDate);
   if (eventDateMs == null) {
     add(suggestions, "date_missing", "meta.eventDate", "Add the webinar date/time if it is known.");
-  } else if (scheduleWindowPassed(event.analyticsSessionMode, eventDateMs, meta2.durationMinutes, nowMs)) {
-    add(errors, "schedule_window_passed", "meta.eventDate", "Session mode is 'schedule' and the scheduled time (eventDate + durationMinutes) has already passed, so OKO will not start the analytics session automatically. If the webinar has not taken place yet, set a future eventDate with oko_update_event, or start the session by hand with oko_start_session. If it has already taken place, this is expected.");
+  } else if (scheduleWindowPassedByPlan(event, eventDateMs, meta2.durationMinutes, nowMs)) {
+    add(errors, "schedule_window_passed", "meta.eventDate", "The auto start is on ('schedule') and the session plan (the session time set in Setup, else eventDate + durationMinutes) has already passed, so OKO will not start the analytics session automatically. If the webinar has not taken place yet, set a future eventDate (or session time) with oko_update_event, or start the session by hand with oko_start_session. If it has already taken place, this is expected.");
   } else if (event.analyticsSessionMode !== "schedule" && eventDateMs < nowMs - 60 * 60 * 1e3) {
     add(warnings, "date_in_past", "meta.eventDate", "Configured webinar date appears to be in the past.");
   }
   if (scheduleMissesDate(event.analyticsSessionMode, meta2.eventDate)) {
-    add(errors, "schedule_missing_date", "analyticsSessionMode", "Session mode is 'schedule' but meta.eventDate is empty, so OKO can never start or end the session automatically and the reminder is never sent. Set eventDate, or switch sessionMode to 'manual' \u2014 oko_update_event accepts both fields in one call.");
+    add(warnings, "schedule_missing_date", "meta.eventDate", "Add the event date: without a date the session does not start by itself (the auto start is on, 'schedule', and OKO has no session time to start it at), and a page cannot be published without a date. A page is born this way until the date is set \u2014 this is a normal draft, not an error. Set meta.eventDate, or switch sessionMode to 'manual' \u2014 oko_update_event accepts both fields in one call.");
+  }
+  for (const warning of sessionPlanWarnings(event)) {
+    add(warnings, warning.code, "meta.sessionStartAt", warning.message);
   }
   const duplicateFormIds = /* @__PURE__ */ new Set();
   const seenFormIds = /* @__PURE__ */ new Set();
@@ -119349,25 +119477,25 @@ function stateWithin(now, window2) {
     return "open";
   return "after";
 }
-function isRecord(value) {
+function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function toMillis2(value) {
   if (typeof value === "number" && Number.isFinite(value))
     return value;
-  if (isRecord(value) && typeof value.toMillis === "function") {
+  if (isRecord2(value) && typeof value.toMillis === "function") {
     const ms = value.toMillis();
     return typeof ms === "number" && Number.isFinite(ms) ? ms : null;
   }
   return null;
 }
 function windowFromEvent(event, nowMs) {
-  const billing = isRecord(event.billing) ? event.billing : {};
+  const billing = isRecord2(event.billing) ? event.billing : {};
   const storedStart = toMillis2(billing.windowStart);
   const storedEnd = toMillis2(billing.windowEnd);
   let window2 = storedStart !== null && storedEnd !== null ? { windowStart: new Date(storedStart), windowEnd: new Date(storedEnd) } : null;
   if (!window2) {
-    const meta2 = isRecord(event.meta) ? event.meta : {};
+    const meta2 = isRecord2(event.meta) ? event.meta : {};
     const eventDateMs = toMillis2(meta2.eventDate);
     if (eventDateMs !== null)
       window2 = showWindow(new Date(eventDateMs));
@@ -119385,11 +119513,28 @@ function telegramBlocksPatch(args) {
   };
 }
 function assertScheduleHasDate(fresh, patch) {
+  const touchesModeOrDate = "analyticsSessionMode" in patch || "meta.eventDate" in patch || "meta" in patch;
+  if (!touchesModeOrDate)
+    return;
   const missing = scheduleMissesDate(valueAfterPatch(fresh, patch, "analyticsSessionMode"), valueAfterPatch(fresh, patch, "meta.eventDate"));
   if (!missing)
     return;
   throw new Error("sessionMode 'schedule' requires meta.eventDate: without a date OKO can never start the session automatically. Set eventDate in the same call, or switch sessionMode to 'manual' in the same call to clear the date.");
 }
+function assertSessionPlanValid(fresh, patch) {
+  if (!("meta.sessionStartAt" in patch) && !("meta.sessionEndAt" in patch) && !("meta" in patch))
+    return;
+  const start = toMillis(valueAfterPatch(fresh, patch, "meta.sessionStartAt"));
+  const end = toMillis(valueAfterPatch(fresh, patch, "meta.sessionEndAt"));
+  if (start === null && end === null)
+    return;
+  if (start === null || end === null) {
+    throw new Error("The session plan needs BOTH sessionStartAt and sessionEndAt: pass the pair in one call, or pass null for both to follow the event time.");
+  }
+  if (end <= start) {
+    throw new Error("sessionEndAt must be later than sessionStartAt.");
+  }
+}
 var DATE_LOCKED_BILLING_STATES = /* @__PURE__ */ new Set(["published", "held"]);
 function eventDateLockedRefusal(eventId, windowOpened) {
   return {
@@ -119583,7 +119728,10 @@ function registerEventTools(server2) {
         "Use after creating/configuring a webinar and before telling the organizer it is ready.",
         "Use before live-session prep to catch missing video, pending image variants, and invalid form bindings."
       ],
-      notes: ["This tool does not modify the event and does not start/end analytics sessions."]
+      notes: [
+        "This tool does not modify the event and does not start/end analytics sessions.",
+        "Session warnings (from the page plan and, when the server answers, the payer's plan and lumens): the session plan differs from the event time \xB7 the lumens will not last the plan \xB7 the plan that pays has no sessions. They are warnings, not errors: the page can be published and shown either way."
+      ]
     }),
     inputSchema: { eventId: eventIdField },
     outputSchema: setupValidationOutputSchema,
@@ -119591,7 +119739,16 @@ function registerEventTools(server2) {
   }, async ({ eventId }) => {
     const { uid } = await authed(["events:read"]);
     const data = await readEvent(eventId, uid, "read");
-    return textResult(validateEventSetup(eventId, data, await serverNowMs()));
+    const report = validateEventSetup(eventId, data, await serverNowMs());
+    const fetched = await fetchSessionOutlook(eventId);
+    const outlookWarnings = "outlook" in fetched ? sessionOutlookWarnings(fetched.outlook) : [{ code: "session_outlook_unavailable", message: `Could not check the payer's plan and lumens for this page's session (${fetched.error}).` }];
+    return textResult({
+      ...report,
+      warnings: [
+        ...report.warnings,
+        ...outlookWarnings.map((warning) => ({ code: warning.code, path: "analyticsSessionMode", message: warning.message }))
+      ]
+    });
   });
   server2.registerTool("oko_create_webinar", {
     title: "Create webinar",
@@ -119642,12 +119799,15 @@ function registerEventTools(server2) {
       createdAt: serverTimestamp2()
     }));
     const docRef = created.ref;
+    const sessionWarnings = await collectSessionWarnings(docRef.id, { meta: { eventDate: args.eventDate ? Timestamp.fromDate(new Date(args.eventDate)) : null } });
     return textResult({
       id: docRef.id,
       ...eventLinks(docRef.id),
       workspaceId,
       runtime: created.runtime,
+      warnings: sessionWarnings,
       hints: [
+        "Analytics sessions: the page starts and ends its session by itself at the event time (sessionMode schedule; a session costs 1 lumen per minute, taken when it ends). Change the time of the session or turn the auto start off with oko_update_event (sessionMode, sessionStartAt, sessionEndAt).",
         ...eventRuntimeHint(created.runtime),
         `The page is a draft: viewers of publicUrl see "not published" (a legacy-tier payer's page is published at creation). Do not hand publicUrl out as live until oko_publish_event has published it \u2014 quote first, then confirm with the organizer.`,
         "Next: oko_configure_blocks for chat/CTA/placeholder, oko_configure_cards for cards, image uploads, oko_validate_event_setup, then oko_publish_event.",
@@ -119660,12 +119820,14 @@ function registerEventTools(server2) {
     description: toolDescription({
       summary: "Update safe top-level event/setup metadata fields.",
       exampleCall: { "eventId": "Kx9pQ2mR7tL4vB8nW3cY", "title": "Autumn product webinar (rescheduled)", "eventDate": "2026-09-12T07:00:00.000Z", "speakerName": "Jane Doe", "description": "", "durationMinutes": 60 },
-      args: ["eventId plus any subset of title, videoUrl, eventDate, speakerName, description, pinned, sessionMode, durationMinutes."],
-      returns: "event id and the list of Firestore fields updated.",
+      args: ["eventId plus any subset of title, videoUrl, eventDate, speakerName, description, pinned, sessionMode, durationMinutes, sessionStartAt, sessionEndAt."],
+      returns: "event id, the list of Firestore fields updated, and session warnings (plan versus event time, lumens versus plan, a plan with no sessions).",
       examples: ["Use for title/date/speaker/video edits; use oko_configure_blocks for blocks and forms."],
       notes: [
-        "sessionMode 'schedule' makes OKO start and end the analytics session automatically at eventDate for durationMinutes; 'manual' keeps the Start/End buttons and a Telegram reminder 10 minutes before eventDate. This is still an analytics session, not an event status.",
-        "sessionMode 'schedule' and eventDate travel together: setting the mode without a date, or clearing the date while the mode stays, is refused. Change both in one call.",
+        "An ANALYTICS SESSION measures the show and costs 1 lumen per minute, taken when it ends (no debt; it stops by itself when the lumens run out). It always has a start and an end: the page's session plan \u2014 sessionStartAt and sessionEndAt, both or neither \u2014 and without them the plan is the event time (eventDate to eventDate + durationMinutes).",
+        "sessionMode now means ONLY the automatic start: 'schedule' (the default of every new page) starts the session by itself at the plan's start; 'manual' turns that off \u2014 the organizer starts it with oko_start_session and a Telegram reminder comes 10 minutes before eventDate. Either way the session ends at the end of its plan, and oko_extend_session moves that end while it runs. This is still an analytics session, not an event status.",
+        "sessionStartAt/sessionEndAt: pass BOTH ISO datetimes to set a session time different from the show's, or pass null for both to follow the event time again. A session plan that differs from the event time is reported as a warning (moving eventDate does not move an explicit plan).",
+        "Setting sessionMode 'schedule' on a page with no date, or clearing the date of a page in 'schedule', in one call is refused (nothing could start from it); a page born with the auto start on and no date yet is normal and can be edited freely.",
         'eventDate is LOCKED once the page is published and paid (not on the transition plan): changing it is refused with errorCode EVENT_DATE_LOCKED \u2014 every other field in the same call still goes through if eventDate is dropped from it. Before the show window opens: oko_unpublish_event (refunds), change the date, oko_publish_event (new charge). After the window opens, or once the page shows "held"/\u041F\u0440\u043E\u0432\u0435\u0434\u0435\u043D\u043E: the date cannot move at all \u2014 duplicate the page with oko_duplicate_event for the new date.'
       ]
     }),
@@ -119677,8 +119839,10 @@ function registerEventTools(server2) {
       speakerName: external_exports.string().max(160).nullable().optional().describe('New speaker display name; pass "" or null to clear (the literal text "null" is rejected).'),
       description: external_exports.string().max(3e3).nullable().optional().describe('New description; pass "" or null to clear (the literal text "null" is rejected).'),
       pinned: external_exports.boolean().optional().describe("Whether this event is pinned in the dashboard."),
-      sessionMode: external_exports.enum(["manual", "schedule"]).optional().describe("Analytics session mode: manual Start/End buttons, or automatic start/end on schedule at eventDate."),
-      durationMinutes: external_exports.number().int().min(15).max(1440).optional().describe("Event duration in minutes (15-1440) used by schedule mode to end the session.")
+      sessionMode: external_exports.enum(["manual", "schedule"]).optional().describe("Automatic start of the analytics session: 'schedule' starts it by itself at the start of the session plan (the default of a new page), 'manual' leaves the start to oko_start_session. The session always ends at the end of its plan."),
+      durationMinutes: external_exports.number().int().min(15).max(1440).optional().describe("Event duration in minutes (15-1440); with eventDate it is the default session plan."),
+      sessionStartAt: external_exports.string().datetime().nullable().optional().describe("Start of the session plan (ISO datetime), or null to follow the event time. Pass together with sessionEndAt."),
+      sessionEndAt: external_exports.string().datetime().nullable().optional().describe("End of the session plan (ISO datetime), or null to follow the event time. Pass together with sessionStartAt.")
     },
     outputSchema: updateOutputSchema,
     annotations: writeTool
@@ -119686,7 +119850,7 @@ function registerEventTools(server2) {
     const requiredScopes = /* @__PURE__ */ new Set();
     if (args.title !== void 0 || args.pinned !== void 0)
       requiredScopes.add("events:write");
-    if (args.videoUrl !== void 0 || args.eventDate !== void 0 || args.speakerName !== void 0 || args.description !== void 0 || args.sessionMode !== void 0 || args.durationMinutes !== void 0) {
+    if (args.videoUrl !== void 0 || args.eventDate !== void 0 || args.speakerName !== void 0 || args.description !== void 0 || args.sessionMode !== void 0 || args.durationMinutes !== void 0 || args.sessionStartAt !== void 0 || args.sessionEndAt !== void 0) {
       requiredScopes.add("setup:write");
     }
     if (requiredScopes.size === 0)
@@ -119717,14 +119881,21 @@ function registerEventTools(server2) {
       patch.analyticsSessionMode = args.sessionMode;
     if (args.durationMinutes !== void 0)
       patch["meta.durationMinutes"] = args.durationMinutes;
+    if (args.sessionStartAt !== void 0)
+      patch["meta.sessionStartAt"] = args.sessionStartAt ? Timestamp.fromDate(new Date(args.sessionStartAt)) : null;
+    if (args.sessionEndAt !== void 0)
+      patch["meta.sessionEndAt"] = args.sessionEndAt ? Timestamp.fromDate(new Date(args.sessionEndAt)) : null;
     const nowMs = args.eventDate !== void 0 ? await serverNowMs() : null;
     const validate = (fresh, freshPatch) => {
       assertScheduleHasDate(fresh, freshPatch);
+      assertSessionPlanValid(fresh, freshPatch);
       if (nowMs !== null)
         assertDateNotLocked(args.eventId, fresh, freshPatch, nowMs);
     };
     await writeEventPatchWithCards(args.eventId, patch, null, validate);
-    return textResult({ id: args.eventId, updated: Object.keys(patch) });
+    const touchesSession = ["meta.eventDate", "meta.durationMinutes", "meta.sessionStartAt", "meta.sessionEndAt", "analyticsSessionMode"].some((key) => key in patch);
+    const warnings = touchesSession ? await collectSessionWarnings(args.eventId, await readEvent(args.eventId, uid, "read")) : [];
+    return textResult({ id: args.eventId, updated: Object.keys(patch), warnings });
   });
   server2.registerTool("oko_configure_blocks", {
     title: "Configure event blocks",
@@ -121105,6 +121276,16 @@ async function releaseSessionPointers(eventId, sessionId) {
   attempts.push(await attemptCleanup("events.activeAnalyticsSessionId", () => updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() })));
   return attempts;
 }
+function settlementLine(result) {
+  if (typeof result.minutes !== "number")
+    return null;
+  if (result.billingMode === "free") {
+    return `The session ran ${result.minutes} minute(s); minutes are not being charged for this page right now (0 lumens taken).`;
+  }
+  const charged = typeof result.charged === "number" ? result.charged : 0;
+  const forgiven = typeof result.forgiven === "number" ? result.forgiven : 0;
+  return `Charged ${charged} lumens for ${result.minutes} minute(s)` + (forgiven > 0 ? `; ${forgiven} more were forgiven because the wallet did not hold enough (no debt).` : ".");
+}
 function startSessionRefusal(eventId, body) {
   return { ...textResult({ tool: "oko_start_session", eventId, ...body }), isError: true };
 }
@@ -121126,6 +121307,54 @@ function startSessionRefusalResult(eventId, error3) {
       ]
     });
   }
+  if (info.errorCode === "ENTITLEMENT_REQUIRED") {
+    const inactive = info.reason === "plan_inactive";
+    return startSessionRefusal(eventId, {
+      errorCode: "ENTITLEMENT_REQUIRED",
+      reason: inactive ? "plan_inactive" : "tier",
+      requiredTier: typeof info.requiredTier === "string" ? info.requiredTier : "pro",
+      currentTier: typeof info.currentTier === "string" ? info.currentTier : null,
+      message: text || (inactive ? "OKO refused to start the session: the subscription that pays for this page is not active. Nothing was started or charged." : "OKO refused to start the session: the plan that pays for this page has no analytics sessions. Nothing was started or charged."),
+      whatToDo: inactive ? [
+        "Explain that the subscription owner can renew or buy a plan in the OKO cabinet.",
+        "Do not retry as is: the answer will not change until the subscription does."
+      ] : [
+        "Explain that analytics sessions come with the Pro plan and above; the subscription owner can upgrade in the OKO cabinet.",
+        "Do not retry as is: the answer will not change until the plan does."
+      ]
+    });
+  }
+  if (info.errorCode === "INSUFFICIENT_TOKENS") {
+    const callerIsPayer = info.callerIsPayer === true;
+    return startSessionRefusal(eventId, {
+      errorCode: "INSUFFICIENT_TOKENS",
+      callerIsPayer,
+      message: text || "OKO refused to start the session: the wallet that pays for this page has 0 lumens. Nothing was started or charged.",
+      whatToDo: [
+        callerIsPayer ? "Explain that a session costs 1 lumen per minute and the wallet is at zero: lumens can be topped up in the OKO cabinet." : "Explain that this workspace is paid for by its owner, whose lumens have run out: ask the owner to top up.",
+        "Do not retry as is: the balance will not change by itself."
+      ]
+    });
+  }
+  if (info.reason === "payer_unresolved") {
+    return startSessionRefusal(eventId, {
+      errorCode: "PAYER_UNRESOLVED",
+      message: text || "OKO cannot tell which workspace wallet pays for this event, so a session cannot be charged. Nothing was started.",
+      whatToDo: [
+        "Check the event's workspace with oko_get_event; if the workspace was removed, move the event with oko_move_event.",
+        "Do not retry as is: the answer will not change until the workspace does."
+      ]
+    });
+  }
+  if (info.reason === "planned_end_invalid") {
+    return startSessionRefusal(eventId, {
+      errorCode: "PLANNED_END_INVALID",
+      message: text || "The end of the session must be a moment in the future. Nothing was started.",
+      whatToDo: [
+        "Pass endsAt as an ISO datetime later than now, or omit it to end with the page's plan."
+      ]
+    });
+  }
   if (info.reason === "outside_show_window") {
     const state2 = info.window === "before" || info.window === "after" ? info.window : null;
     return startSessionRefusal(eventId, {
@@ -121145,32 +121374,92 @@ function startSessionRefusalResult(eventId, error3) {
   }
   return null;
 }
+function buildExtendRequest(input) {
+  const { eventId, sessionId, endsAt, addMinutes } = input;
+  if (endsAt !== void 0)
+    return { eventId, sessionId, plannedEndAt: Date.parse(endsAt) };
+  return { eventId, sessionId, addMinutes };
+}
+function extendSessionRefusalResult(eventId, error3) {
+  if (!error3 || typeof error3 !== "object")
+    return null;
+  const { code, message, details } = error3;
+  if (typeof code !== "string" || !code.startsWith("functions/"))
+    return null;
+  const info = details && typeof details === "object" ? details : {};
+  const text = safeString(message);
+  const refusal4 = (body) => ({ ...textResult({ tool: "oko_extend_session", eventId, ...body }), isError: true });
+  if (info.reason === "session_not_running") {
+    return refusal4({
+      errorCode: "SESSION_NOT_RUNNING",
+      message: text || "No analytics session is running on this page, so there is nothing to extend.",
+      whatToDo: [
+        "Start a session with oko_start_session (it takes an endsAt), or, if it already ended, extend nothing: a finished session is final."
+      ]
+    });
+  }
+  if (info.reason === "planned_end_invalid") {
+    return refusal4({
+      errorCode: "PLANNED_END_INVALID",
+      message: text || "The new end must be a moment in the future.",
+      whatToDo: ["Pass endsAt later than now, or addMinutes to move the current end forward."]
+    });
+  }
+  if (info.reason === "outside_show_window") {
+    return refusal4({
+      errorCode: "OUTSIDE_SHOW_WINDOW",
+      message: text || "The show window of this page is over: a session can no longer be extended.",
+      whatToDo: ["End the session with oko_end_session; to run the show on another date, duplicate the page with oko_duplicate_event."]
+    });
+  }
+  return null;
+}
 function registerSessionTools(server2) {
   server2.registerTool("oko_start_session", {
     title: "Start analytics session",
     description: toolDescription({
-      summary: "Start an analytics session using the same Firestore/RTDB pointers as the dashboard.",
-      args: ["eventId: event whose analytics session should start.", "confirm: must be true."],
-      returns: "eventId, new sessionId, and started=true.",
+      summary: "Start an analytics session using the same Firestore/RTDB pointers as the dashboard. A session measures the show and costs 1 lumen per minute, taken when it ends.",
+      args: [
+        "eventId: event whose analytics session should start.",
+        "endsAt: optional ISO datetime when the session should end. Omit it to end with the page's plan (the session time set in Setup, else the event time); it is never later than the end of the page's show window (the answer says clamped:true when it was moved back).",
+        "confirm: must be true."
+      ],
+      returns: "eventId, new sessionId, started=true, plannedEndAt (ms) and endsAt (ISO), billingMode (metered or free), clamped, and an explanation.",
       examples: ["Use when the organizer wants analytics tracking to begin; it does not start the video stream."],
       notes: [
         "OKO Start/End controls analytics sessions only, not stream publishing.",
-        "A new session only starts inside the page's show window (24h before the event date to 48h after). Refusals carry errorCode and whatToDo: PAGE_NOT_PUBLISHED (publish the page first with oko_publish_event) and OUTSIDE_SHOW_WINDOW (windowState before/after \u2014 wait for the window, or duplicate the page for another date with oko_duplicate_event)."
+        "A session ALWAYS has an end: the plan's end (or endsAt); when it comes OKO ends the session by itself, and the closer a show runs to it the more useful oko_extend_session is. If the show starts before the plan, the session is longer than the plan; if it starts after the plan already ended, it gets the plan's length from now.",
+        "Minutes are counted when the session ends (rounded; under 30 seconds is free) and taken from the wallet that pays, at most as much as it holds \u2014 there is no debt. If the lumens run out while it runs, OKO stops the session by itself. Pages can also start their session automatically at the plan's start (sessionMode schedule); Start here is the manual way.",
+        "A new session only starts inside the page's show window (24h before the event date to 48h after). Refusals carry errorCode and whatToDo: PAGE_NOT_PUBLISHED (publish the page first with oko_publish_event), OUTSIDE_SHOW_WINDOW (windowState before/after \u2014 wait for the window, or duplicate the page for another date with oko_duplicate_event), ENTITLEMENT_REQUIRED (reason tier: the plan has no sessions, they come with Pro and above; reason plan_inactive: the subscription is not active), INSUFFICIENT_TOKENS (the paying wallet is at zero; callerIsPayer tells who should top it up), PAYER_UNRESOLVED and PLANNED_END_INVALID (endsAt must be in the future)."
       ]
     }),
-    inputSchema: { eventId: eventIdField, confirm: external_exports.boolean().optional().describe("Required true to start analytics collection session.") },
+    inputSchema: {
+      eventId: eventIdField,
+      endsAt: external_exports.string().datetime().optional().describe("Optional ISO datetime for the end of this session; omit to end with the page's plan."),
+      confirm: external_exports.boolean().optional().describe("Required true to start analytics collection session.")
+    },
     outputSchema: basicEventOutputSchema,
     annotations: writeTool
-  }, async ({ eventId, confirm }) => {
+  }, async ({ eventId, endsAt, confirm }) => {
     const { uid } = await authed(["analytics:write", "live:control"]);
     const event = await readEvent(eventId, uid, "session");
-    requireConfirm(confirm, "oko_start_session", { eventId, title: event.title ?? null });
+    requireConfirm(confirm, "oko_start_session", { eventId, title: event.title ?? null, endsAt: endsAt ?? null });
     if (event.activeAnalyticsSessionId)
       throw new Error("An analytics session is already active.");
     const start = httpsCallable(functions, "startAnalyticsSessionV3");
     try {
-      const result = await start({ eventId });
-      return textResult({ eventId, started: true, ...result.data });
+      const result = await start({ eventId, ...endsAt ? { plannedEndAt: Date.parse(endsAt) } : {} });
+      return textResult({
+        eventId,
+        started: true,
+        ...result.data,
+        endsAt: typeof result.data.plannedEndAt === "number" ? new Date(result.data.plannedEndAt).toISOString() : null,
+        explanation: sessionExplanation({
+          billingMode: result.data.billingMode,
+          plannedEndAt: result.data.plannedEndAt,
+          clamped: result.data.clamped
+        })
+      });
     } catch (error3) {
       const named = startSessionRefusalResult(eventId, error3);
       if (named)
@@ -121181,11 +121470,15 @@ function registerSessionTools(server2) {
   server2.registerTool("oko_end_session", {
     title: "End analytics session",
     description: toolDescription({
-      summary: "End the active analytics session and persist the session snapshot.",
+      summary: "End the active analytics session, persist the session snapshot and settle its minutes.",
       args: ["eventId: event with an active analytics session.", "confirm: must be true."],
-      returns: "eventId, sessionId, and ended=true.",
+      returns: "eventId, sessionId, ended=true, minutes, charged, forgiven, billingMode, and a plain-language line about the charge.",
       examples: ["Use after the webinar analytics window is over and the user confirms the exact event."],
-      notes: ["Destructive for the active session pointer, but it does not stop the video stream."]
+      notes: [
+        "Destructive for the active session pointer, but it does not stop the video stream.",
+        "The session's minutes (rounded from its duration; a session under 30 seconds is 0) are 1 lumen each, taken now from the wallet that pays. charged is what was taken; forgiven is what the wallet could not cover \u2014 there is no debt. billingMode free means minutes were not charged (money counting is off for this page). Ending twice is safe: the second call returns the same figures and charges nothing.",
+        "A session also ends by itself at its planned end and when the lumens run out (the report says which). Use oko_extend_session to move the planned end while it runs."
+      ]
     }),
     inputSchema: {
       eventId: eventIdField,
@@ -121203,7 +121496,62 @@ function registerSessionTools(server2) {
     requireConfirm(confirm, "oko_end_session", { eventId, sessionId, reportLocale: reportLocale ?? null });
     const end = httpsCallable(functions, "endAnalyticsSessionV3");
     const result = await end({ eventId, sessionId, ...reportLocale ? { locale: reportLocale } : {} });
-    return textResult({ eventId, ...result.data });
+    return textResult({ eventId, ...result.data, billingLine: settlementLine(result.data) });
+  });
+  server2.registerTool("oko_extend_session", {
+    title: "Extend analytics session",
+    description: toolDescription({
+      summary: "Move the planned end of the RUNNING analytics session \u2014 later (the show runs long) or earlier. Analytics never edits page settings, so this is a server call like Start and End. Extending is free; only the minutes the session actually runs are paid.",
+      args: [
+        "eventId: event with an active analytics session.",
+        "endsAt: the new end as an ISO datetime \u2014 OR \u2014",
+        "addMinutes: move the CURRENT planned end by this many minutes (1-1440). Give exactly one of the two.",
+        "confirm: must be true."
+      ],
+      returns: "eventId, sessionId, extended=true, plannedEndAt (ms), endsAt (ISO), clamped, windowEndAt.",
+      examples: ["The show is running long: oko_extend_session with addMinutes 30, then confirm."],
+      notes: [
+        "The new end must be in the future and is never later than the end of the page's show window: past it the end is moved back to the window's end and the answer says clamped:true (windowEndAt tells where) \u2014 that is not an error.",
+        "The session ends by itself at its planned end; extending is how a long show keeps its measurement. It also stops by itself when the lumens run out.",
+        "Refusals carry errorCode and whatToDo: SESSION_NOT_RUNNING (no session is running on this page \u2014 start one with oko_start_session), PLANNED_END_INVALID (the end is not in the future), OUTSIDE_SHOW_WINDOW."
+      ]
+    }),
+    inputSchema: {
+      eventId: eventIdField,
+      endsAt: external_exports.string().datetime().optional().describe("New end of the running session, ISO datetime."),
+      addMinutes: external_exports.number().int().min(1).max(1440).optional().describe("Move the current planned end by this many minutes."),
+      confirm: external_exports.boolean().optional().describe("Required true to move the end of the running session.")
+    },
+    outputSchema: basicEventOutputSchema,
+    annotations: writeTool
+  }, async ({ eventId, endsAt, addMinutes, confirm }) => {
+    const { uid } = await authed(["analytics:write", "live:control"]);
+    if (endsAt === void 0 === (addMinutes === void 0)) {
+      throw new Error("Give exactly one of endsAt (an ISO datetime) or addMinutes (minutes to add to the current end).");
+    }
+    const event = await readEvent(eventId, uid, "session");
+    const sessionId = safeString(event.activeAnalyticsSessionId);
+    if (!sessionId) {
+      throw new ToolRefusal(extendSessionRefusalResult(eventId, { code: "functions/failed-precondition", details: { reason: "session_not_running" } }));
+    }
+    requireConfirm(confirm, "oko_extend_session", { eventId, sessionId, endsAt: endsAt ?? null, addMinutes: addMinutes ?? null });
+    const extend2 = httpsCallable(functions, "extendAnalyticsSession");
+    try {
+      const result = await extend2(buildExtendRequest({ eventId, sessionId, endsAt, addMinutes }));
+      return textResult({
+        eventId,
+        sessionId,
+        extended: true,
+        ...result.data,
+        endsAt: new Date(result.data.plannedEndAt).toISOString(),
+        explanation: sessionExplanation({ billingMode: void 0, plannedEndAt: result.data.plannedEndAt, clamped: result.data.clamped })
+      });
+    } catch (error3) {
+      const named = extendSessionRefusalResult(eventId, error3);
+      if (named)
+        throw new ToolRefusal(named);
+      throw error3;
+    }
   });
   server2.registerTool("oko_fix_orphan_session", {
     title: "Fix orphan analytics session",
@@ -121729,7 +122077,7 @@ function registerTelegramTools(server2) {
 // build/tools/unpublication.js
 var TOOL2 = "oko_unpublish_event";
 var NOTHING_WILL_CHANGE = "The page and its lumens stay exactly as they are now.";
-function isRecord2(value) {
+function isRecord3(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function refusal3(eventId, body) {
@@ -121779,7 +122127,7 @@ function windowOpenRefusal(eventId, state2, windowStart) {
   });
 }
 function previewUnpublish(eventId, event, nowMs) {
-  const billing = isRecord2(event.billing) ? event.billing : {};
+  const billing = isRecord3(event.billing) ? event.billing : {};
   const state2 = billing.state === "published" || billing.state === "held" ? billing.state : "unpublished";
   if (state2 === "unpublished")
     return { kind: "already" };

package/package.json

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