@okostream/mcp 0.12.2 → 0.12.4

package/dist/tools/eventAccess.js

@@ -1,65 +0,0 @@
-// Контур прав MCP на конкретное событие.
-//
-// Источник истины — grant `eventAccess/{uid}/grants/{eventId}`, который
-// поддерживают CF7 и CF18. Legacy-путь по массивам события остаётся только
-// на случай, когда правила отказали в чтении grants: отличить отказ доступа
-// от сетевого сбоя обязательно, иначе первый молча превращается во второй.
-//
-// Сторож инварианта — `test/event-access-index.test.mjs`.
-import { doc, getDoc } from "firebase/firestore";
-import { firestore } from "../firebase.js";
-import { asRecord } from "./context.js";
-export const EVENT_ACCESS_FIELD_BY_MODE = {
-    read: "accessibleBy",
-    edit: "editors",
-    delete: "deleters",
-    live: "liveControllers",
-    session: "sessionManagers",
-    analytics: "analyticsViewers",
-    report: "reportDownloaders",
-    moderate: "chatModerators",
-    notify: "notificationSenders",
-};
-export function grantAllowsMode(data, mode) {
-    const field = EVENT_ACCESS_FIELD_BY_MODE[mode];
-    return asRecord(data.capabilities)[field] === true;
-}
-export function legacyEventAllowsMode(data, uid, mode) {
-    if (data.ownerId === uid)
-        return true;
-    const fields = mode === "read"
-        ? ["accessibleBy", "editors"]
-        : [EVENT_ACCESS_FIELD_BY_MODE[mode]];
-    return fields.some((field) => (Array.isArray(data[field]) && data[field].includes(uid)));
-}
-export function isFirestorePermissionDenied(error) {
-    if (!error || typeof error !== "object")
-        return false;
-    const code = error.code;
-    return code === "permission-denied"
-        || code === "firestore/permission-denied"
-        || code === "PERMISSION_DENIED";
-}
-export async function readEvent(eventId, uid, mode = "read") {
-    const [snap, grant] = await Promise.all([
-        getDoc(doc(firestore, "events", eventId)),
-        getDoc(doc(firestore, "eventAccess", uid, "grants", eventId)).catch((error) => {
-            if (!isFirestorePermissionDenied(error))
-                throw error;
-            return null;
-        }),
-    ]);
-    if (!snap.exists())
-        throw new Error("Event not found.");
-    const data = snap.data();
-    const allowed = grant === null
-        ? legacyEventAllowsMode(data, uid, mode)
-        : data.ownerId === uid || (grant.exists() && grantAllowsMode(grant.data(), mode));
-    if (!allowed) {
-        throw new Error(`Event does not grant ${mode} access to this organizer.`);
-    }
-    if (data.trashedAt && mode !== "read" && mode !== "delete") {
-        throw new Error("Event is in trash. Restore it before making changes or live actions.");
-    }
-    return data;
-}

package/dist/tools/eventCreate.js

@@ -1,43 +0,0 @@
-// Создание события: проверка права на пространство и запись с зеркалом RTDB.
-//
-// Зеркало ownerId/workspaceId в основной RTDB — опора правил доступа, и
-// пишет его сервер, а не клиент. Создание идёт парой: документ Firestore,
-// затем ensureEventRuntime (CF32) — она ставит зеркало сразу, не дожидаясь
-// триггера.
-//
-// 🔴 Отката здесь намеренно НЕТ, хотя прежняя редакция этой шапки его
-// обещала. Сбой CF32 не оставляет событие сломанным: зеркало всё равно
-// поставит CF20 `onEventCreated` — она пишет ownerId/workspaceId сама
-// (`functions/src/eventsLifecycle.ts`) и объявлена с `retry: true`, то есть
-// доставка гарантирована. Удалять документ из-за сбоя быстрого пути значило
-// бы терять событие там, где медленный путь его чинит.
-import { addDoc, collection, doc, getDoc } from "firebase/firestore";
-import { httpsCallable } from "firebase/functions";
-import { firestore, functions } from "../firebase.js";
-import { safeString } from "../utils.js";
-export async function assertCanCreateInWorkspace(uid, workspaceId) {
-    if (workspaceId === uid)
-        return;
-    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 !== 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.");
-        }
-    }
-}
-export async function addEventWithRtdbMirror(eventData) {
-    const eventRef = await addDoc(collection(firestore, "events"), eventData);
-    try {
-        const ensureRuntime = httpsCallable(functions, "ensureEventRuntime");
-        await ensureRuntime({ eventId: eventRef.id });
-    }
-    catch (error) {
-        console.error(`[OKO MCP] RTDB mirror deferred to onEventCreated for event ${eventRef.id}:`, error);
-    }
-    return eventRef;
-}

package/dist/tools/events.js

@@ -1,497 +0,0 @@
-// Создание и настройка события: карточка, блоки, карточки-предложения.
-//
-// Список строится по индексу доступа eventAccess/{uid}/grants, а не по
-// массивам события: массивы сняты 31.08.
-//
-// Настройка меняет только Firestore. Живое состояние (что показано зрителю
-// прямо сейчас) живёт в RTDB и правится инструментами live.
-import { z } from "zod";
-import { serialize, textResult } from "../utils.js";
-import { authed, eventLinks, randomId } from "./context.js";
-import { cardsConfigOutputSchema, createWebinarOutputSchema, cursorField, eventIdField, eventOutputSchema, eventsOutputSchema, formSchema, limitField, readOnlyTool, setupValidationOutputSchema, toolDescription, updateOutputSchema, writeTool } from "./schemas.js";
-import { buildCardsItems, CARD_IMAGE_RATIOS, cardHasImage, cardItemInputSchema, eventFormIds, MAX_CARD_ITEMS, normalizeCardButtonUrl, readCardsConfig, writeEventPatchWithCards } from "./imagePipeline.js";
-import { collection, doc, getDoc, getDocs, limit, orderBy, query, serverTimestamp, startAfter, Timestamp, updateDoc, where } from "firebase/firestore";
-import { addEventWithRtdbMirror, assertCanCreateInWorkspace } from "./eventCreate.js";
-import { cursorMeta, normalizeVideo, parseIsoBound, parseTimestampCursor, pickPage, timestampCursorFrom } from "./formatting.js";
-import { firestore } from "../firebase.js";
-import { isFirestorePermissionDenied, readEvent } from "./eventAccess.js";
-import { validateEventSetup } from "./setupValidation.js";
-export function registerEventTools(server) {
-    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: pagination cursor returned as nextCursor by the previous page; reuse it with the same filters.",
-                "workspaceId: optional workspace filter.",
-                'detail: "compact" (default) returns the light card projection; "full" returns complete event documents.',
-                "from/to: optional ISO timestamps bounding meta.eventDate; sorting switches to eventDate descending and undated events are excluded.",
-            ],
-            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.",
-                'For "today\'s webinar" pass from/to covering the day; use detail="full" only when block contents are needed.',
-            ],
-        }),
-        inputSchema: {
-            limit: limitField(),
-            cursor: cursorField,
-            workspaceId: z.string().optional().describe("Optional workspace id to filter returned events."),
-            detail: z.enum(["compact", "full"]).default("compact").describe('Response shape: "compact" card projection (default) or "full" event documents.'),
-            from: z.string().optional().describe("Include only events with meta.eventDate at or after this ISO timestamp."),
-            to: z.string().optional().describe("Include only events with meta.eventDate at or before this ISO timestamp."),
-        },
-        outputSchema: eventsOutputSchema,
-        annotations: readOnlyTool,
-    }, async (args) => {
-        const { uid } = await authed(["events:read"]);
-        const fromTs = parseIsoBound(args.from, "from");
-        const toTs = parseIsoBound(args.to, "to");
-        const dateFiltered = fromTs !== null || toTs !== null;
-        const orderField = dateFiltered ? "eventDate" : "createdAt";
-        const constraints = [
-            // При датном фильтре workspaceId отсеивается по загруженной странице:
-            // составного индекса grants(workspaceId+eventDate) нет намеренно.
-            ...(!dateFiltered && args.workspaceId ? [where("workspaceId", "==", args.workspaceId)] : []),
-            ...(fromTs ? [where("eventDate", ">=", fromTs)] : []),
-            ...(toTs ? [where("eventDate", "<=", toTs)] : []),
-            orderBy(orderField, "desc"),
-            limit(args.limit + 1),
-        ];
-        if (args.cursor)
-            constraints.splice(constraints.length - 1, 0, startAfter(parseTimestampCursor(args.cursor)));
-        const snap = await getDocs(query(collection(firestore, "eventAccess", uid, "grants"), ...constraints)).catch((error) => {
-            // Отказ в чтении собственных grants — это не повод молча уйти на
-            // legacy-путь: с 31.08 он мёртв вдвойне (правило `allow list` оставлено
-            // только владельцу платформы, а девять массивов сняты с документов).
-            // Фолбэк дал бы вторую, непонятную ошибку вместо настоящей причины.
-            if (!isFirestorePermissionDenied(error))
-                throw error;
-            throw new Error("Не удалось прочитать eventAccess/grants организатора. Права событий "
-                + "живут только в индексе; проверь, что ключ активен и его область "
-                + "доступа включает events:read.");
-        });
-        if (snap !== null) {
-            const { page, hasMore } = pickPage(snap.docs, args.limit);
-            const nextCursor = hasMore ? timestampCursorFrom(page.at(-1)?.data()[orderField]) : null;
-            const pageItems = dateFiltered && args.workspaceId
-                ? page.filter((item) => item.data().workspaceId === args.workspaceId)
-                : page;
-            let events;
-            if (args.detail === "full") {
-                const eventDocuments = await Promise.all(pageItems.map((item) => (getDoc(doc(firestore, "events", item.id)))));
-                events = eventDocuments.flatMap((item) => (item.exists()
-                    ? [{ id: item.id, ...serialize(item.data()) }]
-                    : []));
-            }
-            else {
-                // Компактный режим отдаёт grant-проекцию как есть — без чтения
-                // полных документов событий.
-                events = pageItems.map((item) => {
-                    const data = serialize(item.data());
-                    delete data.schemaVersion;
-                    delete data.uid;
-                    delete data.eventId;
-                    return { id: item.id, ...data };
-                });
-            }
-            return textResult({ events, ...cursorMeta(events.length, args.limit, hasMore, nextCursor) }, { truncationHint: 'Use a smaller limit, cursor pagination, or detail="compact".' });
-        }
-        // Legacy-путь (запрос событий по accessibleBy) снят 31.08 вместе с самими
-        // массивами: правило `allow list` оставлено только владельцу платформы, а
-        // поля стёрты со всех документов. Ветка была недостижима — выше остаётся
-        // единственный источник списка, индекс grants.
-        throw new Error("Список событий не получен: индекс eventAccess вернул пустой результат.");
-    });
-    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), ...eventLinks(eventId) });
-    });
-    server.registerTool("oko_validate_event_setup", {
-        title: "Validate event setup",
-        description: toolDescription({
-            summary: "Run a read-only setup readiness lint for one OKO event.",
-            args: ["eventId: OKO event document id."],
-            returns: "ok flag, score, errors, warnings, suggestions, next actions, and useful links.",
-            examples: [
-                "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."],
-        }),
-        inputSchema: { eventId: eventIdField },
-        outputSchema: setupValidationOutputSchema,
-        annotations: readOnlyTool,
-    }, async ({ eventId }) => {
-        const { uid } = await authed(["events:read"]);
-        const data = await readEvent(eventId, uid, "read");
-        return textResult(validateEventSetup(eventId, data));
-    });
-    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;
-        await assertCanCreateInWorkspace(uid, workspaceId);
-        const video = normalizeVideo(args.videoUrl);
-        // Девять массивов доступа не пишутся (31.08): grants строит CF7 из
-        // владельца и shares рабочего пространства.
-        const docRef = await addEventWithRtdbMirror({
-            ownerId: uid,
-            workspaceId,
-            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" },
-            },
-        });
-        return textResult({ id: docRef.id, ...eventLinks(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, sessionMode, durationMinutes."],
-            returns: "event id and the list of Firestore fields updated.",
-            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.",
-            ],
-        }),
-        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."),
-            sessionMode: z.enum(["manual", "schedule"]).optional().describe("Analytics session mode: manual Start/End buttons, or automatic start/end on schedule at eventDate."),
-            durationMinutes: z.number().int().min(15).max(1440).optional().describe("Event duration in minutes (15-1440) used by schedule mode to end the session."),
-        },
-        outputSchema: updateOutputSchema,
-        annotations: writeTool,
-    }, async (args) => {
-        const requiredScopes = new Set();
-        if (args.title !== undefined || args.pinned !== undefined)
-            requiredScopes.add("events:write");
-        if (args.videoUrl !== undefined
-            || args.eventDate !== undefined
-            || args.speakerName !== undefined
-            || args.description !== undefined
-            || args.sessionMode !== undefined
-            || args.durationMinutes !== undefined) {
-            requiredScopes.add("setup:write");
-        }
-        if (requiredScopes.size === 0)
-            throw new Error("Provide at least one field to update.");
-        const { uid } = await authed([...requiredScopes]);
-        const current = await readEvent(args.eventId, uid, "edit");
-        // 🔴 Режим по расписанию без даты — состояние, которое молча не работает:
-        // CF51 отбирает события запросом `analyticsSessionMode == "schedule"` И
-        // `meta.eventDate` в окне, поэтому событие без даты не выбирается никогда,
-        // а инструмент рапортовал успех. Веб на том же состоянии показывает
-        // подсказку `sessionMode.needsDate` (ревью 02.09, Б8).
-        if (args.sessionMode === "schedule") {
-            const dateAfterPatch = args.eventDate !== undefined
-                ? args.eventDate
-                : current.meta?.eventDate ?? null;
-            if (!dateAfterPatch) {
-                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 keep sessionMode 'manual'.");
-            }
-        }
-        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;
-        if (args.sessionMode !== undefined)
-            patch.analyticsSessionMode = args.sessionMode;
-        if (args.durationMinutes !== undefined)
-            patch["meta.durationMinutes"] = args.durationMinutes;
-        await updateDoc(doc(firestore, "events", args.eventId), patch);
-        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, and Telegram channel ids.",
-            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.",
-            ],
-            returns: "event id and the list of Firestore fields updated.",
-            examples: ["Use after oko_create_webinar to set chat visibility, CTA/form binding, and other audience blocks."],
-            notes: [
-                "A block toggle and its image are independent: enabling a block here works with an image already uploaded via oko_upload_image, and uploading an image never enables the block by itself.",
-                "promoBanner has no text field by design: the banner is image+link. blocks.promoBanner.text seen in event documents is legacy and is never rendered on the event page.",
-            ],
-        }),
-        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(),
-        },
-        outputSchema: updateOutputSchema,
-        annotations: writeTool,
-    }, async (args) => {
-        const { uid } = await authed(["setup:write"]);
-        const current = 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;
-        // 🔴 Протокол проверяется так же, как у карточек в этом же файле
-        // (`normalizeCardButtonUrl`). Оба значения попадают в `href` кнопки на
-        // публичной странице: `javascript:` там — исполнение кода у зрителя, а
-        // единственным отличием ссылки баннера от ссылки карточки было то, что
-        // её никто не проверял.
-        if (args.promoBanner?.link !== undefined)
-            patch["blocks.promoBanner.link"] = normalizeCardButtonUrl(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"] = normalizeCardButtonUrl(args.primaryCta.buttonUrl);
-        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;
-        }
-        // 🔴 `formId` баннера и CTA проверяется на существование — ровно так же,
-        // как у карточек в этом же файле (`buildCardsItems` бросает «Form X not
-        // found»). Прежде запись проходила, инструмент рапортовал «привязано», а
-        // кнопка у зрителей не делала НИЧЕГО: FormHost формы не находит, а
-        // buttonUrl в этом сценарии пуст. Формы сверяются с состоянием ПОСЛЕ
-        // патча: замена `forms` в том же вызове перегенерирует id (02.09, Б6).
-        const formsAfterPatch = (patch.forms ?? current.forms);
-        const knownFormIds = new Set((Array.isArray(formsAfterPatch) ? formsAfterPatch : [])
-            .map((form) => (typeof form?.id === "string" ? form.id : null))
-            .filter((id) => Boolean(id)));
-        for (const [field, value] of [
-            ["blocks.promoBanner.formId", patch["blocks.promoBanner.formId"]],
-            ["blocks.primaryCta.formId", patch["blocks.primaryCta.formId"]],
-        ]) {
-            if (typeof value === "string" && value && !knownFormIds.has(value)) {
-                throw new Error(`${field}: form "${value}" not found in event.forms. Create the form in the same call `
-                    + "(or beforehand) — a button bound to a missing form does nothing for viewers.");
-            }
-        }
-        await updateDoc(doc(firestore, "events", args.eventId), patch);
-        return textResult({ id: args.eventId, updated: Object.keys(patch) });
-    });
-    server.registerTool("oko_configure_cards", {
-        title: "Configure event cards",
-        description: toolDescription({
-            summary: "Configure the Cards setup block and replace its card list. Images are managed separately through oko_upload_image and are preserved by matching card id.",
-            args: [
-                "eventId: event to edit.",
-                "enabled: optional Cards block enabled flag.",
-                "visibility: optional default visibility, always or hidden.",
-                "cardImageRatio: optional image ratio, one of auto, 1:1, 4:3, 3:2, 16:9, 2:3, 3:4.",
-                "items: optional full replacement array, max 6 cards. Each item may include id, title, text, buttonLabel, buttonUrl, formId.",
-            ],
-            returns: "event id, updated Firestore fields, normalized cards config, generated card ids, preserved image ids, removed card ids, and warnings.",
-            examples: [
-                "Use after oko_create_webinar to create cards before uploading per-card images.",
-                "Call oko_get_event first and pass the full desired items array when editing existing cards.",
-                "Use formId instead of buttonUrl when a card button should open a lead form.",
-            ],
-            notes: [
-                "This tool replaces blocks.cards.items when items is provided; omitted text fields become null.",
-                "Existing card images are preserved only when the same card id remains in the replacement list.",
-                "buttonUrl allows http(s), mailto, or tel URLs; javascript/data URLs are rejected.",
-                "If a removed card had an image, Storage cleanup is not automatic; this matches the web Setup behavior.",
-            ],
-        }),
-        inputSchema: {
-            eventId: eventIdField,
-            enabled: z.boolean().optional().describe("Whether the Cards block is enabled in setup."),
-            visibility: z.enum(["always", "hidden"]).optional().describe("Default visibility when no live override exists."),
-            cardImageRatio: z.enum(CARD_IMAGE_RATIOS).optional().describe("Image aspect ratio for all cards."),
-            items: z.array(cardItemInputSchema).max(MAX_CARD_ITEMS).optional().describe("Full replacement list, max 6 cards. Omit to update only block settings."),
-        },
-        outputSchema: cardsConfigOutputSchema,
-        annotations: writeTool,
-    }, async (args) => {
-        const { uid } = await authed(["setup:write"]);
-        const event = await readEvent(args.eventId, uid, "edit");
-        const currentCards = readCardsConfig(event);
-        const patch = {};
-        const finalCards = {
-            enabled: args.enabled ?? currentCards.enabled,
-            visibility: args.visibility ?? currentCards.visibility,
-            cardImageRatio: args.cardImageRatio ?? currentCards.cardImageRatio,
-            items: currentCards.items,
-            repairedIdPositions: currentCards.repairedIdPositions,
-        };
-        const generatedCardIds = [];
-        const preservedImageCardIds = [];
-        let removedCardIds = [];
-        let removedCardsWithImages = [];
-        if (args.enabled !== undefined)
-            patch["blocks.cards.enabled"] = args.enabled;
-        if (args.visibility !== undefined)
-            patch["blocks.cards.visibility"] = args.visibility;
-        if (args.cardImageRatio !== undefined)
-            patch["blocks.cards.cardImageRatio"] = args.cardImageRatio;
-        // 🔴 Карточки пересобираются ВНУТРИ транзакции, из свежего документа.
-        // Массив `blocks.cards.items` пишется целиком, а между чтением события и
-        // записью успевает отработать CF4 и дописать в него `imageVariants`,
-        // `imageUrl` и размеры. Реконструкция из устаревшего снимка их стирала —
-        // картинка у зрителя откатывалась к мастеру или пропадала. Это Pattern 23,
-        // уже разобранный на веб-стороне и вернувшийся сюда через MCP.
-        //
-        // Отчёт (что создано, что сохранено, что удалено) тоже считается внутри:
-        // иначе он описывал бы не ту запись, которая случилась.
-        const buildItems = args.items === undefined ? null : (fresh) => {
-            const freshCards = readCardsConfig(fresh);
-            const built = buildCardsItems({
-                inputs: args.items,
-                existing: freshCards.items,
-                formIds: eventFormIds(fresh),
-            });
-            finalCards.items = built.items;
-            generatedCardIds.length = 0;
-            preservedImageCardIds.length = 0;
-            generatedCardIds.push(...built.generatedCardIds);
-            preservedImageCardIds.push(...built.preservedImageCardIds);
-            const nextIds = new Set(built.items.map((item) => item.id));
-            const removed = freshCards.items.filter((item) => !nextIds.has(item.id));
-            removedCardIds = removed.map((item) => item.id);
-            removedCardsWithImages = removed.filter(cardHasImage).map((item) => item.id);
-            return built.items;
-        };
-        if (Object.keys(patch).length > 0 || buildItems) {
-            await writeEventPatchWithCards(args.eventId, patch, buildItems);
-        }
-        const warnings = removedCardsWithImages.length > 0
-            ? [`Removed cards had images and their Storage files were not deleted: ${removedCardsWithImages.join(", ")}.`]
-            : [];
-        // 🔴 Карточка без пригодного `id` получает подставленный при чтении, и он
-        // не совпадает ни с чем в документе: прежняя запись не находится, её
-        // картинка обнуляется. Пока это молчало, организатор видел успешный ответ
-        // и пропавшее изображение без единого объяснения.
-        if (finalCards.repairedIdPositions.length > 0) {
-            warnings.push(`Cards at position(s) ${finalCards.repairedIdPositions.join(", ")} had no usable id in Firestore; `
-                + "a temporary one was generated, so their previous images could not be matched and were dropped. "
-                + "Re-upload images for these cards.");
-        }
-        return textResult({
-            eventId: args.eventId,
-            updated: Object.keys(patch),
-            cards: finalCards,
-            generatedCardIds,
-            removedCardIds,
-            removedCardsWithImages,
-            preservedImageCardIds,
-            warnings,
-        });
-    });
-}