@okostream/mcp 0.1.0

package/dist/tools.js

@@ -0,0 +1,1556 @@
+import { z } from "zod";
+import { addDoc, collection, deleteDoc, deleteField, documentId, doc, getDoc, getDocs, limit, orderBy, query, serverTimestamp, setDoc, startAfter, Timestamp, updateDoc, where, } from "firebase/firestore";
+import { get, endBefore, limitToLast, orderByKey, push, query as dbQuery, ref, remove, runTransaction, serverTimestamp as rtdbServerTimestamp, set, update, } from "firebase/database";
+import { httpsCallable } from "firebase/functions";
+import { ensureAuth, currentScopes } from "./auth.js";
+import { chatRtdb, firestore, functions, rtdb } from "./firebase.js";
+import { csvCell, requireConfirm, safeString, serialize, textResult } from "./utils.js";
+import { detectAndNormalize, extractIframeSrc } from "./videoUrl.js";
+const boolOrNull = z.boolean().nullable();
+const MAX_FIRESTORE_TIMELINE_BUCKETS = 1500;
+const DEFAULT_LIST_LIMIT = 30;
+const MAX_LIST_LIMIT = 100;
+const MAX_EXPORT_LIMIT = 200;
+const ANALYTICS_DEFAULT_LIMIT = 10;
+const ANALYTICS_TIMELINE_DEFAULT_LIMIT = 120;
+const readOnlyTool = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+const writeTool = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+const idempotentWriteTool = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+const destructiveTool = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+const unknownRecordSchema = z.record(z.unknown());
+const basicEventOutputSchema = z.object({
+    eventId: z.string(),
+}).passthrough();
+const updateOutputSchema = z.object({
+    id: z.string().optional(),
+    eventId: z.string().optional(),
+    updated: z.array(z.string()).optional(),
+}).passthrough();
+const createWebinarOutputSchema = {
+    id: z.string(),
+    url: z.string().url(),
+    workspaceId: z.string(),
+};
+const cursorMetaSchema = {
+    count: z.number().int().nonnegative(),
+    limit: z.number().int().positive(),
+    hasMore: z.boolean(),
+    nextCursor: z.string().nullable(),
+    has_more: z.boolean(),
+    next_cursor: z.string().nullable(),
+};
+const workspacesOutputSchema = z.object({
+    workspaces: z.array(unknownRecordSchema),
+    count: z.number().int().nonnegative(),
+}).passthrough();
+const eventsOutputSchema = z.object({
+    events: z.array(unknownRecordSchema),
+    ...cursorMetaSchema,
+}).passthrough();
+const eventOutputSchema = z.object({
+    id: z.string(),
+    url: z.string().url(),
+}).passthrough();
+const liveStateOutputSchema = z.object({
+    eventId: z.string(),
+    agg: unknownRecordSchema,
+    ctrl: unknownRecordSchema,
+    chat: unknownRecordSchema,
+}).passthrough();
+const analyticsOutputSchema = z.object({
+    sessions: z.array(unknownRecordSchema),
+    ...cursorMetaSchema,
+}).passthrough();
+const chatOutputSchema = z.object({
+    messages: z.array(unknownRecordSchema),
+    ...cursorMetaSchema,
+}).passthrough();
+const participantsOutputSchema = z.object({
+    participants: z.array(unknownRecordSchema).optional(),
+    csv: z.string().optional(),
+    ...cursorMetaSchema,
+}).passthrough();
+const leadsOutputSchema = z.object({
+    leads: z.array(unknownRecordSchema).optional(),
+    csv: z.string().optional(),
+    ...cursorMetaSchema,
+}).passthrough();
+const formFieldSchema = z.object({
+    id: z.string().min(1).optional(),
+    label: z.string().max(120),
+    type: z.enum(["text", "tel", "email", "textarea"]).default("text"),
+    required: z.boolean().default(false),
+    placeholder: z.string().max(160).nullable().optional(),
+}).strict();
+const formSchema = z.object({
+    id: z.string().min(1).optional(),
+    title: z.string().max(160).nullable().optional(),
+    description: z.string().max(1000).nullable().optional(),
+    submitLabel: z.string().max(80).nullable().optional(),
+    successText: z.string().max(500).nullable().optional(),
+    consentText: z.string().max(500).nullable().optional(),
+    consentRequired: z.boolean().default(true),
+    fields: z.array(formFieldSchema).max(30),
+}).strict();
+const workspacePermissionsSchema = z.object({
+    createEvents: z.boolean().optional(),
+    editSetup: z.boolean().optional(),
+    deleteEvents: z.boolean().optional(),
+    controlLive: z.boolean().optional(),
+    moderateChat: z.boolean().optional(),
+    startSession: z.boolean().optional(),
+    viewAnalytics: z.boolean().optional(),
+    downloadReports: z.boolean().optional(),
+    sendNotifications: z.boolean().optional(),
+}).strict().default({});
+const eventIdField = z.string().min(1).describe("OKO event document id, for example KJsAku48821hB4PXTW0S.");
+const limitField = (max = MAX_LIST_LIMIT, defaultValue = DEFAULT_LIST_LIMIT) => z.number().int().min(1).max(max).default(defaultValue).describe(`Maximum items to return, 1-${max}.`);
+const cursorField = z.string().min(1).optional().describe("Cursor returned as nextCursor by the previous page.");
+function toolDescription({ summary, args = [], returns, examples = [], notes = [], }) {
+    return [
+        summary,
+        args.length ? `Args:\n${args.map((item) => `- ${item}`).join("\n")}` : "",
+        `Returns:\n- ${returns}`,
+        examples.length ? `Examples:\n${examples.map((item) => `- ${item}`).join("\n")}` : "",
+        notes.length ? `Notes:\n${notes.map((item) => `- ${item}`).join("\n")}` : "",
+    ].filter(Boolean).join("\n\n");
+}
+function cursorMeta(count, max, hasMore, nextCursor) {
+    return {
+        count,
+        limit: max,
+        hasMore,
+        nextCursor,
+        has_more: hasMore,
+        next_cursor: nextCursor,
+    };
+}
+function pickPage(items, max) {
+    return {
+        page: items.slice(0, max),
+        hasMore: items.length > max,
+    };
+}
+function randomId() {
+    return Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+async function authed(scopes) {
+    return ensureAuth(scopes);
+}
+function normalizeVideo(videoUrl) {
+    const raw = videoUrl?.trim();
+    if (!raw)
+        return { originalUrl: null, embedUrl: null };
+    const effective = extractIframeSrc(raw) ?? raw;
+    const detected = detectAndNormalize(effective);
+    if (detected.provider !== "unknown" && !detected.normalizedUrl) {
+        throw new Error(`Could not extract a valid ${detected.provider} video id from videoUrl.`);
+    }
+    return { originalUrl: raw, embedUrl: detected.normalizedUrl ?? effective };
+}
+function eventUrl(eventId) {
+    return `https://okostream.app/event/${eventId}`;
+}
+function assertEventReadable(data, uid) {
+    const access = Array.isArray(data.accessibleBy) ? data.accessibleBy : [];
+    const editors = Array.isArray(data.editors) ? data.editors : [];
+    if (data.ownerId !== uid && !access.includes(uid) && !editors.includes(uid)) {
+        throw new Error("Event is not accessible to this organizer.");
+    }
+}
+function assertEventEditable(data, uid) {
+    const editors = Array.isArray(data.editors) ? data.editors : [];
+    if (data.ownerId !== uid && !editors.includes(uid)) {
+        throw new Error("Event is not editable by this organizer.");
+    }
+}
+async function readEvent(eventId, uid, mode = "read") {
+    const snap = await getDoc(doc(firestore, "events", eventId));
+    if (!snap.exists())
+        throw new Error("Event not found.");
+    const data = snap.data();
+    if (mode === "edit")
+        assertEventEditable(data, uid);
+    else
+        assertEventReadable(data, uid);
+    return data;
+}
+function canEditEventWithPermissions(perms) {
+    return perms.editSetup === true || perms.controlLive === true || perms.startSession === true;
+}
+async function buildWorkspaceAccess(uid, workspaceId) {
+    const accessibleBy = new Set([uid]);
+    const editors = new Set([uid]);
+    if (workspaceId === uid) {
+        return { accessibleBy: [...accessibleBy], editors: [...editors] };
+    }
+    const wsSnap = await getDoc(doc(firestore, "workspaces", workspaceId));
+    if (!wsSnap.exists())
+        throw new Error("Workspace not found or not readable.");
+    const wsOwnerId = safeString(wsSnap.data().ownerId);
+    if (wsOwnerId) {
+        accessibleBy.add(wsOwnerId);
+        editors.add(wsOwnerId);
+    }
+    if (wsOwnerId !== uid) {
+        const shareSnap = await getDoc(doc(firestore, "workspaces", workspaceId, "shares", uid));
+        const perms = (shareSnap.data()?.permissions ?? {});
+        if (!shareSnap.exists() || perms.createEvents !== true) {
+            throw new Error("This organizer lacks createEvents permission in the workspace.");
+        }
+    }
+    try {
+        const sharesSnap = await getDocs(collection(firestore, "workspaces", workspaceId, "shares"));
+        sharesSnap.forEach((share) => {
+            accessibleBy.add(share.id);
+            const perms = (share.data().permissions ?? {});
+            if (canEditEventWithPermissions(perms))
+                editors.add(share.id);
+        });
+    }
+    catch {
+        // Non-owner members cannot read all shares. CF20 will backfill accessibleBy/editors.
+    }
+    return { accessibleBy: [...accessibleBy], editors: [...editors] };
+}
+async function readAgg(eventId) {
+    const snap = await get(ref(rtdb, `events/${eventId}/agg`));
+    const agg = (snap.val() ?? {});
+    const cardsById = readNestedClicks(agg.cards);
+    const ctaById = readNestedClicks(agg.cta);
+    return {
+        chatMessages: Number(agg.chatMessages ?? 0),
+        bannerClicks: Number(agg.bannerClicks ?? 0),
+        bannerImpressions: Number(agg.bannerImpressions ?? 0),
+        ctaClicks: Number(agg.ctaClicks ?? 0),
+        cardsClicks: Number(agg.cardsClicks ?? 0),
+        viewCount: Number(agg.viewCount ?? 0),
+        viewSumSec: Number(agg.viewSumSec ?? 0),
+        online: Number(agg.online ?? 0),
+        uniqueVisitors: Number(agg.uniqueVisitors ?? 0),
+        viewHist: numberRecord(agg.viewHist),
+        geo: numberRecord(agg.geo),
+        cardsById,
+        ctaById,
+    };
+}
+async function getChatRole(eventId, uid) {
+    const snap = await get(ref(chatRtdb, `settings/${eventId}/roles/${uid}`));
+    return typeof snap.val() === "string" ? snap.val() : "viewer";
+}
+function csvRows(headers, rows) {
+    return [headers, ...rows].map((row) => row.map(csvCell).join(",")).join("\n");
+}
+function numberRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (typeof raw === "number" && Number.isFinite(raw))
+            out[key] = raw;
+    }
+    return out;
+}
+function readNestedClicks(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const out = {};
+    for (const [id, raw] of Object.entries(value)) {
+        if (typeof raw === "number" && Number.isFinite(raw)) {
+            out[id] = raw;
+            continue;
+        }
+        if (raw && typeof raw === "object" && typeof raw.clicks === "number") {
+            out[id] = raw.clicks;
+        }
+    }
+    return out;
+}
+function cleanForFirestore(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(cleanForFirestore).filter((item) => item !== undefined);
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        const cleaned = cleanForFirestore(item);
+        if (cleaned !== undefined)
+            out[key] = cleaned;
+    }
+    return out;
+}
+function downsampleTimeline(buckets, maxBuckets = MAX_FIRESTORE_TIMELINE_BUCKETS) {
+    if (buckets.length <= maxBuckets)
+        return buckets;
+    if (maxBuckets < 2)
+        return buckets.slice(-maxBuckets);
+    const result = [];
+    const lastIndex = buckets.length - 1;
+    for (let i = 0; i < maxBuckets; i++) {
+        const idx = Math.round((i * lastIndex) / (maxBuckets - 1));
+        const bucket = buckets[idx];
+        if (bucket && result[result.length - 1] !== bucket)
+            result.push(bucket);
+    }
+    return result;
+}
+function isTimelineBucket(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const data = value;
+    return typeof data.t === "number"
+        && typeof data.v === "number"
+        && typeof data.c === "number"
+        && typeof data.bi === "number"
+        && typeof data.bc === "number"
+        && typeof data.cta === "number";
+}
+function toMillis(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (value && typeof value === "object" && typeof value.toMillis === "function") {
+        return value.toMillis();
+    }
+    return null;
+}
+function parseTimestampCursor(cursor) {
+    const millis = Number(cursor);
+    if (Number.isFinite(millis) && millis > 0)
+        return Timestamp.fromMillis(millis);
+    const parsed = Date.parse(cursor);
+    if (Number.isFinite(parsed))
+        return Timestamp.fromMillis(parsed);
+    throw new Error("Invalid cursor. Use the nextCursor value returned by the previous page.");
+}
+function timestampCursorFrom(value) {
+    const millis = toMillis(value);
+    return millis == null ? null : String(millis);
+}
+function readNmoCriteria(raw) {
+    const data = (raw && typeof raw === "object" ? raw : {});
+    return {
+        minWatchTimeRatio: typeof data.minWatchTimeRatio === "number" ? data.minWatchTimeRatio : 0.8,
+        minCheckpointRatio: typeof data.minCheckpointRatio === "number" ? data.minCheckpointRatio : 0.8,
+    };
+}
+function checkpointResponseInWindow(responses, startMs, endMs) {
+    return Object.values(responses).some((response) => {
+        const ts = typeof response.respondedAt === "number" ? response.respondedAt : response.shownAt;
+        return typeof ts === "number" && ts >= startMs - 5_000 && ts <= endMs + 60_000;
+    });
+}
+async function buildNmoEvaluation({ eventId, sessionId, startMs, endMs, durationSec, baselineEngagement, finalEngagement, }) {
+    const eventSnap = await getDoc(doc(firestore, "events", eventId));
+    const event = eventSnap.data() ?? {};
+    if (event.nmoMode !== true)
+        return null;
+    const criteria = readNmoCriteria(event.nmoCriteria);
+    const [participantsSnap, checkpointsSnap, windowsSnap] = await Promise.all([
+        getDocs(query(collection(firestore, "eventParticipants", eventId, "items"), orderBy("fullName"))),
+        get(ref(rtdb, `events/${eventId}/checkpoints`)),
+        get(ref(rtdb, `events/${eventId}/checkpointWindows`)),
+    ]);
+    const participants = participantsSnap.docs.map((item) => ({ uid: item.id, ...item.data() }));
+    const checkpoints = (checkpointsSnap.val() ?? {});
+    const windows = (windowsSnap.val() ?? {});
+    let checkpointIds = Object.entries(windows)
+        .filter(([, window]) => {
+        if (window.sessionId)
+            return window.sessionId === sessionId;
+        return typeof window.startedAt === "number" && startMs != null && window.startedAt >= startMs && window.startedAt <= endMs;
+    })
+        .map(([id]) => id);
+    if (checkpointIds.length === 0 && startMs != null) {
+        checkpointIds = Object.entries(checkpoints)
+            .filter(([, responses]) => checkpointResponseInWindow(responses, startMs, endMs))
+            .map(([id]) => id);
+    }
+    checkpointIds = [...new Set(checkpointIds)].sort();
+    const totalCheckpoints = checkpointIds.length;
+    const rows = participants.map((participant) => {
+        const uid = safeString(participant.uid);
+        const watchSec = Math.max(0, (finalEngagement[uid] ?? 0) - (baselineEngagement[uid] ?? 0));
+        const watchRatio = durationSec > 0 ? watchSec / durationSec : 0;
+        let confirmedCount = 0;
+        let reactionSum = 0;
+        let reactionCount = 0;
+        for (const checkpointId of checkpointIds) {
+            const response = checkpoints[checkpointId]?.[uid];
+            if (response?.status === "confirmed" || response?.status === "auto_confirmed")
+                confirmedCount++;
+            if (typeof response?.reactionMs === "number" && response.reactionMs > 0) {
+                reactionSum += response.reactionMs;
+                reactionCount++;
+            }
+        }
+        const checkpointRatio = totalCheckpoints > 0 ? confirmedCount / totalCheckpoints : 1;
+        const avgReactionSec = reactionCount > 0 ? Math.round((reactionSum / reactionCount) / 100) / 10 : null;
+        const status = watchSec === 0
+            ? "noShow"
+            : watchRatio >= criteria.minWatchTimeRatio && checkpointRatio >= criteria.minCheckpointRatio
+                ? "passed"
+                : "failed";
+        return {
+            uid,
+            email: safeString(participant.email),
+            fullName: safeString(participant.fullName),
+            ...(safeString(participant.position) && { position: safeString(participant.position) }),
+            ...(safeString(participant.org) && { org: safeString(participant.org) }),
+            watchSec,
+            watchRatio,
+            confirmedCount,
+            totalCheckpoints,
+            checkpointRatio,
+            avgReactionSec,
+            status,
+        };
+    });
+    return {
+        generatedAtMs: endMs,
+        source: "sessionSnapshotV1",
+        criteria,
+        sessionDurationSec: durationSec,
+        checkpointIds,
+        summary: {
+            passed: rows.filter((row) => row.status === "passed").length,
+            failed: rows.filter((row) => row.status === "failed").length,
+            noShow: rows.filter((row) => row.status === "noShow").length,
+            total: rows.length,
+        },
+        rows,
+    };
+}
+function compactAnalyticsSession(raw, options) {
+    const session = serialize(raw);
+    const timeline = Array.isArray(session.timeline) ? session.timeline : null;
+    if (timeline) {
+        session.timelineBucketCount = timeline.length;
+        if (options.includeTimeline) {
+            const page = timeline.slice(-options.timelineLimit);
+            session.timeline = page;
+            session.timelineTruncated = timeline.length > page.length;
+            session.timelineReturned = page.length;
+        }
+        else {
+            delete session.timeline;
+            session.timelineOmitted = true;
+        }
+    }
+    if (!options.includeSnapshots) {
+        if (session.baselineSnapshot !== undefined) {
+            delete session.baselineSnapshot;
+            session.baselineSnapshotOmitted = true;
+        }
+        if (session.finalSnapshot !== undefined) {
+            delete session.finalSnapshot;
+            session.finalSnapshotOmitted = true;
+        }
+    }
+    const nmo = session.nmoEvaluation;
+    if (!options.includeNmoRows && nmo && typeof nmo === "object" && !Array.isArray(nmo)) {
+        const nmoRecord = nmo;
+        if (Array.isArray(nmoRecord.rows)) {
+            nmoRecord.rowsCount = nmoRecord.rows.length;
+            delete nmoRecord.rows;
+            nmoRecord.rowsOmitted = true;
+        }
+    }
+    return session;
+}
+export function registerTools(server) {
+    server.registerTool("oko_whoami", {
+        title: "Who am I",
+        description: toolDescription({
+            summary: "Return the authenticated OKO organizer uid and granted MCP scopes.",
+            returns: "uid plus the exact scopes granted by OKO API key exchange. Use this before write workflows to check permissions.",
+            examples: ['Use when starting a session: call first, then choose tools allowed by "scopes".'],
+        }),
+        outputSchema: {
+            uid: z.string(),
+            scopes: z.array(z.string()),
+        },
+        annotations: readOnlyTool,
+    }, async () => {
+        const auth = await authed([]);
+        return textResult({ uid: auth.uid, scopes: currentScopes() });
+    });
+    server.registerTool("oko_list_workspaces", {
+        title: "List workspaces",
+        description: toolDescription({
+            summary: "List OKO workspaces visible to the authenticated organizer.",
+            args: ["includeShared: include workspaces shared with this organizer, default true."],
+            returns: "workspaces array with id, ownership flag, and permissions for shared workspaces, plus count.",
+            examples: ["Use before oko_create_webinar when the user wants to create a webinar in a shared workspace."],
+        }),
+        inputSchema: { includeShared: z.boolean().default(true).describe("Include workspaces shared with this organizer.") },
+        outputSchema: workspacesOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ includeShared }) => {
+        const { uid } = await authed(["workspace:read"]);
+        const out = [];
+        const ownedSnap = await getDocs(query(collection(firestore, "workspaces"), where("ownerId", "==", uid)));
+        ownedSnap.forEach((item) => out.push({ id: item.id, ...serialize(item.data()), isOwner: true }));
+        if (includeShared) {
+            const profileSnap = await getDoc(doc(firestore, "userProfiles", uid));
+            const sharedIds = (profileSnap.data()?.sharedWorkspaceIds ?? []);
+            for (const workspaceId of sharedIds) {
+                if (out.some((row) => typeof row === "object" && row !== null && row.id === workspaceId))
+                    continue;
+                const wsSnap = await getDoc(doc(firestore, "workspaces", workspaceId));
+                const shareSnap = await getDoc(doc(firestore, "workspaces", workspaceId, "shares", uid));
+                if (wsSnap.exists())
+                    out.push({ id: workspaceId, ...serialize(wsSnap.data()), isOwner: false, permissions: serialize(shareSnap.data()?.permissions ?? {}) });
+            }
+        }
+        return textResult({ workspaces: out, count: out.length });
+    });
+    server.registerTool("oko_list_my_events", {
+        title: "List my events",
+        description: toolDescription({
+            summary: "List OKO events visible to the authenticated organizer.",
+            args: [
+                "limit: maximum events to return, default 30, max 100.",
+                "cursor: timestamp cursor returned as nextCursor by the previous page.",
+                "workspaceId: optional client-side workspace filter.",
+            ],
+            returns: "events plus count, limit, hasMore/has_more, nextCursor/next_cursor.",
+            examples: ["Use limit=10 first; if hasMore is true, call again with cursor=nextCursor."],
+        }),
+        inputSchema: {
+            limit: limitField(),
+            cursor: cursorField,
+            workspaceId: z.string().optional().describe("Optional workspace id to filter returned events."),
+        },
+        outputSchema: eventsOutputSchema,
+        annotations: readOnlyTool,
+    }, async (args) => {
+        const { uid } = await authed(["events:read"]);
+        const constraints = [
+            where("accessibleBy", "array-contains", uid),
+            orderBy("createdAt", "desc"),
+            limit(args.limit + 1),
+        ];
+        if (args.cursor)
+            constraints.splice(2, 0, startAfter(parseTimestampCursor(args.cursor)));
+        const snap = await getDocs(query(collection(firestore, "events"), ...constraints));
+        const { page, hasMore } = pickPage(snap.docs, args.limit);
+        let events = page.map((item) => ({ id: item.id, ...serialize(item.data()) }));
+        if (args.workspaceId)
+            events = events.filter((event) => event.workspaceId === args.workspaceId);
+        const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data().createdAt) : null;
+        return textResult({ events, ...cursorMeta(events.length, args.limit, hasMore, nextCursor) });
+    });
+    server.registerTool("oko_get_event", {
+        title: "Get event",
+        description: toolDescription({
+            summary: "Read one OKO event visible to the organizer.",
+            args: ["eventId: OKO event document id."],
+            returns: "full event document fields plus id and public event URL.",
+            examples: ["Use after oko_create_webinar to verify setup and return the event URL to the user."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: eventOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["events:read"]);
+        const data = await readEvent(eventId, uid, "read");
+        return textResult({ id: eventId, ...serialize(data), url: eventUrl(eventId) });
+    });
+    server.registerTool("oko_create_webinar", {
+        title: "Create webinar",
+        description: toolDescription({
+            summary: "Create an OKO webinar and its required RTDB owner/workspace mirror.",
+            args: [
+                "title: webinar title.",
+                "workspaceId: optional workspace id; omitted means personal workspace.",
+                "videoUrl: optional iframe/source/player URL; normalized by OKO.",
+                "eventDate: optional ISO datetime.",
+                "chatEnabled: whether the chat block is enabled at creation.",
+            ],
+            returns: "new event id, public event URL, and workspaceId.",
+            examples: ["Use for a complete create flow, then call oko_configure_blocks and oko_get_event."],
+            notes: ["This creates an event page; OKO has no draft/live/ended event status."],
+        }),
+        inputSchema: {
+            title: z.string().min(1).max(160).describe("Webinar title shown on the public event page."),
+            workspaceId: z.string().optional().describe("Workspace id; omit for the organizer's personal workspace."),
+            videoUrl: z.string().nullable().optional().describe("Optional source/player/iframe URL to normalize."),
+            eventDate: z.string().datetime().nullable().optional().describe("Optional webinar datetime in ISO format."),
+            speakerName: z.string().max(160).nullable().optional().describe("Optional speaker display name."),
+            description: z.string().max(3000).nullable().optional().describe("Optional event description."),
+            chatEnabled: z.boolean().default(false).describe("Whether the chat block starts enabled."),
+        },
+        outputSchema: createWebinarOutputSchema,
+        annotations: writeTool,
+    }, async (args) => {
+        const { uid } = await authed(["events:write"]);
+        const workspaceId = args.workspaceId ?? uid;
+        const access = await buildWorkspaceAccess(uid, workspaceId);
+        const video = normalizeVideo(args.videoUrl);
+        const docRef = await addDoc(collection(firestore, "events"), {
+            ownerId: uid,
+            workspaceId,
+            accessibleBy: access.accessibleBy,
+            editors: access.editors,
+            createdAt: serverTimestamp(),
+            title: args.title.trim(),
+            pinned: false,
+            video,
+            meta: {
+                eventDate: args.eventDate ? Timestamp.fromDate(new Date(args.eventDate)) : null,
+                speakerName: args.speakerName?.trim() || null,
+                description: args.description?.trim() || null,
+            },
+            blocks: {
+                chat: { enabled: args.chatEnabled, visibility: "always" },
+                promoBanner: { enabled: false, text: "", link: "", visibility: "always" },
+            },
+        });
+        await update(ref(rtdb, `events/${docRef.id}`), {
+            ownerId: uid,
+            workspaceId,
+        });
+        return textResult({ id: docRef.id, url: eventUrl(docRef.id), workspaceId });
+    });
+    server.registerTool("oko_update_event", {
+        title: "Update event metadata",
+        description: toolDescription({
+            summary: "Update safe top-level event/setup metadata fields.",
+            args: ["eventId plus any subset of title, videoUrl, eventDate, speakerName, description, pinned."],
+            returns: "event id and the list of Firestore fields updated.",
+            examples: ["Use for title/date/speaker/video edits; use oko_configure_blocks for block/form/NMO setup."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            title: z.string().min(1).max(160).optional().describe("New webinar title."),
+            videoUrl: z.string().nullable().optional().describe("New source/player/iframe URL, or null to clear."),
+            eventDate: z.string().datetime().nullable().optional().describe("New ISO datetime, or null to clear."),
+            speakerName: z.string().max(160).nullable().optional().describe("New speaker display name, or null to clear."),
+            description: z.string().max(3000).nullable().optional().describe("New description, or null to clear."),
+            pinned: z.boolean().optional().describe("Whether this event is pinned in the dashboard."),
+        },
+        outputSchema: updateOutputSchema,
+        annotations: writeTool,
+    }, async (args) => {
+        const { uid } = await authed(["events:write", "setup:write"]);
+        const data = await readEvent(args.eventId, uid, "edit");
+        const patch = {};
+        if (args.title !== undefined)
+            patch.title = args.title.trim();
+        if (args.videoUrl !== undefined) {
+            const video = normalizeVideo(args.videoUrl);
+            patch["video.originalUrl"] = video.originalUrl;
+            patch["video.embedUrl"] = video.embedUrl;
+        }
+        if (args.eventDate !== undefined)
+            patch["meta.eventDate"] = args.eventDate ? Timestamp.fromDate(new Date(args.eventDate)) : null;
+        if (args.speakerName !== undefined)
+            patch["meta.speakerName"] = args.speakerName?.trim() || null;
+        if (args.description !== undefined)
+            patch["meta.description"] = args.description?.trim() || null;
+        if (args.pinned !== undefined)
+            patch.pinned = args.pinned;
+        await updateDoc(doc(firestore, "events", args.eventId), patch);
+        await update(ref(rtdb, `events/${args.eventId}`), {
+            ownerId: safeString(data.ownerId, uid),
+            workspaceId: safeString(data.workspaceId, uid),
+        });
+        return textResult({ id: args.eventId, updated: Object.keys(patch) });
+    });
+    server.registerTool("oko_configure_blocks", {
+        title: "Configure event blocks",
+        description: toolDescription({
+            summary: "Configure supported event setup blocks, forms, Telegram channel ids, and NMO mode.",
+            args: [
+                "eventId: event to edit.",
+                "chat/promoBanner/primaryCta/videoPlaceholder: optional block patches.",
+                "forms: replaces configured lead forms when provided.",
+                "telegramChannelIds: replaces configured Telegram channels when provided.",
+                "nmo: optional NMO mode and criteria patch.",
+            ],
+            returns: "event id and the list of Firestore fields updated.",
+            examples: ["Use after oko_create_webinar to set chat visibility, CTA/form binding, or NMO settings."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            chat: z.object({ enabled: z.boolean().optional(), visibility: z.enum(["always", "hidden"]).optional() }).optional(),
+            promoBanner: z.object({ enabled: z.boolean().optional(), link: z.string().max(1000).optional(), visibility: z.enum(["always", "hidden"]).optional(), formId: z.string().nullable().optional() }).optional(),
+            primaryCta: z.object({ enabled: z.boolean().optional(), visibility: z.enum(["always", "hidden"]).optional(), title: z.string().nullable().optional(), text: z.string().nullable().optional(), buttonLabel: z.string().nullable().optional(), buttonUrl: z.string().nullable().optional(), formId: z.string().nullable().optional() }).optional(),
+            videoPlaceholder: z.object({ enabled: z.boolean().optional(), mode: z.enum(["glass", "image"]).optional(), title: z.string().nullable().optional(), subtitle: z.string().nullable().optional(), showTimer: z.boolean().optional() }).optional(),
+            forms: z.array(formSchema).max(20).optional(),
+            telegramChannelIds: z.array(z.number().int()).max(20).optional(),
+            nmo: z.object({
+                enabled: z.boolean().optional(),
+                minWatchTimeRatio: z.number().min(0).max(1).optional(),
+                minCheckpointRatio: z.number().min(0).max(1).optional(),
+                extraPosition: z.boolean().optional(),
+                extraOrg: z.boolean().optional(),
+            }).optional(),
+        },
+        outputSchema: updateOutputSchema,
+        annotations: writeTool,
+    }, async (args) => {
+        const { uid } = await authed(["setup:write"]);
+        await readEvent(args.eventId, uid, "edit");
+        const patch = {};
+        if (args.chat?.enabled !== undefined)
+            patch["blocks.chat.enabled"] = args.chat.enabled;
+        if (args.chat?.visibility !== undefined)
+            patch["blocks.chat.visibility"] = args.chat.visibility;
+        if (args.promoBanner?.enabled !== undefined)
+            patch["blocks.promoBanner.enabled"] = args.promoBanner.enabled;
+        if (args.promoBanner?.link !== undefined)
+            patch["blocks.promoBanner.link"] = args.promoBanner.link;
+        if (args.promoBanner?.visibility !== undefined)
+            patch["blocks.promoBanner.visibility"] = args.promoBanner.visibility;
+        if (args.promoBanner?.formId !== undefined)
+            patch["blocks.promoBanner.formId"] = args.promoBanner.formId;
+        if (args.primaryCta?.enabled !== undefined)
+            patch["blocks.primaryCta.enabled"] = args.primaryCta.enabled;
+        if (args.primaryCta?.visibility !== undefined)
+            patch["blocks.primaryCta.visibility"] = args.primaryCta.visibility;
+        if (args.primaryCta?.title !== undefined)
+            patch["blocks.primaryCta.title"] = args.primaryCta.title?.trim() || null;
+        if (args.primaryCta?.text !== undefined)
+            patch["blocks.primaryCta.text"] = args.primaryCta.text?.trim() || null;
+        if (args.primaryCta?.buttonLabel !== undefined)
+            patch["blocks.primaryCta.buttonLabel"] = args.primaryCta.buttonLabel?.trim() || null;
+        if (args.primaryCta?.buttonUrl !== undefined)
+            patch["blocks.primaryCta.buttonUrl"] = args.primaryCta.buttonUrl?.trim() || null;
+        if (args.primaryCta?.formId !== undefined)
+            patch["blocks.primaryCta.formId"] = args.primaryCta.formId;
+        if (args.videoPlaceholder?.enabled !== undefined)
+            patch["blocks.video.placeholder.enabled"] = args.videoPlaceholder.enabled;
+        if (args.videoPlaceholder?.mode !== undefined)
+            patch["blocks.video.placeholder.mode"] = args.videoPlaceholder.mode;
+        if (args.videoPlaceholder?.title !== undefined)
+            patch["blocks.video.placeholder.title"] = args.videoPlaceholder.title?.trim() || null;
+        if (args.videoPlaceholder?.subtitle !== undefined)
+            patch["blocks.video.placeholder.subtitle"] = args.videoPlaceholder.subtitle?.trim() || null;
+        if (args.videoPlaceholder?.showTimer !== undefined)
+            patch["blocks.video.placeholder.showTimer"] = args.videoPlaceholder.showTimer;
+        if (args.forms !== undefined)
+            patch.forms = args.forms.map((form) => ({
+                id: form.id ?? randomId(),
+                type: "lead",
+                title: form.title?.trim() || null,
+                description: form.description?.trim() || null,
+                submitLabel: form.submitLabel?.trim() || null,
+                successText: form.successText?.trim() || null,
+                consentText: form.consentText?.trim() || null,
+                consentRequired: form.consentRequired !== false,
+                fields: form.fields.map((field) => ({
+                    id: field.id ?? randomId(),
+                    label: field.label.trim(),
+                    type: field.type,
+                    required: field.required === true,
+                    placeholder: field.placeholder?.trim() || null,
+                })),
+            }));
+        if (args.telegramChannelIds !== undefined) {
+            patch["telegram.enabled"] = args.telegramChannelIds.length > 0;
+            patch["telegram.channelIds"] = args.telegramChannelIds;
+            patch["telegram.channelId"] = args.telegramChannelIds[0] ?? null;
+        }
+        if (args.nmo?.enabled !== undefined)
+            patch.nmoMode = args.nmo.enabled;
+        if (args.nmo?.minWatchTimeRatio !== undefined)
+            patch["nmoCriteria.minWatchTimeRatio"] = args.nmo.minWatchTimeRatio;
+        if (args.nmo?.minCheckpointRatio !== undefined)
+            patch["nmoCriteria.minCheckpointRatio"] = args.nmo.minCheckpointRatio;
+        if (args.nmo?.extraPosition !== undefined)
+            patch["nmoExtraFields.position"] = args.nmo.extraPosition;
+        if (args.nmo?.extraOrg !== undefined)
+            patch["nmoExtraFields.org"] = args.nmo.extraOrg;
+        await updateDoc(doc(firestore, "events", args.eventId), patch);
+        return textResult({ id: args.eventId, updated: Object.keys(patch) });
+    });
+    server.registerTool("oko_delete_event", {
+        title: "Delete event",
+        description: toolDescription({
+            summary: "Delete an OKO event document.",
+            args: ["eventId: event to delete.", "confirm: must be true."],
+            returns: "deleted event id.",
+            examples: ["Use only after the user explicitly confirms the exact event title/id."],
+            notes: ["Destructive. Does not control stream state; it deletes the event record."],
+        }),
+        inputSchema: { eventId: eventIdField, confirm: z.boolean().optional().describe("Required true for deletion.") },
+        outputSchema: z.object({ deleted: z.string() }).passthrough(),
+        annotations: destructiveTool,
+    }, async ({ eventId, confirm }) => {
+        const { uid } = await authed(["events:delete"]);
+        const data = await readEvent(eventId, uid, "edit");
+        requireConfirm(confirm, "oko_delete_event", { eventId, title: data.title });
+        await deleteDoc(doc(firestore, "events", eventId));
+        return textResult({ deleted: eventId });
+    });
+    server.registerTool("oko_get_live_state", {
+        title: "Get live state",
+        description: toolDescription({
+            summary: "Read main RTDB live controls, aggregate analytics, and chat settings for an event.",
+            args: ["eventId: event to inspect."],
+            returns: "eventId, agg metrics, ctrl live overrides, and chat settings.",
+            examples: ["Use during a webinar before changing live block visibility or starting/ending sessions."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: liveStateOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["analytics:read"]);
+        await readEvent(eventId, uid, "read");
+        const [aggSnap, ctrlSnap, chatSettingsSnap] = await Promise.all([
+            get(ref(rtdb, `events/${eventId}/agg`)),
+            get(ref(rtdb, `events/${eventId}/ctrl`)),
+            get(ref(chatRtdb, `settings/${eventId}`)),
+        ]);
+        return textResult({ eventId, agg: aggSnap.val() ?? {}, ctrl: ctrlSnap.val() ?? {}, chat: chatSettingsSnap.val() ?? {} });
+    });
+    server.registerTool("oko_set_block_visibility", {
+        title: "Set live block visibility",
+        description: toolDescription({
+            summary: "Set or reset a live RTDB visibility override for a public event block.",
+            args: ["eventId: event to control.", "block: chat, banner, cta, cards, or placeholder.", "visible: true/false, or null to reset override."],
+            returns: "eventId, block, and effective override value.",
+            examples: ["Use visible=false to hide the CTA live; use visible=null to return to setup defaults."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            block: z.enum(["chat", "banner", "cta", "cards", "placeholder"]).describe("Public block whose live override should change."),
+            visible: boolOrNull.describe("true/false to force visibility, null to reset override."),
+        },
+        outputSchema: basicEventOutputSchema,
+        annotations: idempotentWriteTool,
+    }, async ({ eventId, block, visible }) => {
+        const { uid } = await authed(["live:control"]);
+        await readEvent(eventId, uid, "edit");
+        const paths = {
+            chat: "chatVisible",
+            banner: "bannerVisible",
+            cta: "ctaVisible",
+            cards: "cardsVisible",
+            placeholder: "placeholderVisible",
+        };
+        const target = ref(rtdb, `events/${eventId}/ctrl/${paths[block]}`);
+        if (visible === null)
+            await remove(target);
+        else
+            await set(target, visible);
+        return textResult({ eventId, block, visible });
+    });
+    server.registerTool("oko_refresh_viewers", {
+        title: "Refresh viewers",
+        description: toolDescription({
+            summary: "Trigger a live viewer refresh tick for an event.",
+            args: ["eventId: event whose viewers should refresh."],
+            returns: "eventId and refreshed=true.",
+            examples: ["Use after a setup/live change if viewers should reload state immediately."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: basicEventOutputSchema,
+        annotations: writeTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["live:control"]);
+        await readEvent(eventId, uid, "edit");
+        await set(ref(rtdb, `events/${eventId}/ctrl/refreshTick`), Date.now());
+        return textResult({ eventId, refreshed: true });
+    });
+    server.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."],
+            returns: "eventId, new sessionId, and started=true.",
+            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."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: basicEventOutputSchema,
+        annotations: writeTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["analytics:write", "live:control"]);
+        const event = await readEvent(eventId, uid, "edit");
+        if (event.activeAnalyticsSessionId)
+            throw new Error("An analytics session is already active.");
+        let sessionId = null;
+        try {
+            const agg = await readAgg(eventId);
+            const sessionRef = await addDoc(collection(firestore, "events", eventId, "analyticsSessions"), {
+                startedAt: serverTimestamp(),
+                endedAt: null,
+            });
+            sessionId = sessionRef.id;
+            const updates = {
+                "ctrl/activeSessionId": sessionId,
+                [`sessions/${sessionId}/startedAt`]: Date.now(),
+                [`sessions/${sessionId}/baseline/chatMessages`]: agg.chatMessages,
+                [`sessions/${sessionId}/baseline/bannerClicks`]: agg.bannerClicks,
+                [`sessions/${sessionId}/baseline/bannerImpressions`]: agg.bannerImpressions,
+                [`sessions/${sessionId}/baseline/ctaClicks`]: agg.ctaClicks,
+                [`sessions/${sessionId}/baseline/cardsClicks`]: agg.cardsClicks,
+                [`sessions/${sessionId}/baseline/viewCount`]: agg.viewCount,
+                [`sessions/${sessionId}/baseline/viewSumSec`]: agg.viewSumSec,
+                [`sessions/${sessionId}/baseline/online`]: agg.online,
+                [`sessions/${sessionId}/baseline/uniqueVisitors`]: agg.uniqueVisitors,
+                [`sessions/${sessionId}/peak`]: agg.online,
+            };
+            for (const [bucket, count] of Object.entries(agg.viewHist)) {
+                updates[`sessions/${sessionId}/baseline/viewHist/${bucket}`] = count;
+            }
+            for (const [cityKey, count] of Object.entries(agg.geo ?? {})) {
+                updates[`sessions/${sessionId}/baseline/geo/${cityKey}`] = count;
+            }
+            for (const [cardId, clicks] of Object.entries(agg.cardsById ?? {})) {
+                updates[`sessions/${sessionId}/baseline/cardsById/${cardId}`] = clicks;
+            }
+            for (const [ctaId, clicks] of Object.entries(agg.ctaById ?? {})) {
+                updates[`sessions/${sessionId}/baseline/ctaById/${ctaId}`] = clicks;
+            }
+            await update(ref(rtdb, `events/${eventId}`), updates);
+            try {
+                const engagementSnap = await get(ref(rtdb, `events/${eventId}/engagement`));
+                const engagementNow = numberRecord(engagementSnap.val());
+                const engagementUpdates = {};
+                for (const [viewerId, seconds] of Object.entries(engagementNow)) {
+                    engagementUpdates[`sessions/${sessionId}/baseline/engagement/${viewerId}`] = seconds;
+                }
+                if (Object.keys(engagementUpdates).length > 0) {
+                    await update(ref(rtdb, `events/${eventId}`), engagementUpdates);
+                }
+            }
+            catch {
+                // Non-fatal: dashboard behaves the same; avg/median are skipped if baseline is unavailable.
+            }
+            await updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: sessionId });
+            try {
+                await set(ref(rtdb, `activeSessions/${sessionId}`), { eventId, startedAt: Date.now() });
+            }
+            catch {
+                // Non-fatal: client-side sampler can still write timeline, and CF stale cleanup is best-effort.
+            }
+            return textResult({ eventId, sessionId, started: true });
+        }
+        catch (err) {
+            if (sessionId) {
+                await Promise.allSettled([
+                    remove(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`)),
+                    remove(ref(rtdb, `events/${eventId}/sessions/${sessionId}`)),
+                    remove(ref(rtdb, `activeSessions/${sessionId}`)),
+                    updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() }),
+                    deleteDoc(doc(firestore, "events", eventId, "analyticsSessions", sessionId)),
+                ]);
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Start failed: ${msg}`);
+        }
+    });
+    server.registerTool("oko_end_session", {
+        title: "End analytics session",
+        description: toolDescription({
+            summary: "End the active analytics session and persist the session snapshot.",
+            args: ["eventId: event with an active analytics session.", "confirm: must be true."],
+            returns: "eventId, sessionId, and ended=true.",
+            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."],
+        }),
+        inputSchema: { eventId: eventIdField, confirm: z.boolean().optional().describe("Required true for ending the active session.") },
+        outputSchema: basicEventOutputSchema,
+        annotations: destructiveTool,
+    }, async ({ eventId, confirm }) => {
+        const { uid } = await authed(["analytics:write", "live:control"]);
+        const event = await readEvent(eventId, uid, "edit");
+        const sessionId = safeString(event.activeAnalyticsSessionId);
+        if (!sessionId)
+            throw new Error("No active analytics session.");
+        requireConfirm(confirm, "oko_end_session", { eventId, sessionId });
+        const sessionDocRef = doc(firestore, "events", eventId, "analyticsSessions", sessionId);
+        const [finalAgg, baselineSnap, sessionSnap, firestoreSessionSnap] = await Promise.all([
+            readAgg(eventId),
+            get(ref(rtdb, `events/${eventId}/sessions/${sessionId}/baseline`)),
+            get(ref(rtdb, `events/${eventId}/sessions/${sessionId}`)),
+            getDoc(sessionDocRef),
+        ]);
+        if (!baselineSnap.exists()) {
+            throw new Error("Session baseline is missing; clear the stuck session and start a fresh session.");
+        }
+        const baseRaw = (baselineSnap.val() ?? {});
+        const baseline = {
+            chatMessages: Number(baseRaw.chatMessages ?? 0),
+            bannerClicks: Number(baseRaw.bannerClicks ?? 0),
+            bannerImpressions: Number(baseRaw.bannerImpressions ?? 0),
+            ctaClicks: Number(baseRaw.ctaClicks ?? 0),
+            cardsClicks: Number(baseRaw.cardsClicks ?? 0),
+            viewCount: Number(baseRaw.viewCount ?? 0),
+            viewSumSec: Number(baseRaw.viewSumSec ?? 0),
+            viewHist: numberRecord(baseRaw.viewHist),
+            online: Number(baseRaw.online ?? 0),
+            uniqueVisitors: Number(baseRaw.uniqueVisitors ?? 0),
+            geo: numberRecord(baseRaw.geo),
+            cardsById: numberRecord(baseRaw.cardsById),
+            ctaById: numberRecord(baseRaw.ctaById),
+        };
+        const session = (sessionSnap.val() ?? {});
+        const timelineRaw = (session.timeline ?? {});
+        const rawSessionTimeline = Object.values(timelineRaw).filter(isTimelineBucket).sort((a, b) => a.t - b.t);
+        const sessionTimeline = downsampleTimeline(rawSessionTimeline);
+        const startMs = toMillis(firestoreSessionSnap.data()?.startedAt) ?? toMillis(session.startedAt);
+        const endMs = Date.now();
+        const durationSec = startMs != null ? Math.max(0, Math.round((endMs - startMs) / 1000)) : 0;
+        const viewCount = Math.max(0, finalAgg.viewCount - baseline.viewCount);
+        const viewSumSec = Math.max(0, finalAgg.viewSumSec - baseline.viewSumSec);
+        const bannerUniqueImpressions = Number(session.bannerUniqueImpressions ?? 0);
+        const bannerUniqueClicks = Number(session.bannerUniqueClicks ?? 0);
+        const bannerCtrDenominator = Math.max(bannerUniqueImpressions, bannerUniqueClicks);
+        const bannerCtr = bannerCtrDenominator > 0
+            ? Math.round((bannerUniqueClicks / bannerCtrDenominator) * 1000) / 10
+            : null;
+        let avgTimeSec = null;
+        let medianTimeSec = null;
+        let finalEngagement = {};
+        let baselineEngagement = {};
+        let engagementLoaded = false;
+        try {
+            const finalEngagementSnap = await get(ref(rtdb, `events/${eventId}/engagement`));
+            finalEngagement = numberRecord(finalEngagementSnap.val());
+            baselineEngagement = numberRecord(baseRaw.engagement);
+            engagementLoaded = true;
+            const sessionDurations = [];
+            for (const [viewerId, finalSeconds] of Object.entries(finalEngagement)) {
+                const delta = Math.max(0, finalSeconds - (baselineEngagement[viewerId] ?? 0));
+                if (delta >= 30)
+                    sessionDurations.push(delta);
+            }
+            if (sessionDurations.length > 0) {
+                avgTimeSec = Math.round(sessionDurations.reduce((sum, item) => sum + item, 0) / sessionDurations.length);
+                const sorted = [...sessionDurations].sort((a, b) => a - b);
+                const mid = Math.floor(sorted.length / 2);
+                medianTimeSec = sorted.length % 2 === 0
+                    ? Math.round(((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2)
+                    : sorted[mid] ?? null;
+            }
+        }
+        catch {
+            // Non-fatal: session can still be saved without avg/median.
+        }
+        const cardsBreakdown = {};
+        for (const cardId of new Set([...Object.keys(finalAgg.cardsById ?? {}), ...Object.keys(baseline.cardsById ?? {})])) {
+            const delta = Math.max(0, (finalAgg.cardsById?.[cardId] ?? 0) - (baseline.cardsById?.[cardId] ?? 0));
+            if (delta > 0)
+                cardsBreakdown[cardId] = delta;
+        }
+        const ctaBreakdown = {};
+        for (const ctaId of new Set([...Object.keys(finalAgg.ctaById ?? {}), ...Object.keys(baseline.ctaById ?? {})])) {
+            const delta = Math.max(0, (finalAgg.ctaById?.[ctaId] ?? 0) - (baseline.ctaById?.[ctaId] ?? 0));
+            if (delta > 0)
+                ctaBreakdown[ctaId] = delta;
+        }
+        const geoBreakdown = {};
+        for (const cityKey of new Set([...Object.keys(finalAgg.geo ?? {}), ...Object.keys(baseline.geo ?? {})])) {
+            const delta = Math.max(0, (finalAgg.geo?.[cityKey] ?? 0) - (baseline.geo?.[cityKey] ?? 0));
+            if (delta > 0)
+                geoBreakdown[cityKey] = delta;
+        }
+        let nmoEvaluation = null;
+        if (engagementLoaded) {
+            try {
+                nmoEvaluation = await buildNmoEvaluation({
+                    eventId,
+                    sessionId,
+                    startMs,
+                    endMs,
+                    durationSec,
+                    baselineEngagement,
+                    finalEngagement,
+                });
+            }
+            catch {
+                // Non-fatal: dashboard treats NMO snapshot failure as warning-only.
+            }
+        }
+        const finalSnapshot = {
+            chatMessages: finalAgg.chatMessages,
+            bannerClicks: finalAgg.bannerClicks,
+            bannerImpressions: finalAgg.bannerImpressions,
+            ctaClicks: finalAgg.ctaClicks,
+            cardsClicks: finalAgg.cardsClicks,
+            viewCount: finalAgg.viewCount,
+            viewSumSec: finalAgg.viewSumSec,
+            viewHist: finalAgg.viewHist,
+            uniqueVisitors: finalAgg.uniqueVisitors,
+            geo: finalAgg.geo ?? {},
+            cardsById: finalAgg.cardsById ?? {},
+            ctaById: finalAgg.ctaById ?? {},
+        };
+        const sessionUniqueVisitors = baseline.online + Number(session.uniqueVisitors ?? 0);
+        await updateDoc(sessionDocRef, {
+            endedAt: serverTimestamp(),
+            durationSec,
+            peakViewers: Number(session.peak ?? 0),
+            uniqueVisitors: sessionUniqueVisitors,
+            viewCount,
+            viewSumSec,
+            avgTimeSec,
+            medianTimeSec,
+            chatMessages: Math.max(0, finalAgg.chatMessages - baseline.chatMessages),
+            bannerImpressions: Math.max(0, finalAgg.bannerImpressions - baseline.bannerImpressions),
+            bannerUniqueImpressions,
+            bannerClicks: Math.max(0, finalAgg.bannerClicks - baseline.bannerClicks),
+            bannerUniqueClicks,
+            bannerCtr,
+            ctaClicks: Math.max(0, finalAgg.ctaClicks - baseline.ctaClicks),
+            ctaUniqueClicks: Number(session.ctaUniqueClicks ?? 0),
+            ctaBreakdown: Object.keys(ctaBreakdown).length > 0 ? ctaBreakdown : null,
+            cardsClicks: Math.max(0, finalAgg.cardsClicks - baseline.cardsClicks),
+            cardsUniqueClicks: Number(session.cardsUniqueClicks ?? 0),
+            cardsBreakdown: Object.keys(cardsBreakdown).length > 0 ? cardsBreakdown : null,
+            geo: Object.keys(geoBreakdown).length > 0 ? geoBreakdown : null,
+            baselineSnapshot: cleanForFirestore(baseline),
+            finalSnapshot: cleanForFirestore(finalSnapshot),
+            timeline: sessionTimeline,
+            timelineOriginalBucketCount: rawSessionTimeline.length,
+            ...(nmoEvaluation ? { nmoEvaluation: cleanForFirestore(nmoEvaluation) } : {}),
+        });
+        await updateDoc(doc(firestore, "events", eventId), {
+            activeAnalyticsSessionId: deleteField(),
+            "analytics.lastSessionSummary": {
+                sessionId,
+                startedAt: firestoreSessionSnap.data()?.startedAt ?? null,
+                endedAt: Timestamp.now(),
+                peakViewers: session.peak ?? null,
+                uniqueVisitors: sessionUniqueVisitors,
+                viewCount,
+                viewSumSec,
+            },
+        });
+        await Promise.allSettled([
+            remove(ref(rtdb, `activeSessions/${sessionId}`)),
+            remove(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`)),
+        ]);
+        return textResult({ eventId, sessionId, ended: true });
+    });
+    server.registerTool("oko_get_analytics", {
+        title: "Get analytics sessions",
+        description: toolDescription({
+            summary: "Read paginated analytics session summaries for an event.",
+            args: [
+                "eventId: event to inspect.",
+                "limit: max sessions to return, default 10, max 50.",
+                "cursor: timestamp cursor returned as nextCursor by the previous page.",
+                "includeTimeline: include recent timeline buckets; default false to keep context small.",
+                "timelineLimit: max timeline buckets per session when includeTimeline=true.",
+                "includeSnapshots: include baseline/final snapshots; default false.",
+                "includeNmoRows: include NMO participant rows; default false.",
+            ],
+            returns: "sessions plus count, limit, hasMore/has_more, nextCursor/next_cursor. Heavy timeline/snapshot fields are omitted unless requested.",
+            examples: ["Use default options for dashboard-like summaries; request includeTimeline only for chart/debug tasks."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            limit: limitField(50, ANALYTICS_DEFAULT_LIMIT),
+            cursor: cursorField,
+            includeTimeline: z.boolean().default(false).describe("Include recent timeline buckets for each session."),
+            timelineLimit: z.number().int().min(1).max(500).default(ANALYTICS_TIMELINE_DEFAULT_LIMIT).describe("Max timeline buckets per session when includeTimeline=true."),
+            includeSnapshots: z.boolean().default(false).describe("Include baselineSnapshot and finalSnapshot."),
+            includeNmoRows: z.boolean().default(false).describe("Include full NMO participant rows when present."),
+        },
+        outputSchema: analyticsOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId, limit: max, cursor, includeTimeline, timelineLimit, includeSnapshots, includeNmoRows }) => {
+        const { uid } = await authed(["analytics:read"]);
+        await readEvent(eventId, uid, "read");
+        const constraints = [
+            orderBy("startedAt", "desc"),
+            limit(max + 1),
+        ];
+        if (cursor)
+            constraints.splice(1, 0, startAfter(parseTimestampCursor(cursor)));
+        const snap = await getDocs(query(collection(firestore, "events", eventId, "analyticsSessions"), ...constraints));
+        const { page, hasMore } = pickPage(snap.docs, max);
+        const sessions = page.map((item) => compactAnalyticsSession({ id: item.id, ...item.data() }, { includeTimeline, timelineLimit, includeSnapshots, includeNmoRows }));
+        const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data().startedAt) : null;
+        return textResult({ sessions, ...cursorMeta(sessions.length, max, hasMore, nextCursor) }, { truncationHint: "Use limit/cursor or keep includeTimeline/includeSnapshots/includeNmoRows disabled." });
+    });
+    server.registerTool("oko_list_recent_chat", {
+        title: "List recent chat",
+        description: toolDescription({
+            summary: "Read recent chat messages from chat RTDB with cursor pagination.",
+            args: [
+                "eventId: event chat to inspect.",
+                "limit: max messages to return, default 50, max 100.",
+                "cursor: message id returned as nextCursor by the previous page to read older messages.",
+            ],
+            returns: "messages array sorted newest-first plus count, limit, hasMore/has_more, nextCursor/next_cursor.",
+            examples: ["Use limit=20 first; if hasMore is true, call again with cursor=nextCursor for older chat."],
+        }),
+        inputSchema: { eventId: eventIdField, limit: limitField(100, 50), cursor: cursorField },
+        outputSchema: chatOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId, limit: max, cursor }) => {
+        const { uid } = await authed(["analytics:read"]);
+        await readEvent(eventId, uid, "read");
+        const constraints = cursor
+            ? [orderByKey(), endBefore(cursor), limitToLast(max + 1)]
+            : [orderByKey(), limitToLast(max + 1)];
+        const snap = await get(dbQuery(ref(chatRtdb, `messages/${eventId}`), ...constraints));
+        const entries = Object.entries((snap.val() ?? {}))
+            .sort(([a], [b]) => b.localeCompare(a));
+        const { page, hasMore } = pickPage(entries, max);
+        const messages = page.map(([id, message]) => ({ id, ...serialize(message) }));
+        const nextCursor = hasMore ? messages.at(-1)?.id ?? null : null;
+        return textResult({ messages, ...cursorMeta(messages.length, max, hasMore, nextCursor) });
+    });
+    server.registerTool("oko_send_chat_message", {
+        title: "Send chat message",
+        description: toolDescription({
+            summary: "Send a chat message as the authenticated organizer/moderator.",
+            args: ["eventId: target event chat.", "text: message text, max 500 chars.", "name: display name, default OKO MCP."],
+            returns: "eventId, new messageId, and sent=true.",
+            examples: ["Use for organizer announcements in chat after user confirms the exact text."],
+        }),
+        inputSchema: { eventId: eventIdField, text: z.string().min(1).max(500).describe("Message text."), name: z.string().min(1).max(24).default("OKO MCP").describe("Display name.") },
+        outputSchema: basicEventOutputSchema,
+        annotations: writeTool,
+    }, async ({ eventId, text, name }) => {
+        const { uid } = await authed(["chat:write"]);
+        await readEvent(eventId, uid, "read");
+        const role = await getChatRole(eventId, uid);
+        const msgRef = push(ref(chatRtdb, `messages/${eventId}`));
+        await set(msgRef, { text, uid, name, role, ts: rtdbServerTimestamp() });
+        await runTransaction(ref(rtdb, `events/${eventId}/agg/chatMessages`), (n) => (n ?? 0) + 1);
+        return textResult({ eventId, messageId: msgRef.key, sent: true });
+    });
+    server.registerTool("oko_delete_chat_message", {
+        title: "Delete chat message",
+        description: toolDescription({
+            summary: "Soft-delete a chat message through moderation metadata.",
+            args: ["eventId: target event.", "messageId: chat RTDB message id.", "confirm: must be true."],
+            returns: "eventId, messageId, and deleted=true.",
+            examples: ["Use only after showing the message text/id and receiving explicit confirmation."],
+        }),
+        inputSchema: { eventId: eventIdField, messageId: z.string().min(1).describe("Chat RTDB message id."), confirm: z.boolean().optional().describe("Required true for deletion.") },
+        outputSchema: basicEventOutputSchema,
+        annotations: destructiveTool,
+    }, async ({ eventId, messageId, confirm }) => {
+        const { uid } = await authed(["chat:moderate"]);
+        await readEvent(eventId, uid, "edit");
+        requireConfirm(confirm, "oko_delete_chat_message", { eventId, messageId });
+        await set(ref(chatRtdb, `mod/deleted/${eventId}/${messageId}`), { deletedAt: rtdbServerTimestamp(), ts: Date.now(), by: uid });
+        return textResult({ eventId, messageId, deleted: true });
+    });
+    server.registerTool("oko_mute_user", {
+        title: "Mute chat user",
+        description: toolDescription({
+            summary: "Mute a chat user for a bounded time window.",
+            args: ["eventId: target event.", "uid: Firebase uid to mute.", "minutes: mute duration, 1-1440, default 5.", "confirm: must be true."],
+            returns: "eventId, targetUid, and mutedMinutes.",
+            examples: ["Use after reading chat messages and confirming the exact uid with the user."],
+        }),
+        inputSchema: { eventId: eventIdField, uid: z.string().min(1).describe("Firebase uid to mute."), minutes: z.number().int().min(1).max(1440).default(5).describe("Mute duration in minutes."), confirm: z.boolean().optional().describe("Required true for mute.") },
+        outputSchema: basicEventOutputSchema,
+        annotations: destructiveTool,
+    }, async ({ eventId, uid: targetUid, minutes, confirm }) => {
+        const actor = await authed(["chat:moderate"]);
+        await readEvent(eventId, actor.uid, "edit");
+        requireConfirm(confirm, "oko_mute_user", { eventId, targetUid, minutes });
+        await set(ref(chatRtdb, `mutes/${eventId}/${targetUid}`), { until: Date.now() + minutes * 60_000, by: actor.uid, reason: "manual" });
+        return textResult({ eventId, targetUid, mutedMinutes: minutes });
+    });
+    server.registerTool("oko_ban_user", {
+        title: "Ban chat user",
+        description: toolDescription({
+            summary: "Ban a chat user and soft-delete up to 500 recent messages from that uid.",
+            args: ["eventId: target event.", "uid: Firebase uid to ban.", "confirm: must be true."],
+            returns: "eventId, targetUid, banned=true, and deletedMessages count.",
+            examples: ["Use only after explicit user confirmation; prefer mute for temporary moderation."],
+        }),
+        inputSchema: { eventId: eventIdField, uid: z.string().min(1).describe("Firebase uid to ban."), confirm: z.boolean().optional().describe("Required true for ban.") },
+        outputSchema: basicEventOutputSchema,
+        annotations: destructiveTool,
+    }, async ({ eventId, uid: targetUid, confirm }) => {
+        const actor = await authed(["chat:moderate"]);
+        await readEvent(eventId, actor.uid, "edit");
+        requireConfirm(confirm, "oko_ban_user", { eventId, targetUid });
+        await set(ref(chatRtdb, `bans/${eventId}/${targetUid}`), true);
+        const messagesSnap = await get(dbQuery(ref(chatRtdb, `messages/${eventId}`), limitToLast(500)));
+        const messages = (messagesSnap.val() ?? {});
+        const deletes = {};
+        for (const [messageId, message] of Object.entries(messages)) {
+            if (message.uid === targetUid)
+                deletes[`mod/deleted/${eventId}/${messageId}`] = { deletedAt: rtdbServerTimestamp(), ts: Date.now(), by: actor.uid, reason: "ban" };
+        }
+        if (Object.keys(deletes).length > 0)
+            await update(ref(chatRtdb), deletes);
+        return textResult({ eventId, targetUid, banned: true, deletedMessages: Object.keys(deletes).length });
+    });
+    server.registerTool("oko_set_chat_settings", {
+        title: "Set chat settings",
+        description: toolDescription({
+            summary: "Set slow mode and automod settings for an event chat.",
+            args: ["eventId: target event.", "slowModeMs: optional slow mode delay, 0-60000 ms.", "automodEnabled: optional automod toggle."],
+            returns: "eventId and updated RTDB setting paths.",
+            examples: ["Use slowModeMs=5000 to slow busy chats; use automodEnabled=false as an emergency kill switch."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            slowModeMs: z.number().int().min(0).max(60000).optional().describe("Slow mode delay in milliseconds."),
+            automodEnabled: z.boolean().optional().describe("Enable or disable chat automoderation."),
+        },
+        outputSchema: basicEventOutputSchema,
+        annotations: idempotentWriteTool,
+    }, async ({ eventId, slowModeMs, automodEnabled }) => {
+        const { uid } = await authed(["chat:moderate"]);
+        await readEvent(eventId, uid, "edit");
+        const patch = {};
+        if (slowModeMs !== undefined)
+            patch[`settings/${eventId}/slowModeMs`] = slowModeMs;
+        if (automodEnabled !== undefined)
+            patch[`settings/${eventId}/automodEnabled`] = automodEnabled;
+        await update(ref(chatRtdb), patch);
+        return textResult({ eventId, updated: Object.keys(patch) });
+    });
+    server.registerTool("oko_launch_checkpoint", {
+        title: "Launch NMO checkpoint",
+        description: toolDescription({
+            summary: "Launch a participant attendance checkpoint for NMO mode.",
+            args: ["eventId: target event.", "timeoutSec: checkpoint response window, 5-3600 seconds.", "confirm: must be true."],
+            returns: "eventId and checkpoint object with id, startedAt, timeoutSec, and optional sessionId.",
+            examples: ["Use during a live NMO webinar only after user confirmation."],
+        }),
+        inputSchema: { eventId: eventIdField, timeoutSec: z.number().int().min(5).max(3600).default(30).describe("Checkpoint response window in seconds."), confirm: z.boolean().optional().describe("Required true for launch.") },
+        outputSchema: basicEventOutputSchema,
+        annotations: writeTool,
+    }, async ({ eventId, timeoutSec, confirm }) => {
+        const { uid } = await authed(["nmo:write", "live:control"]);
+        await readEvent(eventId, uid, "edit");
+        requireConfirm(confirm, "oko_launch_checkpoint", { eventId, timeoutSec });
+        const activeSnap = await get(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`));
+        const checkpoint = { id: randomId(), startedAt: Date.now(), timeoutSec, ...(activeSnap.val() ? { sessionId: activeSnap.val() } : {}) };
+        await update(ref(rtdb, `events/${eventId}`), {
+            "ctrl/checkpoint": checkpoint,
+            [`checkpointWindows/${checkpoint.id}`]: checkpoint,
+        });
+        return textResult({ eventId, checkpoint });
+    });
+    server.registerTool("oko_close_checkpoint", {
+        title: "Close NMO checkpoint",
+        description: toolDescription({
+            summary: "Close the active NMO checkpoint for an event.",
+            args: ["eventId: target event."],
+            returns: "eventId and checkpointClosed=true.",
+            examples: ["Use when the organizer wants to stop showing the active checkpoint."],
+        }),
+        inputSchema: { eventId: eventIdField },
+        outputSchema: basicEventOutputSchema,
+        annotations: idempotentWriteTool,
+    }, async ({ eventId }) => {
+        const { uid } = await authed(["nmo:write", "live:control"]);
+        await readEvent(eventId, uid, "edit");
+        await remove(ref(rtdb, `events/${eventId}/ctrl/checkpoint`));
+        return textResult({ eventId, checkpointClosed: true });
+    });
+    server.registerTool("oko_list_participants", {
+        title: "List NMO participants",
+        description: toolDescription({
+            summary: "Read paginated NMO participants for an event.",
+            args: [
+                "eventId: target event.",
+                "csv: return CSV string instead of participants array.",
+                "limit: max rows, default 50, max 200.",
+                "cursor: participant uid returned as nextCursor by the previous page.",
+            ],
+            returns: "participants or csv plus count, limit, hasMore/has_more, nextCursor/next_cursor.",
+            examples: ["Use limit=50 first; if hasMore is true, call again with cursor=nextCursor."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            csv: z.boolean().default(false).describe("Return CSV string instead of JSON rows."),
+            limit: limitField(MAX_EXPORT_LIMIT, 50),
+            cursor: cursorField,
+        },
+        outputSchema: participantsOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId, csv, limit: max, cursor }) => {
+        const { uid } = await authed(["nmo:write"]);
+        await readEvent(eventId, uid, "read");
+        const constraints = cursor
+            ? [orderBy(documentId()), startAfter(cursor), limit(max + 1)]
+            : [orderBy(documentId()), limit(max + 1)];
+        const snap = await getDocs(query(collection(firestore, "eventParticipants", eventId, "items"), ...constraints));
+        const page = snap.docs.slice(0, max);
+        const rows = page.map((item) => ({ uid: item.id, ...serialize(item.data()) }));
+        const hasMore = snap.docs.length > max;
+        const nextCursor = hasMore ? page.at(-1)?.id ?? null : null;
+        const meta = cursorMeta(rows.length, max, hasMore, nextCursor);
+        if (csv) {
+            const text = csvRows(["uid", "email", "fullName", "position", "org", "registeredAt"], rows.map((row) => [row.uid, row.email, row.fullName, row.position, row.org, row.registeredAt]));
+            return textResult({ csv: text, ...meta });
+        }
+        return textResult({ participants: rows, ...meta });
+    });
+    server.registerTool("oko_list_leads", {
+        title: "List form leads",
+        description: toolDescription({
+            summary: "Read paginated lead form submissions for an event.",
+            args: [
+                "eventId: target event.",
+                "formId: optional lead form id filter.",
+                "csv: return CSV string instead of leads array.",
+                "limit: max rows, default 50, max 200.",
+                "cursor: lead document id returned as nextCursor by the previous page.",
+            ],
+            returns: "leads or csv plus count, limit, hasMore/has_more, nextCursor/next_cursor.",
+            examples: ["Use formId to export one form; if Firestore requests an index, create it from the error link and rerun."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            formId: z.string().optional().describe("Optional lead form id to filter submissions."),
+            csv: z.boolean().default(false).describe("Return CSV string instead of JSON rows."),
+            limit: limitField(MAX_EXPORT_LIMIT, 50),
+            cursor: cursorField,
+        },
+        outputSchema: leadsOutputSchema,
+        annotations: readOnlyTool,
+    }, async ({ eventId, formId, csv, limit: max, cursor }) => {
+        const { uid } = await authed(["leads:read"]);
+        await readEvent(eventId, uid, "read");
+        const base = collection(firestore, "events", eventId, "leads");
+        const constraints = formId
+            ? [where("formId", "==", formId), orderBy(documentId()), ...(cursor ? [startAfter(cursor)] : []), limit(max + 1)]
+            : [orderBy(documentId()), ...(cursor ? [startAfter(cursor)] : []), limit(max + 1)];
+        const snap = await getDocs(query(base, ...constraints));
+        const page = snap.docs.slice(0, max);
+        const leads = page.map((item) => ({ id: item.id, ...serialize(item.data()) }));
+        const hasMore = snap.docs.length > max;
+        const nextCursor = hasMore ? page.at(-1)?.id ?? null : null;
+        const meta = cursorMeta(leads.length, max, hasMore, nextCursor);
+        if (csv) {
+            const text = csvRows(["id", "formId", "source", "submittedAt", "valuesJson"], leads.map((lead) => [lead.id, lead.formId, lead.source, lead.submittedAt, JSON.stringify(lead.values ?? {})]));
+            return textResult({ csv: text, ...meta });
+        }
+        return textResult({ leads, ...meta });
+    });
+    server.registerTool("oko_publish_telegram_post", {
+        title: "Publish Telegram post",
+        description: toolDescription({
+            summary: "Create and optionally send or schedule a Telegram post for an OKO event.",
+            args: [
+                "eventId: event used for access checks and default button URL.",
+                "channelId: Telegram channel id configured for the organizer.",
+                "caption: post caption, max 4096 chars.",
+                "scheduleAt: optional ISO datetime; omitted means immediate send and requires confirm=true.",
+                "confirm: must be true for immediate send.",
+            ],
+            returns: "postId, scheduled flag, and sent flag.",
+            examples: ["Use scheduleAt for scheduled posts; for immediate send, show the exact channel/caption and ask for confirmation."],
+            notes: ["External side effect: immediate sends can publish to real Telegram channels."],
+        }),
+        inputSchema: {
+            eventId: eventIdField,
+            channelId: z.number().int().describe("Telegram channel id."),
+            caption: z.string().min(1).max(4096).describe("Telegram post caption."),
+            imageUrl: z.string().nullable().optional().describe("Optional image URL."),
+            buttonLabel: z.string().max(64).nullable().optional().describe("Optional inline button label."),
+            buttonUrl: z.string().max(1000).nullable().optional().describe("Optional inline button URL; defaults to event URL when buttonLabel is set."),
+            scheduleAt: z.string().datetime().nullable().optional().describe("Optional ISO datetime for scheduled send."),
+            confirm: z.boolean().optional().describe("Required true for immediate send."),
+        },
+        outputSchema: z.object({ postId: z.string(), scheduled: z.boolean(), sent: z.boolean() }).passthrough(),
+        annotations: writeTool,
+    }, async (args) => {
+        const { uid } = await authed(["telegram:write"]);
+        await readEvent(args.eventId, uid, "edit");
+        const scheduled = !!args.scheduleAt;
+        if (!scheduled)
+            requireConfirm(args.confirm, "oko_publish_telegram_post", { eventId: args.eventId, channelId: args.channelId, caption: args.caption });
+        const postData = {
+            eventId: args.eventId,
+            ownerId: uid,
+            ownerEmail: "",
+            channelId: args.channelId,
+            caption: args.caption.trim(),
+            imageUrl: args.imageUrl?.trim() || null,
+            buttons: args.buttonLabel?.trim() ? [{ label: args.buttonLabel.trim(), url: args.buttonUrl?.trim() || eventUrl(args.eventId) }] : [],
+            status: scheduled ? "scheduled" : "draft",
+            scheduledAt: args.scheduleAt ? Timestamp.fromDate(new Date(args.scheduleAt)) : null,
+            sentAt: null,
+            telegramMessageId: null,
+            error: null,
+            createdAt: serverTimestamp(),
+            updatedAt: serverTimestamp(),
+        };
+        const postRef = await addDoc(collection(firestore, "telegramPosts"), postData);
+        if (!scheduled) {
+            const sendPost = httpsCallable(functions, "sendTelegramPost");
+            await sendPost({ postId: postRef.id });
+        }
+        return textResult({ postId: postRef.id, scheduled, sent: !scheduled });
+    });
+    server.registerTool("oko_create_workspace_invite", {
+        title: "Create workspace invite",
+        description: toolDescription({
+            summary: "Create a workspace invite for a known OKO workspace.",
+            args: [
+                "workspaceId: workspace owned by the authenticated organizer.",
+                "code: invite code, 4-64 chars; stored uppercase.",
+                "email: optional intended recipient email.",
+                "permissions: optional whitelist of workspace permission booleans.",
+                "confirm: must be true.",
+            ],
+            returns: "workspaceId, invite code, and created=true.",
+            examples: ["Use only after confirming the recipient and permission set with the workspace owner."],
+        }),
+        inputSchema: {
+            workspaceId: z.string().min(1),
+            code: z.string().min(4).max(64),
+            email: z.string().email().optional(),
+            comment: z.string().max(500).default(""),
+            permissions: workspacePermissionsSchema,
+            confirm: z.boolean().optional(),
+        },
+        outputSchema: z.object({ workspaceId: z.string(), code: z.string(), created: z.boolean() }).passthrough(),
+        annotations: writeTool,
+    }, async (args) => {
+        const { uid } = await authed(["workspace:write"]);
+        const workspaceSnap = await getDoc(doc(firestore, "workspaces", args.workspaceId));
+        if (!workspaceSnap.exists())
+            throw new Error("Workspace not found.");
+        const workspace = workspaceSnap.data();
+        if (workspace.ownerId !== uid)
+            throw new Error("Only the workspace owner can create invites.");
+        requireConfirm(args.confirm, "oko_create_workspace_invite", { workspaceId: args.workspaceId, code: args.code, email: args.email });
+        const code = args.code.trim().toUpperCase();
+        await setDoc(doc(firestore, "workspaceInvites", code), {
+            workspaceId: args.workspaceId,
+            workspaceName: safeString(workspace.name, "Workspace"),
+            email: args.email ?? "",
+            comment: args.comment,
+            permissions: args.permissions,
+            createdBy: uid,
+            createdAt: serverTimestamp(),
+            claimed: false,
+            claimedBy: null,
+        });
+        return textResult({ workspaceId: args.workspaceId, code, created: true });
+    });
+}