@learnpack/learnpack 5.0.363 → 5.0.364

package/lib/commands/serve.js

@@ -24,6 +24,7 @@ const dotenv = require("dotenv");
 // import { v4 as uuidv4 } from "uuid"
 const creatorUtilities_1 = require("../utils/creatorUtilities");
 const lessonRecovery_1 = require("../utils/lessonRecovery");
+const generationRetry_1 = require("../utils/generationRetry");
 // import { handleAssetCreation } from "./publish"
 const axios_1 = require("axios");
 const FormData = require("form-data");
@@ -52,6 +53,9 @@ const redis_1 = require("redis");
 const historyManager_1 = require("../managers/historyManager");
 const readmeHistoryService_1 = require("../managers/readmeHistoryService");
 const readmeSanitizer_1 = require("../utils/readmeSanitizer");
+const componentsGuide_1 = require("../utils/interactivity/componentsGuide");
+const interactivityPlan_1 = require("../utils/interactivity/interactivityPlan");
+const structuredComponents_1 = require("../utils/interactivity/structuredComponents");
 // eslint-disable-next-line
 const frontMatter = require("front-matter");
 if (process.env.NEW_RELIC_ENABLED === "true") {
@@ -75,16 +79,20 @@ function translationsSummary(lesson) {
 function opId() {
     return crypto.randomBytes(4).toString("hex");
 }
-// Serialization per course to prevent syllabus race conditions
+// Serialization per course to prevent syllabus race conditions. The queue lives
+// in memory, so it only orders requests within one process: serve runs on a
+// single Heroku dyno. With more than one, it has to move to Redis.
+// A function running in the queue must not call serializeByCourse for the same
+// course, or it waits for itself.
 const courseQueues = new Map();
 async function serializeByCourse(courseSlug, fn) {
     var _a;
     const prev = (_a = courseQueues.get(courseSlug)) !== null && _a !== void 0 ? _a : Promise.resolve();
+    // A failure belongs to its own caller. Without the catch, every function
+    // queued after it would be skipped and fail with the same error.
     const next = prev
+        .catch(() => null)
         .then(() => fn())
-        .catch(error => {
-        throw error;
-    })
         .finally(() => {
         if (courseQueues.get(courseSlug) === next) {
             courseQueues.delete(courseSlug);
@@ -413,17 +421,45 @@ async function startInitialContentGeneration(rigoToken, steps, packageContext, e
     }
     return res.id;
 }
-async function startInteractivityGeneration(rigoToken, steps, packageContext, exercise, courseSlug, purposeSlug, bucket, lastLesson = "") {
+async function startInteractivityGeneration(rigoToken, steps, packageContext, exercise, courseSlug, purposeSlug, bucket, lastLesson = "", options = {}) {
     const exSlug = (0, creatorUtilities_2.slugify)(exercise.id + "-" + exercise.title);
     console.log("Starting interactivity generation for", exSlug);
-    const webhookUrl = `${process.env.HOST}/webhooks/${courseSlug}/interactivity-processor/${exercise.uid}/${rigoToken}`;
+    const request = (0, interactivityPlan_1.planInteractivityRequest)({
+        v2Enabled: (0, interactivityPlan_1.isInteractivityV2Enabled)(),
+        forceV1: options.forceV1,
+    });
+    // The structured template (v2) needs the components guide: without it the
+    // model does not know what each component field means. The guide is loaded
+    // before anything else so that rigobot is never called without it.
+    let componentsYml;
+    if (request.tpl === "v2") {
+        try {
+            componentsYml = (0, componentsGuide_1.buildInteractivityGuide)(await componentsGuide_1.componentsGuideLoader.load());
+        }
+        catch (error) {
+            if (error instanceof componentsGuide_1.ComponentsGuideUnavailableError) {
+                console.error("Components guide unavailable:", error.message);
+                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                    lesson: exSlug,
+                    status: "error",
+                    log: `❌ Could not load the components guide for lesson ${exercise.title}; retry the generation`,
+                });
+            }
+            throw error;
+        }
+    }
+    else {
+        componentsYml = await fetchComponentsYml();
+    }
+    // The template and the attempt travel in the webhook URL: rigobot posts back
+    // to this exact URL, and its error payload says neither.
+    const webhookUrl = `${process.env.HOST}/webhooks/${courseSlug}/interactivity-processor/${exercise.uid}/${rigoToken}${request.webhookQuery}`;
     // Emit notification that interactivity generation is starting
     (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
         lesson: exSlug,
         status: "generating",
         log: `🔄 Starting interactivity generation for lesson: ${exercise.title}`,
     });
-    const componentsYml = await fetchComponentsYml();
     const currentSyllabus = await getSyllabus(courseSlug, bucket);
     const fullSyllabus = {
         steps: steps.map(lessonCleaner),
@@ -440,7 +476,10 @@ async function startInteractivityGeneration(rigoToken, steps, packageContext, ex
         output_language: packageContext.language || "en",
         current_syllabus: JSON.stringify(fullSyllabus),
         lesson_info: JSON.stringify(lessonCleaner(exercise)),
-    }, webhookUrl);
+    }, webhookUrl, request.slug);
+    if (!res) {
+        throw new Error(`Could not start interactivity generation for lesson ${exSlug} (${request.slug})`);
+    }
     return res.id;
 }
 async function createInitialReadme(tutorialInfo, tutorialSlug, rigoToken) {
@@ -555,6 +594,48 @@ async function updateLessonWithInitialContent(courseSlug, lessonUID, initialResp
     await saveSyllabus(courseSlug, syllabus, bucket);
     return lesson;
 }
+/**
+ * Changes one lesson on a fresh read of the syllabus. Saving a copy read
+ * earlier would undo whatever was saved since, like the lesson's
+ * `initialContent`.
+ * @param courseSlug - The course.
+ * @param lessonUID - The lesson to change.
+ * @param bucket - The bucket that holds the syllabus.
+ * @param patch - Changes the lesson in place. Gets the course language.
+ * @returns Once the syllabus is saved, or right away if the lesson is gone.
+ */
+async function patchLesson(courseSlug, lessonUID, bucket, patch) {
+    const syllabus = await getSyllabus(courseSlug, bucket);
+    const lesson = syllabus.lessons.find(lesson => lesson.uid === lessonUID);
+    if (!lesson) {
+        console.error(`Lesson ${lessonUID} not found in syllabus`);
+        return;
+    }
+    patch(lesson, syllabus.courseInfo.language || "en");
+    await saveSyllabus(courseSlug, syllabus, bucket);
+}
+/**
+ * The translation entry of a lesson that waits for a new job.
+ * @param completionId - The Rigobot job.
+ * @param autoRetries - The automatic retries of the current phase so far.
+ * @returns The entry to save under the course language.
+ */
+const startedJob = (completionId, autoRetries = 0) => ({
+    completionId,
+    startedAt: Date.now(),
+    completedAt: 0,
+    autoRetries,
+});
+/**
+ * The creator log for a failed job that is not retried.
+ * @param reason - Why there is no retry.
+ * @param phase - What the job generated.
+ * @param exSlug - The lesson slug.
+ * @returns The log line.
+ */
+const noRetryLog = (reason, phase, exSlug) => reason === "permanent" ?
+    `❌ Error generating ${phase} for lesson ${exSlug}. Retrying cannot fix this error, so it was not retried` :
+    `❌ Error generating ${phase} for lesson ${exSlug} after ${generationRetry_1.MAX_AUTO_RETRIES} retries`;
 async function updateLessonStatusToError(courseSlug, lessonUID, bucket) {
     try {
         const syllabus = await getSyllabus(courseSlug, bucket);
@@ -1419,60 +1500,61 @@ class ServeCommand extends SessionCommand_1.default {
             if (!rigoToken) {
                 throw new errorHandler_1.ValidationError("Rigo token is required. x-rigo-token header is missing");
             }
-            const syllabus = await getSyllabus(courseSlug, bucket);
-            const exercise = syllabus.lessons.find(lesson => lesson.uid === lessonUid);
-            const exerciseIndex = syllabus.lessons.findIndex(lesson => lesson.uid === lessonUid);
-            // Validate that exercise exists
-            if (!exercise) {
-                throw new errorHandler_1.NotFoundError(`Lesson with UID "${lessonUid}" not found in course "${courseSlug}"`);
-            }
-            // Validate that exercise index is valid (defensive check)
-            if (exerciseIndex === -1) {
-                throw new errorHandler_1.NotFoundError(`Lesson with UID "${lessonUid}" not found in course "${courseSlug}"`);
-            }
-            // Validate that exercise has required properties
-            if (!exercise.id || !exercise.title) {
-                throw new errorHandler_1.ValidationError(`Lesson "${lessonUid}" is missing required properties (id or title)`);
-            }
-            // previous exercise
-            let previousReadme = "---";
-            const previousExercise = syllabus.lessons[exerciseIndex - 1];
-            if (previousExercise) {
-                // Get the readme of the previous exercise
-                const exSlug = (0, creatorUtilities_2.slugify)(previousExercise.id + "-" + previousExercise.title);
-                // llist the files un
-                const [files] = await bucket.getFiles({
-                    prefix: `courses/${courseSlug}/exercises/${exSlug}/README`,
-                });
-                // select any README
-                const readmeFiles = files.map(f => f.name);
-                const readmeFile = readmeFiles.find(f => f.includes("README"));
-                if (readmeFile) {
-                    const [content] = await bucket.file(readmeFile).download();
-                    previousReadme = content.toString();
+            // In the course queue, so the webhook of this job cannot be handled
+            // before the lesson is saved as generating.
+            await serializeByCourse(courseSlug, async () => {
+                const syllabus = await getSyllabus(courseSlug, bucket);
+                const exercise = syllabus.lessons.find(lesson => lesson.uid === lessonUid);
+                const exerciseIndex = syllabus.lessons.findIndex(lesson => lesson.uid === lessonUid);
+                // Validate that exercise exists
+                if (!exercise) {
+                    throw new errorHandler_1.NotFoundError(`Lesson with UID "${lessonUid}" not found in course "${courseSlug}"`);
                 }
-            }
-            // Use new two-phase generation workflow
-            const completionId = await startInitialContentGeneration(rigoToken, syllabus.lessons, syllabus.courseInfo, exercise, courseSlug, syllabus.courseInfo.purpose, previousReadme +
-                "\n\nThe user provided the following feedback related to the content of the course so far: \n\n" +
-                feedback);
-            syllabus.lessons[exerciseIndex].status = "GENERATING";
-            syllabus.lessons[exerciseIndex].translations = {
-                [syllabus.courseInfo.language || "en"]: {
-                    completionId,
-                    startedAt: Date.now(),
-                    completedAt: 0,
-                },
-            };
-            console.log("Lesson", syllabus.lessons[exerciseIndex]);
-            if (syllabus.feedback && typeof syllabus.feedback === "string") {
-                syllabus.feedback += "\n\n" + feedback;
-            }
-            else {
-                syllabus.feedback = feedback;
-            }
-            syllabus.generationMode = mode;
-            await saveSyllabus(courseSlug, syllabus, bucket);
+                // Validate that exercise index is valid (defensive check)
+                if (exerciseIndex === -1) {
+                    throw new errorHandler_1.NotFoundError(`Lesson with UID "${lessonUid}" not found in course "${courseSlug}"`);
+                }
+                // Validate that exercise has required properties
+                if (!exercise.id || !exercise.title) {
+                    throw new errorHandler_1.ValidationError(`Lesson "${lessonUid}" is missing required properties (id or title)`);
+                }
+                // previous exercise
+                let previousReadme = "---";
+                const previousExercise = syllabus.lessons[exerciseIndex - 1];
+                if (previousExercise) {
+                    // Get the readme of the previous exercise
+                    const exSlug = (0, creatorUtilities_2.slugify)(previousExercise.id + "-" + previousExercise.title);
+                    // llist the files un
+                    const [files] = await bucket.getFiles({
+                        prefix: `courses/${courseSlug}/exercises/${exSlug}/README`,
+                    });
+                    // select any README
+                    const readmeFiles = files.map(f => f.name);
+                    const readmeFile = readmeFiles.find(f => f.includes("README"));
+                    if (readmeFile) {
+                        const [content] = await bucket.file(readmeFile).download();
+                        previousReadme = content.toString();
+                    }
+                }
+                // Use new two-phase generation workflow
+                const completionId = await startInitialContentGeneration(rigoToken, syllabus.lessons, syllabus.courseInfo, exercise, courseSlug, syllabus.courseInfo.purpose, previousReadme +
+                    "\n\nThe user provided the following feedback related to the content of the course so far: \n\n" +
+                    feedback);
+                // A new job by the user, so the automatic retries start over.
+                syllabus.lessons[exerciseIndex].status = "GENERATING";
+                syllabus.lessons[exerciseIndex].translations = {
+                    [syllabus.courseInfo.language || "en"]: startedJob(completionId),
+                };
+                console.log("Lesson", syllabus.lessons[exerciseIndex]);
+                if (syllabus.feedback && typeof syllabus.feedback === "string") {
+                    syllabus.feedback += "\n\n" + feedback;
+                }
+                else {
+                    syllabus.feedback = feedback;
+                }
+                syllabus.generationMode = mode;
+                await saveSyllabus(courseSlug, syllabus, bucket);
+            });
             res.json({ status: "SUCCESS" });
         }));
         // TODO: Check if this command is being used
@@ -1742,112 +1824,132 @@ class ServeCommand extends SessionCommand_1.default {
             const { courseSlug, lessonUID, rigoToken } = req.params;
             const response = req.body;
             console.log("RECEIVING INITIAL CONTENT WEBHOOK", response);
-            const syllabus = await getSyllabus(courseSlug, bucket);
-            const exerciseIndex = syllabus.lessons.findIndex(lesson => lesson.uid === lessonUID);
-            if (exerciseIndex === -1) {
-                console.error("Exercise not found receiving webhook:", lessonUID);
-                return res.json({ status: "ERROR", error: "Exercise not found" });
-            }
-            let exercise = syllabus.lessons[exerciseIndex];
-            const exSlug = (0, creatorUtilities_2.slugify)(exercise.id + "-" + exercise.title);
-            // Handle errors
-            if (response.status === "ERROR") {
-                await updateLessonStatusToError(courseSlug, lessonUID, bucket);
-                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                    lesson: exSlug,
-                    status: "error",
-                    log: `❌ Error generating initial content for lesson ${exSlug}`,
-                });
-                // Retry initial content generation
-                try {
-                    (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                        lesson: exSlug,
-                        status: "generating",
-                        log: `🔄 Retrying initial content generation for lesson ${exSlug}`,
-                    });
-                    const retryCompletionId = await startInitialContentGeneration(rigoToken, syllabus.lessons, syllabus.courseInfo, exercise, courseSlug, syllabus.courseInfo.purpose, "");
-                    // Update lesson status to show it's retrying
-                    exercise.status = "GENERATING";
-                    exercise.translations = {
-                        [syllabus.courseInfo.language || "en"]: {
-                            completionId: retryCompletionId,
-                            startedAt: Date.now(),
-                            completedAt: 0,
-                        },
-                    };
-                    await saveSyllabus(courseSlug, syllabus, bucket);
-                }
-                catch (retryError) {
-                    console.error("Error retrying initial content generation:", retryError);
-                    (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                        lesson: lessonUID,
-                        status: "error",
-                        log: `❌ Failed to retry initial content generation for lesson ${lessonUID}`,
-                    });
-                }
-                return res.json({ status: "ERROR" });
-            }
             try {
-                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                    lesson: exSlug,
-                    status: "generating",
-                    log: `✅ Initial content generated for lesson ${exSlug}`,
-                });
-                // Update lesson with initial content
-                exercise = await updateLessonWithInitialContent(courseSlug, lessonUID, response.parsed, bucket);
-                if (!exercise) {
-                    console.error("Exercise not found after updating initial content");
-                    return res.json({ status: "ERROR", error: "Exercise not found" });
-                }
-                let lastLesson = "";
-                const prevLessonIndex = exerciseIndex - 1;
-                if (prevLessonIndex >= 0) {
+                // In the course queue, nothing else saves the syllabus between
+                // reading the lesson and saving it.
+                await serializeByCourse(courseSlug, async () => {
+                    const syllabus = await getSyllabus(courseSlug, bucket);
+                    const language = syllabus.courseInfo.language || "en";
+                    const exerciseIndex = syllabus.lessons.findIndex(lesson => lesson.uid === lessonUID);
+                    if (exerciseIndex === -1) {
+                        console.error("Exercise not found receiving webhook:", lessonUID);
+                        return res.json({ status: "ERROR", error: "Exercise not found" });
+                    }
+                    let exercise = syllabus.lessons[exerciseIndex];
+                    const exSlug = (0, creatorUtilities_2.slugify)(exercise.id + "-" + exercise.title);
+                    if ((0, generationRetry_1.isStaleWebhook)(exercise, language, response.id)) {
+                        console.log(`Ignoring initial content webhook of job ${response.id} for lesson ${exSlug}: the lesson no longer waits for it`);
+                        return res.json({ status: "IGNORED" });
+                    }
+                    // Handle errors
+                    if (response.status === "ERROR") {
+                        console.error(`Initial content job ${response.id} failed for lesson ${exSlug}:`, response.status_text);
+                        const retryPlan = (0, generationRetry_1.planGenerationRetry)(exercise, language, response.status_text);
+                        if (!retryPlan.retry) {
+                            await updateLessonStatusToError(courseSlug, lessonUID, bucket);
+                            (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                                lesson: exSlug,
+                                status: "error",
+                                log: noRetryLog(retryPlan.reason, "initial content", exSlug),
+                            });
+                            return res.json({ status: "ERROR" });
+                        }
+                        const attempt = retryPlan.attempt;
+                        try {
+                            (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                                lesson: exSlug,
+                                status: "generating",
+                                log: `🔄 Retrying initial content generation for lesson ${exSlug} (${attempt} of ${generationRetry_1.MAX_AUTO_RETRIES})`,
+                            });
+                            const retryCompletionId = await startInitialContentGeneration(rigoToken, syllabus.lessons, syllabus.courseInfo, exercise, courseSlug, syllabus.courseInfo.purpose, "");
+                            await patchLesson(courseSlug, lessonUID, bucket, (lesson, lang) => {
+                                lesson.status = "GENERATING";
+                                lesson.translations = {
+                                    [lang]: startedJob(retryCompletionId, attempt),
+                                };
+                            });
+                        }
+                        catch (retryError) {
+                            console.error("Error retrying initial content generation:", retryError);
+                            await updateLessonStatusToError(courseSlug, lessonUID, bucket);
+                            (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                                lesson: exSlug,
+                                status: "error",
+                                log: `❌ Failed to retry initial content generation for lesson ${exSlug}`,
+                            });
+                        }
+                        return res.json({ status: "ERROR" });
+                    }
                     try {
-                        const prevLesson = syllabus.lessons[prevLessonIndex];
-                        // search the lesson content in the bucket
-                        const prevLessonSlug = (0, creatorUtilities_2.slugify)(prevLesson.id + "-" + prevLesson.title);
-                        const file = bucket.file(`courses/${courseSlug}/exercises/${prevLessonSlug}/README${(0, creatorUtilities_1.getReadmeExtension)(syllabus.courseInfo.language || "en")}`);
-                        const [content] = await file.download();
-                        lastLesson = content.toString();
+                        (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                            lesson: exSlug,
+                            status: "generating",
+                            log: `✅ Initial content generated for lesson ${exSlug}`,
+                        });
+                        // Update lesson with initial content
+                        exercise = await updateLessonWithInitialContent(courseSlug, lessonUID, response.parsed, bucket);
+                        if (!exercise) {
+                            console.error("Exercise not found after updating initial content");
+                            return res.json({
+                                status: "ERROR",
+                                error: "Exercise not found",
+                            });
+                        }
+                        let lastLesson = "";
+                        const prevLessonIndex = exerciseIndex - 1;
+                        if (prevLessonIndex >= 0) {
+                            try {
+                                const prevLesson = syllabus.lessons[prevLessonIndex];
+                                // search the lesson content in the bucket
+                                const prevLessonSlug = (0, creatorUtilities_2.slugify)(prevLesson.id + "-" + prevLesson.title);
+                                const file = bucket.file(`courses/${courseSlug}/exercises/${prevLessonSlug}/README${(0, creatorUtilities_1.getReadmeExtension)(language)}`);
+                                const [content] = await file.download();
+                                lastLesson = content.toString();
+                            }
+                            catch (error) {
+                                console.error("Error searching previous lesson content:", error);
+                            }
+                        }
+                        const completionId = await startInteractivityGeneration(rigoToken, syllabus.lessons, syllabus.courseInfo, exercise, courseSlug, syllabus.courseInfo.purpose, bucket, lastLesson);
+                        // Saved on a fresh read: `syllabus` was read before the initial
+                        // content was saved, and saving it would erase that content.
+                        await patchLesson(courseSlug, lessonUID, bucket, (lesson, lang) => {
+                            lesson.status = "GENERATING";
+                            lesson.translations = { [lang]: startedJob(completionId) };
+                        });
+                        (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                            lesson: exSlug,
+                            status: "generating",
+                            log: `🔄 Starting interactivity phase for lesson ${exercise.title}`,
+                        });
+                        (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                            lesson: exSlug,
+                            status: "initial-content-complete",
+                            log: `✅ Initial content generated for lesson ${exSlug}, starting interactivity phase`,
+                        });
+                        res.json({ status: "SUCCESS" });
                     }
                     catch (error) {
-                        console.error("Error searching previous lesson content:", error);
+                        console.error("Error processing initial content webhook:", error);
+                        await updateLessonStatusToError(courseSlug, lessonUID, bucket);
+                        (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                            lesson: exSlug,
+                            status: "error",
+                            log: `❌ Error processing initial content for lesson ${exSlug}`,
+                        });
+                        res
+                            .status(500)
+                            .json({ status: "ERROR", error: error.message });
                     }
-                }
-                const completionId = await startInteractivityGeneration(rigoToken, syllabus.lessons, syllabus.courseInfo, exercise, courseSlug, syllabus.courseInfo.purpose, bucket, lastLesson);
-                // Update lesson status to show it's in Phase 2
-                exercise.status = "GENERATING";
-                exercise.translations = {
-                    [syllabus.courseInfo.language || "en"]: {
-                        completionId,
-                        startedAt: Date.now(),
-                        completedAt: 0,
-                    },
-                };
-                await saveSyllabus(courseSlug, syllabus, bucket);
-                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                    lesson: exSlug,
-                    status: "generating",
-                    log: `🔄 Starting interactivity phase for lesson ${exercise.title}`,
                 });
-                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                    lesson: exSlug,
-                    status: "initial-content-complete",
-                    log: `✅ Initial content generated for lesson ${exSlug}, starting interactivity phase`,
-                });
-                res.json({ status: "SUCCESS" });
             }
             catch (error) {
-                console.error("Error processing initial content webhook:", error);
-                await updateLessonStatusToError(courseSlug, lessonUID, bucket);
-                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                    lesson: exSlug,
-                    status: "error",
-                    log: `❌ Error processing initial content for lesson ${exSlug}`,
-                });
-                res
-                    .status(500)
-                    .json({ status: "ERROR", error: error.message });
+                console.error("Error handling initial content webhook:", error);
+                if (!res.headersSent) {
+                    res
+                        .status(500)
+                        .json({ status: "ERROR", error: error.message });
+                }
             }
         });
         // Phase 2: Interactivity generation webhook (replaces exercise-processor logic)
@@ -1857,116 +1959,184 @@ class ServeCommand extends SessionCommand_1.default {
             console.log("RECEIVING INTERACTIVITY WEBHOOK");
             // console.log("LESSON UID", lessonUID)
             // console.log("RESPONSE", response)
-            // Handle errors
-            if (response.status === "ERROR") {
-                await updateLessonStatusToError(courseSlug, lessonUID, bucket);
-                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                    lesson: lessonUID,
-                    status: "error",
-                    log: `❌ Error adding interactivity to lesson ${lessonUID}`,
-                });
-                // Retry interactivity generation
-                try {
+            try {
+                // In the course queue, nothing else saves the syllabus between
+                // reading the lesson and saving it.
+                await serializeByCourse(courseSlug, async () => {
+                    var _a, _b, _c;
                     const syllabus = await getSyllabus(courseSlug, bucket);
-                    const lessonIndex = syllabus.lessons.findIndex(lesson => lesson.uid === lessonUID);
-                    const exercise = syllabus.lessons[lessonIndex];
-                    if (exercise && exercise.initialContent) {
+                    const language = syllabus.courseInfo.language || "en";
+                    const exerciseIndex = syllabus.lessons.findIndex(lesson => lesson.uid === lessonUID);
+                    if (exerciseIndex === -1) {
+                        console.error("Exercise not found receiving webhook:", lessonUID);
+                        return res.json({ status: "ERROR", error: "Exercise not found" });
+                    }
+                    const exercise = syllabus.lessons[exerciseIndex];
+                    const exSlug = (0, creatorUtilities_2.slugify)(exercise.id + "-" + exercise.title);
+                    if ((0, generationRetry_1.isStaleWebhook)(exercise, language, response.id)) {
+                        console.log(`Ignoring interactivity webhook of job ${response.id} for lesson ${exSlug}: the lesson no longer waits for it`);
+                        return res.json({ status: "IGNORED" });
+                    }
+                    // Handle errors
+                    if (response.status === "ERROR") {
+                        console.error(`Interactivity job ${response.id} failed for lesson ${exSlug}:`, response.status_text);
+                        // Every retry uses v1. A failed v2 job gets its v1 retry even
+                        // when its error would repeat, because the error belongs to the
+                        // v2 template.
+                        const { fromV2, retryStatusText } = (0, interactivityPlan_1.describeInteractivityFailure)(req.query, response.status_text);
+                        const retryPlan = (0, generationRetry_1.planGenerationRetry)(exercise, language, retryStatusText);
+                        // The retry builds on the initial content, so without it there
+                        // is nothing to retry.
+                        if (!retryPlan.retry || !exercise.initialContent) {
+                            await updateLessonStatusToError(courseSlug, lessonUID, bucket);
+                            (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                                lesson: exSlug,
+                                status: "error",
+                                log: retryPlan.retry ?
+                                    `❌ Error adding interactivity to lesson ${exSlug}. Its initial content is missing, so it was not retried` :
+                                    noRetryLog(retryPlan.reason, "interactivity", exSlug),
+                            });
+                            return res.json({ status: "ERROR" });
+                        }
+                        const attempt = retryPlan.attempt;
+                        try {
+                            (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                                lesson: exSlug,
+                                status: "generating",
+                                log: fromV2 ?
+                                    `⚠️ Structured interactivity failed for lesson ${exSlug}, retrying with the previous method (${attempt} of ${generationRetry_1.MAX_AUTO_RETRIES})` :
+                                    `🔄 Retrying interactivity generation for lesson ${exSlug} (${attempt} of ${generationRetry_1.MAX_AUTO_RETRIES})`,
+                            });
+                            // Get previous lesson content for context
+                            let lastLesson = "";
+                            const prevLessonIndex = exerciseIndex - 1;
+                            if (prevLessonIndex >= 0) {
+                                try {
+                                    const prevLesson = syllabus.lessons[prevLessonIndex];
+                                    const prevLessonSlug = (0, creatorUtilities_2.slugify)(prevLesson.id + "-" + prevLesson.title);
+                                    const file = bucket.file(`courses/${courseSlug}/exercises/${prevLessonSlug}/README${(0, creatorUtilities_1.getReadmeExtension)(language)}`);
+                                    const [content] = await file.download();
+                                    lastLesson = content.toString();
+                                }
+                                catch (error) {
+                                    console.error("Error getting previous lesson content for retry:", error);
+                                }
+                            }
+                            const retryCompletionId = await startInteractivityGeneration(rigoToken, syllabus.lessons, syllabus.courseInfo, exercise, courseSlug, syllabus.courseInfo.purpose, bucket, lastLesson, { forceV1: true });
+                            await patchLesson(courseSlug, lessonUID, bucket, (lesson, lang) => {
+                                lesson.status = "GENERATING";
+                                lesson.translations = {
+                                    [lang]: startedJob(retryCompletionId, attempt),
+                                };
+                            });
+                        }
+                        catch (retryError) {
+                            console.error("Error retrying interactivity generation:", retryError);
+                            await updateLessonStatusToError(courseSlug, lessonUID, bucket);
+                            (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                                lesson: exSlug,
+                                status: "error",
+                                log: `❌ Failed to retry interactivity generation for lesson ${exSlug}`,
+                            });
+                        }
+                        return res.json({ status: "ERROR" });
+                    }
+                    try {
+                        let finalContent = (_a = response.parsed) === null || _a === void 0 ? void 0 : _a.final_content;
+                        let usedComponents = (_b = response.parsed) === null || _b === void 0 ? void 0 : _b.used_components;
+                        // The structured template (v2) returns component data and
+                        // placeholders; the CLI writes the component markdown.
+                        if (req.query.tpl === "v2") {
+                            if (!Array.isArray((_c = response.parsed) === null || _c === void 0 ? void 0 : _c.multiple_choice_question)) {
+                                console.warn(`Structured interactivity response for ${exSlug} has no component lists`);
+                            }
+                            const guide = componentsGuide_1.componentsGuideLoader.peek();
+                            const result = (0, structuredComponents_1.processInteractivityResult)(response.parsed, {
+                                stepType: exercise.type,
+                                isFirstOrLast: exerciseIndex === 0 ||
+                                    exerciseIndex === syllabus.lessons.length - 1,
+                                lessonId: exercise.id,
+                                decidedBy: guide ? (0, componentsGuide_1.decidedByFromGuide)(guide) : undefined,
+                            });
+                            finalContent = result.markdown;
+                            usedComponents = result.usedComponents;
+                            if (result.warnings.length > 0) {
+                                console.warn(`Component warnings for ${exSlug}:\n- ${result.warnings
+                                    .map(warning => warning.message)
+                                    .join("\n- ")}`);
+                            }
+                            if (result.dropped.length > 0) {
+                                console.warn(`Components removed from ${exSlug}:\n- ${result.dropped
+                                    .map(issue => issue.message)
+                                    .join("\n- ")}`);
+                                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                                    lesson: exSlug,
+                                    status: "generating",
+                                    log: `⚠️ ${result.dropped.length} component(s) removed from lesson ${exercise.title} because they could not be rendered: ${result.dropped
+                                        .map(issue => issue.message)
+                                        .join("; ")}`,
+                                });
+                            }
+                            if (exercise.type === "QUIZ" && result.assessmentCount === 0) {
+                                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                                    lesson: exSlug,
+                                    status: "generating",
+                                    log: `⚠️ The quiz ${exercise.title} has no questions; review it or regenerate it`,
+                                });
+                            }
+                        }
+                        // Process readability of final content
+                        const readability = (0, creatorUtilities_2.checkReadability)(finalContent, PARAMS.max_words, 3);
                         (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                            lesson: lessonUID,
+                            lesson: exSlug,
                             status: "generating",
-                            log: `🔄 Retrying interactivity generation for lesson ${lessonUID}`,
+                            log: `🔄 The lesson ${exercise.title} has a readability score of ${readability.fkglResult.fkgl}`,
                         });
-                        // Get previous lesson content for context
-                        let lastLesson = "";
-                        const prevLessonIndex = lessonIndex - 1;
-                        if (prevLessonIndex >= 0) {
-                            try {
-                                const prevLesson = syllabus.lessons[prevLessonIndex];
-                                const prevLessonSlug = (0, creatorUtilities_2.slugify)(prevLesson.id + "-" + prevLesson.title);
-                                const file = bucket.file(`courses/${courseSlug}/exercises/${prevLessonSlug}/README${(0, creatorUtilities_1.getReadmeExtension)(syllabus.courseInfo.language || "en")}`);
-                                const [content] = await file.download();
-                                lastLesson = content.toString();
-                            }
-                            catch (error) {
-                                console.error("Error getting previous lesson content for retry:", error);
-                            }
+                        // Upload README with final content
+                        const exercisesDir = `courses/${courseSlug}/exercises`;
+                        const targetDir = `${exercisesDir}/${exSlug}`;
+                        const readmeFilename = `README${(0, creatorUtilities_1.getReadmeExtension)(response.parsed.output_language || language)}`;
+                        await (0, bucketIo_1.uploadFileToBucket)(bucket, readability.newMarkdown, `${targetDir}/${readmeFilename}`);
+                        // Update used components (v1: listed by the AI; v2: the
+                        // components that were actually written)
+                        if (Array.isArray(usedComponents)) {
+                            await updateUsedComponents(courseSlug, usedComponents, bucket);
+                            (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                                lesson: exSlug,
+                                status: "generating",
+                                log: `📊 Updated component usage tracking: ${usedComponents.join(", ")}`,
+                            });
                         }
-                        const retryCompletionId = await startInteractivityGeneration(rigoToken, syllabus.lessons, syllabus.courseInfo, exercise, courseSlug, syllabus.courseInfo.purpose, bucket, lastLesson);
-                        // Update lesson status to show it's retrying
-                        exercise.status = "GENERATING";
-                        exercise.translations = {
-                            [syllabus.courseInfo.language || "en"]: {
-                                completionId: retryCompletionId,
-                                startedAt: Date.now(),
-                                completedAt: 0,
-                            },
-                        };
-                        await saveSyllabus(courseSlug, syllabus, bucket);
+                        // Continue with next lesson
+                        await continueWithNextLesson(courseSlug, exerciseIndex, rigoToken, finalContent, bucket);
+                        (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                            lesson: exSlug,
+                            status: "done",
+                            log: `✅ The lesson ${exercise.id} - ${exercise.title} has been generated successfully with interactivity!`,
+                        });
+                        res.json({ status: "SUCCESS" });
+                    }
+                    catch (error) {
+                        console.error("Error processing interactivity webhook:", error);
+                        await updateLessonStatusToError(courseSlug, lessonUID, bucket);
+                        (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
+                            lesson: exSlug,
+                            status: "error",
+                            log: `❌ Error processing interactivity for lesson ${exSlug}`,
+                        });
+                        res
+                            .status(500)
+                            .json({ status: "ERROR", error: error.message });
                     }
-                }
-                catch (retryError) {
-                    console.error("Error retrying interactivity generation:", retryError);
-                    (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                        lesson: lessonUID,
-                        status: "error",
-                        log: `❌ Failed to retry interactivity generation for lesson ${lessonUID}`,
-                    });
-                }
-                return res.json({ status: "ERROR" });
-            }
-            try {
-                const syllabus = await getSyllabus(courseSlug, bucket);
-                const exerciseIndex = syllabus.lessons.findIndex(lesson => lesson.uid === lessonUID);
-                if (exerciseIndex === -1) {
-                    console.error("Exercise not found receiving webhook:", lessonUID);
-                    return res.json({ status: "ERROR", error: "Exercise not found" });
-                }
-                const exercise = syllabus.lessons[exerciseIndex];
-                const exSlug = (0, creatorUtilities_2.slugify)(exercise.id + "-" + exercise.title);
-                // Process readability of final content
-                const readability = (0, creatorUtilities_2.checkReadability)(response.parsed.final_content, PARAMS.max_words, 3);
-                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                    lesson: exSlug,
-                    status: "generating",
-                    log: `🔄 The lesson ${exercise.title} has a readability score of ${readability.fkglResult.fkgl}`,
-                });
-                // Upload README with final content
-                const exercisesDir = `courses/${courseSlug}/exercises`;
-                const targetDir = `${exercisesDir}/${exSlug}`;
-                const readmeFilename = `README${(0, creatorUtilities_1.getReadmeExtension)(response.parsed.output_language ||
-                    syllabus.courseInfo.language ||
-                    "en")}`;
-                await (0, bucketIo_1.uploadFileToBucket)(bucket, readability.newMarkdown, `${targetDir}/${readmeFilename}`);
-                // Update used components if provided by the AI
-                if (response.parsed.used_components &&
-                    Array.isArray(response.parsed.used_components)) {
-                    await updateUsedComponents(courseSlug, response.parsed.used_components, bucket);
-                    (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                        lesson: exSlug,
-                        status: "generating",
-                        log: `📊 Updated component usage tracking: ${response.parsed.used_components.join(", ")}`,
-                    });
-                }
-                // Continue with next lesson
-                await continueWithNextLesson(courseSlug, exerciseIndex, rigoToken, response.parsed.final_content, bucket);
-                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                    lesson: exSlug,
-                    status: "done",
-                    log: `✅ The lesson ${exercise.id} - ${exercise.title} has been generated successfully with interactivity!`,
                 });
-                res.json({ status: "SUCCESS" });
             }
             catch (error) {
-                console.error("Error processing interactivity webhook:", error);
-                await updateLessonStatusToError(courseSlug, lessonUID, bucket);
-                (0, creatorSocket_1.emitToCourse)(courseSlug, "course-creation", {
-                    lesson: lessonUID,
-                    status: "error",
-                    log: `❌ Error processing interactivity for lesson ${lessonUID}`,
-                });
-                res
-                    .status(500)
-                    .json({ status: "ERROR", error: error.message });
+                console.error("Error handling interactivity webhook:", error);
+                if (!res.headersSent) {
+                    res
+                        .status(500)
+                        .json({ status: "ERROR", error: error.message });
+                }
             }
         });
         // The following endpoint is used to store an incoming translation where it supposed to be
@@ -2649,19 +2819,20 @@ class ServeCommand extends SessionCommand_1.default {
                 translations: {},
                 uid: stepSlug,
             };
-            const newLessons = (0, creatorUtilities_1.insertStepInCorrectPosition)(initialSyllabus.lessons, newLesson);
-            // Use new two-phase generation workflow
-            const completionId = await startInitialContentGeneration(rigoToken, newLessons, initialSyllabus.courseInfo, newLesson, courseSlug, initialSyllabus.courseInfo.purpose, "lastResult");
-            newLesson.translations = {
-                [initialSyllabus.courseInfo.language || "en"]: {
-                    completionId,
-                    startedAt: Date.now(),
-                    completedAt: 0,
-                },
-            };
-            await (0, bucketIo_1.uploadFileToBucket)(bucket, JSON.stringify(Object.assign(Object.assign({}, initialSyllabus), { lessons: newLessons })), `courses/${courseSlug}/.learn/initialSyllabus.json`);
-            const targetDir = `courses/${courseSlug}/exercises/${stepSlug}`;
-            await uploadInitialReadme(bucket, stepSlug, targetDir, initialSyllabus.courseInfo);
+            // In the course queue, so the webhook of this job finds the new lesson
+            // saved, and the syllabus saved here is not older than the last save.
+            await serializeByCourse(courseSlug, async () => {
+                const syllabus = await getSyllabus(courseSlug, bucket);
+                const newLessons = (0, creatorUtilities_1.insertStepInCorrectPosition)(syllabus.lessons, newLesson);
+                // Use new two-phase generation workflow
+                const completionId = await startInitialContentGeneration(rigoToken, newLessons, syllabus.courseInfo, newLesson, courseSlug, syllabus.courseInfo.purpose, "lastResult");
+                newLesson.translations = {
+                    [syllabus.courseInfo.language || "en"]: startedJob(completionId),
+                };
+                await (0, bucketIo_1.uploadFileToBucket)(bucket, JSON.stringify(Object.assign(Object.assign({}, syllabus), { lessons: newLessons })), `courses/${courseSlug}/.learn/initialSyllabus.json`);
+                const targetDir = `courses/${courseSlug}/exercises/${stepSlug}`;
+                await uploadInitialReadme(bucket, stepSlug, targetDir, syllabus.courseInfo);
+            });
             res.json({ status: "SUCCESS", message: "Exercise generati on started!" });
         });
         app.put("/actions/rename", async (req, res) => {