@studious-lms/server 1.25.0 → 1.27.0

package/src/services/aiProposalTools.ts

@@ -22,6 +22,9 @@ import type {
   WorksheetToCreate,
   SectionToCreate,
   DocToCreate,
+  AssignmentUpdate,
+  WorksheetUpdate,
+  SectionUpdate,
 } from '../pipelines/aiLabChatContract.js';
 
 export interface LabProposals {
@@ -29,10 +32,21 @@ export interface LabProposals {
   worksheets: WorksheetToCreate[];
   sections: SectionToCreate[];
   docs: DocToCreate[];
+  assignmentUpdates: AssignmentUpdate[];
+  worksheetUpdates: WorksheetUpdate[];
+  sectionUpdates: SectionUpdate[];
 }
 
 export function createLabProposals(): LabProposals {
-  return { assignments: [], worksheets: [], sections: [], docs: [] };
+  return {
+    assignments: [],
+    worksheets: [],
+    sections: [],
+    docs: [],
+    assignmentUpdates: [],
+    worksheetUpdates: [],
+    sectionUpdates: [],
+  };
 }
 
 function normalizeDueDate(input?: string | null): string {
@@ -82,6 +96,34 @@ interface ProposeAssignmentArgs {
   acceptWorksheet?: boolean;
 }
 
+interface ProposeUpdateAssignmentArgs {
+  id: string;
+  targetTitle: string;
+  title?: string;
+  instructions?: string;
+  dueDate?: string;
+  type?: AssignmentType;
+  maxGrade?: number;
+  acceptFiles?: boolean;
+  acceptExtendedResponse?: boolean;
+  acceptWorksheet?: boolean;
+  sectionId?: string | null;
+}
+
+interface ProposeUpdateWorksheetArgs {
+  id: string;
+  targetTitle: string;
+  name?: string;
+  addQuestions?: ProposeWorksheetArgs['questions'];
+}
+
+interface ProposeUpdateSectionArgs {
+  id: string;
+  targetTitle: string;
+  name: string;
+  color?: string | null;
+}
+
 interface GenerateDocumentArgs {
   title: string;
   content: string;
@@ -235,6 +277,129 @@ export function labProposalTools(proposals: LabProposals): ToolSet {
       },
     },
 
+    propose_update_assignment: {
+      description:
+        'Propose changes to an EXISTING assignment. Only pass the fields that should change; use the assignment id from CLASS CONTEXT.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Database id of the existing assignment' },
+          targetTitle: { type: 'string', description: "The assignment's current title (shown on the approval card)" },
+          title: { type: 'string', description: 'New title, if renaming' },
+          instructions: { type: 'string' },
+          dueDate: { type: 'string', description: 'ISO 8601 datetime' },
+          type: { type: 'string', enum: ASSIGNMENT_TYPES as unknown as string[] },
+          maxGrade: { type: 'number' },
+          acceptFiles: { type: 'boolean' },
+          acceptExtendedResponse: { type: 'boolean' },
+          acceptWorksheet: { type: 'boolean' },
+          sectionId: { type: 'string', description: 'Move to this section (id from CLASS CONTEXT)' },
+        },
+        required: ['id', 'targetTitle'],
+      }),
+      execute: async (args: ProposeUpdateAssignmentArgs) => {
+        proposals.assignmentUpdates.push({
+          ...args,
+          dueDate: args.dueDate ? normalizeDueDate(args.dueDate) : undefined,
+        });
+        return `Update to assignment "${args.targetTitle}" proposed.`;
+      },
+    },
+
+    propose_update_worksheet: {
+      description:
+        'Propose changes to an EXISTING worksheet: rename it and/or append new questions. Use the worksheet id from CLASS CONTEXT.',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Database id of the existing worksheet' },
+          targetTitle: { type: 'string', description: "The worksheet's current name (shown on the approval card)" },
+          name: { type: 'string', description: 'New name, if renaming' },
+          addQuestions: {
+            type: 'array',
+            description: 'New questions to append to the worksheet',
+            items: {
+              type: 'object',
+              properties: {
+                type: { type: 'string', enum: QUESTION_TYPES as unknown as string[] },
+                question: { type: 'string' },
+                answer: { type: 'string' },
+                options: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      text: { type: 'string' },
+                      isCorrect: { type: 'boolean' },
+                    },
+                    required: ['text', 'isCorrect'],
+                  },
+                },
+                markScheme: {
+                  type: 'array',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      points: { type: 'number' },
+                      description: { type: 'string' },
+                    },
+                    required: ['points', 'description'],
+                  },
+                },
+                points: { type: 'number' },
+              },
+              required: ['type', 'question'],
+            },
+          },
+        },
+        required: ['id', 'targetTitle'],
+      }),
+      execute: async ({ id, targetTitle, name, addQuestions }: ProposeUpdateWorksheetArgs) => {
+        proposals.worksheetUpdates.push({
+          id,
+          targetTitle,
+          name,
+          addQuestions: (addQuestions ?? []).map((q, index) => ({
+            type: q.type,
+            question: q.question,
+            answer: q.answer ?? '',
+            options: (q.options ?? []).map((o) => ({
+              id: v4(),
+              text: o.text,
+              isCorrect: o.isCorrect,
+            })),
+            markScheme: (q.markScheme ?? []).map((m) => ({
+              id: v4(),
+              points: m.points,
+              description: m.description,
+            })),
+            points: q.points ?? 0,
+            order: index,
+          })),
+        });
+        return `Update to worksheet "${targetTitle}" proposed.`;
+      },
+    },
+
+    propose_update_section: {
+      description:
+        'Propose changes to an EXISTING section (rename and/or recolor). Use the section id from CLASS CONTEXT. Always pass name (the resulting name, even if unchanged).',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Database id of the existing section' },
+          targetTitle: { type: 'string', description: "The section's current name (shown on the approval card)" },
+          name: { type: 'string', description: 'Resulting section name (pass the current name if only changing color)' },
+          color: { type: 'string', description: 'Optional hex color like #3b82f6' },
+        },
+        required: ['id', 'targetTitle', 'name'],
+      }),
+      execute: async ({ id, targetTitle, name, color }: ProposeUpdateSectionArgs) => {
+        proposals.sectionUpdates.push({ id, targetTitle, name, color: color ?? null });
+        return `Update to section "${targetTitle}" proposed.`;
+      },
+    },
+
     generate_document: {
       description:
         'Generate a downloadable file and attach it to this message. Pick the best format for the request — pptx for slides, xlsx/csv for data, docx for editable handouts, pdf for print-ready docs, png/jpeg for charts/diagrams/figures (NOT pdf for visuals). Use py/js/ts only when the teacher explicitly wants source code. Always set format explicitly.',

package/src/services/aiProposals.ts

@@ -0,0 +1,428 @@
+/**
+ * AI creation proposals – defer-and-confirm flow for Lab chat.
+ *
+ * The lab pipeline records every `propose_*` tool call as a pending creation
+ * on the AI message's meta (`meta.pendingCreations`). Nothing is created at
+ * generation time: the teacher approves or dismisses each proposal from the
+ * chat, and approval creates the real entity server-side.
+ */
+import { TRPCError } from "@trpc/server";
+import { v4 } from "uuid";
+import { prisma } from "../lib/prisma.js";
+import { chatChannel, pusher } from "../lib/pusher.js";
+import { logger } from "../utils/logger.js";
+import {
+  findConversationMembership,
+  findMessageByIdMinimal,
+  messageFileSelect,
+} from "../models/message.js";
+import { createAssignmentRecord, updateAssignmentRecord } from "./assignment.js";
+import {
+  createWorksheetRecord,
+  addQuestionToWorksheet,
+  updateWorksheetRecord,
+} from "./worksheet.js";
+import { createSectionRecord, updateSectionRecord } from "./section.js";
+import type { StreamPart } from "./aiChatStream.js";
+import type { LabProposals } from "./aiProposalTools.js";
+import type {
+  AssignmentToCreate,
+  WorksheetToCreate,
+  SectionToCreate,
+  AssignmentUpdate,
+  WorksheetUpdate,
+  SectionUpdate,
+} from "../pipelines/aiLabChatContract.js";
+
+export type PendingCreationStatus = "pending" | "approved" | "dismissed";
+
+export type PendingCreation =
+  | { id: string; kind: "assignment"; title: string; payload: AssignmentToCreate; status: PendingCreationStatus; createdId?: string }
+  | { id: string; kind: "worksheet"; title: string; payload: WorksheetToCreate; status: PendingCreationStatus; createdId?: string }
+  | { id: string; kind: "section"; title: string; payload: SectionToCreate; status: PendingCreationStatus; createdId?: string }
+  | { id: string; kind: "assignmentUpdate"; title: string; payload: AssignmentUpdate; status: PendingCreationStatus; createdId?: string }
+  | { id: string; kind: "worksheetUpdate"; title: string; payload: WorksheetUpdate; status: PendingCreationStatus; createdId?: string }
+  | { id: string; kind: "sectionUpdate"; title: string; payload: SectionUpdate; status: PendingCreationStatus; createdId?: string };
+
+const PROPOSAL_TOOL_KIND: Record<string, PendingCreation["kind"]> = {
+  propose_assignment: "assignment",
+  propose_worksheet: "worksheet",
+  propose_section: "section",
+  propose_update_assignment: "assignmentUpdate",
+  propose_update_worksheet: "worksheetUpdate",
+  propose_update_section: "sectionUpdate",
+};
+
+/**
+ * Turn the stream's accumulated proposals into pending creations and stamp
+ * each `propose_*` tool part with its proposal id so the client can render
+ * the confirmation card inline at the tool-call position.
+ */
+export function buildPendingCreations(
+  proposals: LabProposals,
+  parts: StreamPart[],
+): { pendingCreations: PendingCreation[]; parts: StreamPart[] } {
+  const pendingCreations: PendingCreation[] = [
+    ...proposals.assignments.map((payload): PendingCreation => ({
+      id: v4(), kind: "assignment", title: payload.title, payload, status: "pending",
+    })),
+    ...proposals.worksheets.map((payload): PendingCreation => ({
+      id: v4(), kind: "worksheet", title: payload.title, payload, status: "pending",
+    })),
+    ...proposals.sections.map((payload): PendingCreation => ({
+      id: v4(), kind: "section", title: payload.name, payload, status: "pending",
+    })),
+    ...proposals.assignmentUpdates.map((payload): PendingCreation => ({
+      id: v4(), kind: "assignmentUpdate", title: payload.targetTitle, payload, status: "pending",
+    })),
+    ...proposals.worksheetUpdates.map((payload): PendingCreation => ({
+      id: v4(), kind: "worksheetUpdate", title: payload.targetTitle, payload, status: "pending",
+    })),
+    ...proposals.sectionUpdates.map((payload): PendingCreation => ({
+      id: v4(), kind: "sectionUpdate", title: payload.targetTitle, payload, status: "pending",
+    })),
+  ];
+
+  const remaining = new Map<PendingCreation["kind"], PendingCreation[]>();
+  for (const creation of pendingCreations) {
+    const list = remaining.get(creation.kind) ?? [];
+    list.push(creation);
+    remaining.set(creation.kind, list);
+  }
+
+  const stamped = parts.map((part) => {
+    if (part.type !== "tool") return part;
+    const kind = PROPOSAL_TOOL_KIND[part.toolName];
+    if (!kind) return part;
+    const list = remaining.get(kind);
+    if (!list || list.length === 0) return part;
+    // Prefer a title match; fall back to stream order.
+    const idx = part.title
+      ? list.findIndex((c) => c.title.trim().toLowerCase() === part.title!.trim().toLowerCase())
+      : 0;
+    const creation = list.splice(idx >= 0 ? idx : 0, 1)[0];
+    return { ...part, proposalId: creation.id };
+  });
+
+  return { pendingCreations, parts: stamped };
+}
+
+const RESOLVE_MAX_RETRIES = 5;
+
+/**
+ * Compare-and-swap a proposal's status inside message meta. Returns the new
+ * meta on success, or null when the proposal was not in `fromStatus`.
+ */
+async function casProposalStatus(
+  messageId: string,
+  proposalId: string,
+  fromStatus: PendingCreationStatus,
+  patch: Partial<Pick<PendingCreation, "status" | "createdId">>,
+): Promise<Record<string, unknown> | null> {
+  for (let attempt = 0; attempt < RESOLVE_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 creations = Array.isArray(currentMeta.pendingCreations)
+      ? (currentMeta.pendingCreations as PendingCreation[])
+      : [];
+    const target = creations.find((c) => c.id === proposalId);
+    if (!target) {
+      throw new TRPCError({ code: "NOT_FOUND", message: "Proposal not found" });
+    }
+    if (target.status !== fromStatus) return null;
+
+    const newMeta = {
+      ...currentMeta,
+      pendingCreations: creations.map((c) =>
+        c.id === proposalId ? { ...c, ...patch } : c,
+      ),
+    };
+
+    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) return newMeta;
+  }
+
+  throw new TRPCError({
+    code: "CONFLICT",
+    message: "Failed to update proposal after retries due to concurrent updates",
+  });
+}
+
+async function broadcastMessageMeta(messageId: string, conversationId: string) {
+  const updated = await prisma.message.findUnique({
+    where: { id: messageId },
+    include: {
+      sender: {
+        select: {
+          id: true,
+          username: true,
+          profile: { select: { displayName: true, profilePicture: true } },
+        },
+      },
+      attachments: { select: messageFileSelect },
+      mentions: { select: { userId: true } },
+    },
+  });
+  if (!updated) return;
+
+  try {
+    await pusher.trigger(chatChannel(conversationId), "message-updated", {
+      id: updated.id,
+      content: updated.content,
+      senderId: updated.senderId,
+      conversationId: updated.conversationId,
+      status: updated.status,
+      createdAt: updated.createdAt,
+      sender: updated.sender,
+      attachments: updated.attachments ?? [],
+      meta: updated.meta,
+      mentionedUserIds: updated.mentions.map((m) => m.userId),
+    });
+  } catch (error) {
+    logger.error("Failed to broadcast proposal resolution via Pusher", {
+      error,
+      messageId,
+    });
+  }
+}
+
+/** Create or update the proposed entity; returns the affected entity's id. */
+async function createProposedEntity(
+  userId: string,
+  classId: string,
+  proposal: PendingCreation,
+): Promise<string> {
+  switch (proposal.kind) {
+    case "sectionUpdate": {
+      const payload = proposal.payload;
+      await updateSectionRecord(userId, {
+        id: payload.id,
+        classId,
+        name: payload.name,
+        color: payload.color ?? undefined,
+      });
+      return payload.id;
+    }
+    case "worksheetUpdate": {
+      const payload = proposal.payload;
+      if (payload.name) {
+        await updateWorksheetRecord(payload.id, userId, { name: payload.name });
+      }
+      for (const question of payload.addQuestions ?? []) {
+        await addQuestionToWorksheet(payload.id, userId, {
+          question: question.question,
+          answer: question.answer,
+          points: question.points,
+          options: question.options,
+          markScheme: question.markScheme,
+          type: question.type,
+          order: question.order,
+        });
+      }
+      return payload.id;
+    }
+    case "assignmentUpdate": {
+      const payload = proposal.payload;
+      await updateAssignmentRecord(userId, {
+        id: payload.id,
+        classId,
+        title: payload.title,
+        instructions: payload.instructions,
+        dueDate: payload.dueDate,
+        type: payload.type,
+        maxGrade: payload.maxGrade,
+        acceptFiles: payload.acceptFiles,
+        acceptExtendedResponse: payload.acceptExtendedResponse,
+        acceptWorksheet: payload.acceptWorksheet,
+        sectionId: payload.sectionId,
+      });
+      return payload.id;
+    }
+    case "section": {
+      const section = await createSectionRecord(userId, {
+        classId,
+        name: proposal.payload.name,
+        color: proposal.payload.color ?? undefined,
+      });
+      return section.id;
+    }
+    case "worksheet": {
+      const worksheet = await createWorksheetRecord(classId, proposal.payload.title);
+      for (const question of proposal.payload.questions) {
+        await addQuestionToWorksheet(worksheet.id, userId, {
+          question: question.question,
+          answer: question.answer,
+          points: question.points,
+          options: question.options,
+          markScheme: question.markScheme,
+          type: question.type,
+          order: question.order,
+        });
+      }
+      return worksheet.id;
+    }
+    case "assignment": {
+      const payload = proposal.payload;
+      const assignment = await createAssignmentRecord(userId, {
+        classId,
+        title: payload.title,
+        instructions: payload.instructions,
+        dueDate: payload.dueDate,
+        type: payload.type,
+        maxGrade: payload.maxGrade,
+        acceptFiles: payload.acceptFiles,
+        acceptExtendedResponse: payload.acceptExtendedResponse,
+        acceptWorksheet: payload.acceptWorksheet,
+        gradingBoundaryId: payload.gradingBoundaryId ?? undefined,
+        markSchemeId: payload.markSchemeId ?? undefined,
+        worksheetIds: payload.worksheetIds,
+        studentIds: payload.studentIds,
+        sectionId: payload.sectionId ?? undefined,
+        existingFileIds: payload.attachments.map((a) => a.id),
+      });
+      return assignment.id;
+    }
+  }
+}
+
+/**
+ * Approve or dismiss a pending AI creation proposal. Approval creates the
+ * entity server-side; both outcomes persist to message meta and broadcast a
+ * `message-updated` event so every client (and reloads) see the final state.
+ */
+export async function resolveAiProposal(
+  userId: string,
+  input: { messageId: string; proposalId: string; action: "approve" | "dismiss" },
+) {
+  const { messageId, proposalId, action } = input;
+
+  const message = await findMessageByIdMinimal(messageId);
+  if (!message) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Message not found" });
+  }
+
+  const membership = await findConversationMembership(
+    message.conversationId,
+    userId,
+  );
+  if (!membership) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Not a member of this conversation",
+    });
+  }
+
+  const labChat = await prisma.labChat.findFirst({
+    where: { conversationId: message.conversationId },
+    select: { classId: true },
+  });
+  if (!labChat) {
+    throw new TRPCError({
+      code: "BAD_REQUEST",
+      message: "Proposals can only be resolved in lab chats",
+    });
+  }
+
+  const teaches = await prisma.class.findFirst({
+    where: { id: labChat.classId, teachers: { some: { id: userId } } },
+    select: { id: true },
+  });
+  if (!teaches) {
+    throw new TRPCError({
+      code: "FORBIDDEN",
+      message: "Only class teachers can resolve proposals",
+    });
+  }
+
+  const currentMeta = await prisma.message.findUnique({
+    where: { id: messageId },
+    select: { meta: true },
+  });
+  const creations = Array.isArray(
+    (currentMeta?.meta as Record<string, unknown> | null)?.pendingCreations,
+  )
+    ? ((currentMeta!.meta as Record<string, unknown>)
+        .pendingCreations as PendingCreation[])
+    : [];
+  const proposal = creations.find((c) => c.id === proposalId);
+  if (!proposal) {
+    throw new TRPCError({ code: "NOT_FOUND", message: "Proposal not found" });
+  }
+  if (proposal.status !== "pending") {
+    return {
+      status: proposal.status,
+      createdId: proposal.createdId ?? null,
+    };
+  }
+
+  if (action === "dismiss") {
+    const meta = await casProposalStatus(messageId, proposalId, "pending", {
+      status: "dismissed",
+    });
+    if (meta) {
+      await broadcastMessageMeta(messageId, message.conversationId);
+    }
+    return { status: "dismissed" as const, createdId: null };
+  }
+
+  // Approve: claim the proposal first so concurrent approvals create at most
+  // one entity, then create and record the created id (roll back on failure).
+  const claimed = await casProposalStatus(messageId, proposalId, "pending", {
+    status: "approved",
+  });
+  if (!claimed) {
+    const msg = await prisma.message.findUnique({
+      where: { id: messageId },
+      select: { meta: true },
+    });
+    const latest = (
+      ((msg?.meta as Record<string, unknown> | null)?.pendingCreations ??
+        []) as PendingCreation[]
+    ).find((c) => c.id === proposalId);
+    return {
+      status: latest?.status ?? "pending",
+      createdId: latest?.createdId ?? null,
+    };
+  }
+
+  try {
+    const createdId = await createProposedEntity(userId, labChat.classId, proposal);
+    await casProposalStatus(messageId, proposalId, "approved", { createdId });
+    await broadcastMessageMeta(messageId, message.conversationId);
+    return { status: "approved" as const, createdId };
+  } catch (error) {
+    logger.error("Failed to create approved AI proposal", {
+      error,
+      messageId,
+      proposalId,
+      kind: proposal.kind,
+    });
+    await casProposalStatus(messageId, proposalId, "approved", {
+      status: "pending",
+    }).catch(() => null);
+    await broadcastMessageMeta(messageId, message.conversationId);
+    throw new TRPCError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Failed to create the approved item",
+    });
+  }
+}

package/src/services/assignment.ts

@@ -28,6 +28,7 @@ import { enqueueRunJob } from "../workers/queues.js";
 import { logger } from "../utils/logger.js";
 import { invalidateStudentProgressInferenceCache } from "./studentProgressInferenceCache.js";
 import { enqueueEmbedding } from "./embedding.js";
+import { syncAssignmentModuleProgress } from "./module.js";
 import { resolveAssignmentBehavior } from "../lib/assignmentTypeDefaults.js";
 
 export async function assignmentExists(id: string) {
@@ -803,7 +804,7 @@ export async function updateSubmissionRecord(
         }
       }
     }
-    return prisma.submission.update({
+    const updatedSubmission = await prisma.submission.update({
       where: { id: submission.id },
       data: {
         submitted: !submission.submitted,
@@ -821,6 +822,8 @@ export async function updateSubmissionRecord(
         },
       },
     });
+    await syncAssignmentModuleProgress(userId, submission.assignmentId);
+    return updatedSubmission;
   }
 
   const isLateUpdate = submission.assignment.dueDate < new Date();
@@ -1002,6 +1005,10 @@ export async function updateSubmissionAsTeacherRecord(
       data: { returned: !submission.returned },
       include: submissionTeacherInclude,
     });
+    await syncAssignmentModuleProgress(
+      submission.studentId,
+      submission.assignmentId
+    );
 
     if (updated.returned) {
       sendNotification({
@@ -1072,6 +1079,10 @@ export async function updateSubmissionAsTeacherRecord(
       submission.assignment.classId,
       submission.studentId,
     );
+    await syncAssignmentModuleProgress(
+      submission.studentId,
+      submission.assignmentId
+    );
   }
 
   // Index submission for RAG search after teacher grades/feedback