@studious-lms/server 1.3.0 → 1.4.1

package/src/pipelines/labChatPrompt.ts

@@ -0,0 +1,68 @@
+export const buildLabChatSystemPrompt = (context: string): string => `${context}
+
+IMPORTANT INSTRUCTIONS:
+- Use the context information above (subject, topic, difficulty, objectives, etc.) as your foundation
+- A separate CLASS CONTEXT message lists this class's sections, mark schemes, grading boundaries, worksheets, files, and students with their database IDs
+- Do NOT ask teachers about technical details (hex codes, format numbers, IDs, schema fields). Use sensible defaults yourself.
+- Only ask clarifying questions about content or pedagogy (e.g., topic scope, difficulty, number of questions). Never ask "what hex color?" or "which format?"
+- When creating content, make reasonable choices: pick nice default colors, use standard formatting. Teachers care about the content, not implementation.
+- Only output final course materials when you have sufficient details about the content itself
+- Do not use markdown in your responses - use plain text only
+- You are primarily a chatbot - only provide docs/assignments when the teacher explicitly requests them
+- If the request is vague, ask 1-2 high-level clarifying questions (topic, scope, style) - never technical ones
+
+CRITICAL: REFERENCING OBJECTS - NAMES vs IDs:
+- In "text": Refer to objects by NAME (e.g., "Unit 1", "Biology Rubric", "Cell_Structure_Worksheet")
+- In "assignmentsToCreate", "worksheetsToCreate", "sectionsToCreate": Use DATABASE IDs from the CLASS CONTEXT
+  * sectionId, gradingBoundaryId, markSchemeId, worksheetIds, studentIds, attachments[].id must be real IDs from the context
+  * If the class has no sections/mark schemes/grading boundaries, use sectionsToCreate first, or omit optional IDs
+
+RESPONSE FORMAT (JSON):
+{ "text": string, "docs": null | array, "worksheetsToCreate": array, "sectionsToCreate": array, "assignmentsToCreate": null | array }
+
+CRITICAL ARRAY RULES:
+- "worksheetsToCreate" must always be an array. Use [] when there are no worksheets to create.
+- "sectionsToCreate" must always be an array. Use [] when there are no sections to create.
+- Do not return null for "worksheetsToCreate" or "sectionsToCreate".
+
+CRITICAL - "text" field rules:
+- "text" must be a SHORT conversational summary (2-4 sentences). Plain text, no markdown.
+- NEVER list assignment/worksheet fields in text (no "Type:", "dueDate:", "worksheetIds:", "sectionId:", etc.)
+- NEVER dump schema or JSON-like output in text. The teacher sees the actual content in UI cards below.
+- Good example: "I've created 4 assignments for Unit 1: Week 1 homework on the worksheet, Week 2 quiz, Week 3 lab activity, and Week 4 review test. You can create them below."
+- Bad example: "Week 1 - Homework. Type: HOMEWORK. dueDate: 2026-03-10. worksheetIds: [...]" - NEVER do this.
+
+- "docs": PDF documents when creating course materials (worksheets, handouts, answer keys)
+- "worksheetsToCreate": Worksheets with questions when teacher wants structured assessments. Always return an array.
+- "sectionsToCreate": New sections when the class has none or teacher wants new units. Always return an array.
+- "assignmentsToCreate": Assignments when teacher explicitly requests them. Use IDs from CLASS CONTEXT. The structured data goes HERE only, not in text.
+
+WHEN CREATING DOCUMENTS (docs):
+- docs: [ { "title": string, "blocks": [ { "format": 0-12, "content": string | string[], "metadata"?: {...} } ] } ]
+- Format: 0=H1, 1=H2, 2=H3, 3=H4, 4=H5, 5=H6, 6=PARAGRAPH, 7=BULLET, 8=NUMBERED, 9=TABLE, 10=IMAGE, 11=CODE_BLOCK, 12=QUOTE
+- Bullets (7) and Numbered (8): content is array of strings; do NOT include * or 1. 2. 3. - renderer adds them
+- Table (9) and Image (10) not supported - do not emit
+- Colors: use sensible defaults (e.g. "#3B82F6" blue, "#10B981" green) - never ask the teacher
+
+WHEN CREATING WORKSHEETS (worksheetsToCreate):
+- Return an array every time, even when empty.
+- Question types: MULTIPLE_CHOICE, TRUE_FALSE, SHORT_ANSWER, LONG_ANSWER, MATH_EXPRESSION, ESSAY
+- For MULTIPLE_CHOICE/TRUE_FALSE: options array with { id, text, isCorrect }
+- For others: options can be empty; answer holds the key
+- markScheme: array of { id, points, description } for rubric items
+- points: total points per question; order: display order
+
+WHEN CREATING SECTIONS (sectionsToCreate):
+- Return an array every time, even when empty.
+- Use when class has no sections or teacher wants new units (e.g., "Unit 1", "Chapter 3")
+- color: pick a nice default (e.g. "#3B82F6") - do not ask
+
+WHEN CREATING ASSIGNMENTS (assignmentsToCreate):
+- Put ALL assignment data (title, type, dueDate, instructions, worksheetIds, etc.) ONLY in assignmentsToCreate. The "text" field gets a brief friendly summary only.
+- Use IDs from CLASS CONTEXT. If class has no sections, suggest sectionsToCreate first.
+- type: HOMEWORK | QUIZ | TEST | PROJECT | ESSAY | DISCUSSION | PRESENTATION | LAB | OTHER
+- sectionId, gradingBoundaryId, markSchemeId: use from context; omit if class has none (suggest creating first)
+- studentIds: empty array = assign to all; otherwise list specific student IDs
+- worksheetIds: IDs of existing worksheets; empty if using docs-only or new worksheets
+- attachments[].id: file IDs from CLASS CONTEXT (PDFs, documents)
+- acceptFiles, acceptExtendedResponse, acceptWorksheet: set based on assignment type`;

package/src/routers/_app.ts

@@ -20,6 +20,7 @@ import { newtonChatRouter } from "./newtonChat.js";
 import { marketingRouter } from "./marketing.js";
 import { worksheetRouter } from "./worksheet.js";
 import { commentRouter } from "./comment.js";
+import { studentProgressRouter } from "./studentProgress.js";
 
 export const appRouter = createTRPCRouter({
   class: classRouter,
@@ -41,7 +42,8 @@ export const appRouter = createTRPCRouter({
   marketing: marketingRouter,
   worksheet: worksheetRouter,
   comment: commentRouter,
-}); 
+  studentProgress: studentProgressRouter,
+});
 
 // Export type router type definition
 export type AppRouter = typeof appRouter;
@@ -49,4 +51,4 @@ export type RouterInputs = inferRouterInputs<AppRouter>;
 export type RouterOutputs = inferRouterOutputs<AppRouter>;
 
 // Export caller
-export const createCaller = createCallerFactory(appRouter); 
+export const createCaller = createCallerFactory(appRouter);

package/src/routers/class.ts

@@ -318,7 +318,7 @@ export const classRouter = createTRPCRouter({
     .input(z.object({ classId: z.string() }))
     .mutation(({ ctx, input }) => exportClass(input.classId, ctx.user?.id ?? "")),
 
-  importClass: protectedTeacherProcedure
+  importClass: protectedProcedure
     .input(
       z.object({
         classId: z.string(),

package/src/routers/labChat.ts

@@ -6,6 +6,7 @@ import {
   listLabChats,
   postToLabChat,
   deleteLabChat,
+  rerunLastResponse,
 } from "../services/labChat.js";
 
 export const labChatRouter = createTRPCRouter({
@@ -54,4 +55,10 @@ export const labChatRouter = createTRPCRouter({
     .mutation(({ ctx, input }) =>
       deleteLabChat(ctx.user!.id, input.labChatId)
     ),
+
+  rerunLastResponse: protectedProcedure
+    .input(z.object({ labChatId: z.string() }))
+    .mutation(({ ctx, input }) =>
+      rerunLastResponse(ctx.user!.id, input.labChatId)
+    ),
 });

package/src/routers/message.ts

@@ -7,6 +7,7 @@ import {
   deleteMessage,
   markAsRead,
   markMentionsAsRead,
+  markSuggestionCreated,
   getUnreadCount,
 } from "../services/message.js";
 
@@ -75,6 +76,18 @@ export const messageRouter = createTRPCRouter({
       markMentionsAsRead(ctx.user!.id, input.conversationId)
     ),
 
+  markSuggestionCreated: protectedProcedure
+    .input(
+      z.object({
+        messageId: z.string(),
+        type: z.enum(["assignment", "worksheet", "section"]),
+        index: z.number().int().min(0),
+      })
+    )
+    .mutation(({ ctx, input }) =>
+      markSuggestionCreated(ctx.user!.id, input)
+    ),
+
   getUnreadCount: protectedProcedure
     .input(z.object({ conversationId: z.string() }))
     .query(({ ctx, input }) =>

package/src/routers/studentProgress.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { createTRPCRouter, protectedClassMemberProcedure } from "../trpc.js";
+import {
+  chatAboutStudentProgress,
+  getStudentProgressRecommendations,
+} from "../services/studentProgress.js";
+
+const progressInputSchema = z.object({
+  classId: z.string(),
+  studentId: z.string(),
+});
+
+export const studentProgressRouter = createTRPCRouter({
+  getRecommendations: protectedClassMemberProcedure
+    .input(progressInputSchema)
+    .query(({ ctx, input }) =>
+      getStudentProgressRecommendations(
+        ctx.user!.id,
+        input.classId,
+        input.studentId,
+      ),
+    ),
+
+  chat: protectedClassMemberProcedure
+    .input(
+      progressInputSchema.extend({
+        message: z.string().min(1).max(4000),
+        history: z
+          .array(
+            z.object({
+              role: z.enum(["user", "assistant"]),
+              content: z.string().min(1).max(4000),
+            }),
+          )
+          .max(8)
+          .optional(),
+      }),
+    )
+    .mutation(({ ctx, input }) =>
+      chatAboutStudentProgress(ctx.user!.id, {
+        classId: input.classId,
+        studentId: input.studentId,
+        message: input.message,
+        history: input.history,
+      }),
+    ),
+});

package/src/services/class.ts

@@ -608,15 +608,22 @@ export async function exportClass(classId: string, userId: string) {
 }
 
 export async function importClass(classId: string, userId: string, year: number, classData: Class & { classFiles: Folder | null }) {
-  const newClassId = await createClassByImport(classId, userId, year, classData);
-  
-
-  if (!newClassId) {
+  try {
+    const newClassId = await createClassByImport(classId, userId, year, classData);
+    if (!newClassId) {
+      throw new TRPCError({
+        code: "INTERNAL_SERVER_ERROR",
+        message: "Failed to import class",
+      });
+    }
+    return newClassId;
+  } catch (err) {
+    if (err instanceof TRPCError) throw err;
+    const message = err instanceof Error ? err.message : "Unknown error";
     throw new TRPCError({
       code: "INTERNAL_SERVER_ERROR",
-      message: "Failed to import class",
+      message: `Failed to import class: ${message}`,
+      cause: err,
     });
   }
-
-  return newClassId;
 }

package/src/services/labChat.ts

@@ -3,6 +3,7 @@
  * trigger AI responses, and broadcast via Pusher.
  */
 import { TRPCError } from "@trpc/server";
+import { GenerationStatus } from "@prisma/client";
 import { prisma } from "../lib/prisma.js";
 import { chatChannel, teacherChannel, pusher } from "../lib/pusher.js";
 import {
@@ -18,6 +19,7 @@ import {
 } from "../models/labChat.js";
 import { generateAndSendLabIntroduction, generateAndSendLabResponse } from "../pipelines/aiLabChat.js";
 import { isAIUser } from "../utils/aiUser.js";
+import { logger } from "../utils/logger.js";
 
 /** Create a lab chat with conversation and teacher members. Broadcasts via Pusher. */
 export async function createLabChat(
@@ -166,7 +168,20 @@ export async function getLabChat(userId: string, labChatId: string) {
     });
   }
 
-  return labChat;
+  const pendingMessage = await prisma.message.findFirst({
+    where: {
+      conversationId: labChat.conversationId,
+      status: GenerationStatus.PENDING,
+      senderId: { not: "AI_ASSISTANT" },
+    },
+    orderBy: { createdAt: "desc" },
+    select: { id: true },
+  });
+
+  return {
+    ...labChat,
+    pendingGenerationMessageId: pendingMessage?.id ?? null,
+  };
 }
 
 export async function listLabChats(userId: string, classId: string) {
@@ -229,6 +244,7 @@ export async function postToLabChat(
         content,
         senderId: userId,
         conversationId: labChat.conversationId,
+        ...(isAIUser(userId) ? {} : { status: GenerationStatus.PENDING }),
       },
       include: {
         sender: {
@@ -282,10 +298,25 @@ export async function postToLabChat(
   }
 
   if (!isAIUser(userId)) {
-    generateAndSendLabResponse(
-      labChatId,
-      content,
-      labChat.conversationId
+    try {
+      await pusher.trigger(teacherChannel(labChat.classId), "lab-response-pending", {
+        labChatId,
+        messageId: result.id,
+        conversationId: labChat.conversationId,
+      });
+    } catch (error) {
+      console.error("Failed to broadcast lab response pending:", error);
+    }
+    generateAndSendLabResponse(labChatId, content, {
+      classId: labChat.classId,
+      messageId: result.id,
+    }).catch((error) =>
+      logger.error("Failed to generate lab response", {
+        error,
+        labChatId,
+        messageId: result.id,
+        conversationId: labChat.conversationId,
+      })
     );
   }
 
@@ -350,3 +381,87 @@ export async function deleteLabChat(userId: string, labChatId: string) {
 
   return { success: true };
 }
+
+/** Rerun the last AI response for a lab chat. Deletes the last AI message and regenerates. */
+export async function rerunLastResponse(userId: string, labChatId: string) {
+  const labChat = await findLabChatForPost(labChatId, userId);
+  if (!labChat) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Lab chat not found or access denied",
+    });
+  }
+
+  const messages = await prisma.message.findMany({
+    where: { conversationId: labChat.conversationId },
+    orderBy: { createdAt: "desc" },
+    take: 10,
+    select: { id: true, content: true, senderId: true, createdAt: true },
+  });
+
+  const lastMessage = messages[0];
+  if (!lastMessage) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "No messages to rerun",
+    });
+  }
+
+  if (!isAIUser(lastMessage.senderId)) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Last message is not from AI – nothing to rerun",
+    });
+  }
+
+  const teacherMessage = messages.find((m) => !isAIUser(m.senderId));
+  if (!teacherMessage) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "No teacher message found to rerun from",
+    });
+  }
+
+  await prisma.$transaction([
+    prisma.message.delete({
+      where: { id: lastMessage.id },
+    }),
+    prisma.message.update({
+      where: { id: teacherMessage.id },
+      data: { status: GenerationStatus.PENDING },
+    }),
+  ]);
+
+  try {
+    await pusher.trigger(chatChannel(labChat.conversationId), "message-deleted", {
+      messageId: lastMessage.id,
+      conversationId: labChat.conversationId,
+      senderId: lastMessage.senderId,
+    });
+  } catch (error) {
+    console.error("Failed to broadcast message deletion:", error);
+  }
+  try {
+    await pusher.trigger(teacherChannel(labChat.classId), "lab-response-pending", {
+      labChatId,
+      messageId: teacherMessage.id,
+      conversationId: labChat.conversationId,
+    });
+  } catch (error) {
+    console.error("Failed to broadcast lab response pending:", error);
+  }
+
+  generateAndSendLabResponse(labChatId, teacherMessage.content, {
+    classId: labChat.classId,
+    messageId: teacherMessage.id,
+  }).catch((error) =>
+    logger.error("Failed to generate lab response", {
+      error,
+      labChatId,
+      messageId: teacherMessage.id,
+      conversationId: labChat.conversationId,
+    })
+  );
+
+  return { success: true };
+}

package/src/services/message.ts

@@ -357,6 +357,148 @@ export async function deleteMessage(userId: string, messageId: string) {
   return { success: true, messageId };
 }
 
+const CREATED_INDICES_KEY: Record<"assignment" | "worksheet" | "section", string> = {
+  assignment: "assignments",
+  worksheet: "worksheets",
+  section: "sections",
+};
+
+const MARK_SUGGESTION_MAX_RETRIES = 5;
+
+/** Mark an AI-suggested item as created. Stores in message meta for fast reads. */
+export async function markSuggestionCreated(
+  userId: string,
+  input: {
+    messageId: string;
+    type: "assignment" | "worksheet" | "section";
+    index: number;
+  }
+) {
+  const { messageId, type, index } = input;
+
+  const existingMessage = await findMessageByIdMinimal(messageId);
+  if (!existingMessage) {
+    throw new TRPCError({
+      code: "NOT_FOUND",
+      message: "Message not found",
+    });
+  }
+
+  const membership = await findConversationMembership(
+    existingMessage.conversationId,
+    userId
+  );
+  if (!membership) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Not a member of this conversation",
+    });
+  }
+
+  const conversationId = existingMessage.conversationId;
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt < MARK_SUGGESTION_MAX_RETRIES; attempt++) {
+    const msg = await prisma.message.findUnique({
+      where: { id: messageId },
+      select: { meta: true },
+    });
+    if (!msg) {
+      throw new TRPCError({
+        code: "NOT_FOUND",
+        message: "Message not found",
+      });
+    }
+
+    const currentMeta = (msg.meta as Record<string, unknown>) ?? {};
+    const createdIndices = (currentMeta.createdIndices as Record<string, number[]>) ?? {};
+    const typeIndices = createdIndices[CREATED_INDICES_KEY[type]] ?? [];
+    if (typeIndices.includes(index)) return { success: true };
+
+    const newTypeIndices = [...typeIndices, index].sort((a, b) => a - b);
+    const newMeta = {
+      ...currentMeta,
+      createdIndices: {
+        ...createdIndices,
+        [CREATED_INDICES_KEY[type]]: newTypeIndices,
+      },
+    };
+
+    const newMetaJson = JSON.stringify(newMeta);
+    const currentMetaJson = msg.meta === null ? null : JSON.stringify(msg.meta);
+
+    const updatedCount =
+      currentMetaJson === null
+        ? await prisma.$executeRaw`
+            UPDATE "Message" SET meta = ${newMetaJson}::jsonb
+            WHERE id = ${messageId} AND meta IS NULL
+          `
+        : await prisma.$executeRaw`
+            UPDATE "Message" SET meta = ${newMetaJson}::jsonb
+            WHERE id = ${messageId} AND meta = ${currentMetaJson}::jsonb
+          `;
+
+    if (Number(updatedCount) > 0) {
+      const updated = await prisma.message.findUnique({
+        where: { id: messageId },
+        include: {
+          sender: {
+            select: {
+              id: true,
+              username: true,
+              profile: {
+                select: { displayName: true, profilePicture: true },
+              },
+            },
+          },
+          attachments: { select: { id: true, name: true, type: true } },
+          mentions: { select: { userId: true } },
+        },
+      });
+
+      if (updated) {
+        const mentionedUserIds = updated.mentions.map((m) => m.userId);
+        try {
+          await pusher.trigger(
+            chatChannel(conversationId),
+            "message-updated",
+            {
+              id: updated.id,
+              content: updated.content,
+              senderId: updated.senderId,
+              conversationId: updated.conversationId,
+              createdAt: updated.createdAt,
+              sender: updated.sender,
+              attachments: updated.attachments ?? [],
+              meta: newMeta,
+              mentionedUserIds,
+            }
+          );
+        } catch (error) {
+          logger.error("Failed to broadcast suggestion status via Pusher", {
+            error,
+            messageId,
+          });
+        }
+      }
+      return { success: true };
+    }
+
+    lastError = new Error("Concurrent update conflict");
+  }
+
+  logger.error("markSuggestionCreated failed after retries", {
+    messageId,
+    type,
+    index,
+    error: lastError,
+  });
+  throw new TRPCError({
+    code: "CONFLICT",
+    message: "Failed to update suggestion status after retries due to concurrent updates",
+  });
+}
+
 export async function markAsRead(userId: string, conversationId: string) {
   const membership = await findConversationMembership(conversationId, userId);
   if (!membership) {