@studious-lms/server 1.13.0 → 1.14.0

package/src/services/user.ts

@@ -5,15 +5,7 @@ import { TRPCError } from "@trpc/server";
 import { logger } from "../utils/logger.js";
 import { env } from "../lib/config/env.js";
 import { findUserById, findUserProfileByUserId, upsertUserProfile } from "../models/user.js";
-
-function getFileUrl(filePath: string | null): string | null {
-  if (!filePath) return null;
-  if (filePath.startsWith("http")) {
-    return filePath;
-  }
-  const backendUrl = env.BACKEND_URL || "http://localhost:3001";
-  return `${backendUrl}/api/files/${encodeURIComponent(filePath)}`;
-}
+import { makeFilePublic } from "../lib/googleCloudStorage.js";
 
 /** Get user profile with display info and profile picture URLs. */
 export async function getProfile(userId: string) {
@@ -36,10 +28,8 @@ export async function getProfile(userId: string) {
           bio: (userProfile as any).bio || null,
           location: (userProfile as any).location || null,
           website: (userProfile as any).website || null,
-          profilePicture: getFileUrl((userProfile as any).profilePicture),
-          profilePictureThumbnail: getFileUrl(
-            (userProfile as any).profilePictureThumbnail
-          ),
+          profilePicture: (userProfile as any).profilePicture ?? null,
+          profilePictureThumbnail: (userProfile as any).profilePictureThumbnail ?? null,
         }
       : {
           displayName: null,
@@ -78,6 +68,10 @@ export async function updateProfile(
     try {
       profilePictureUrl = input.profilePicture.filePath;
       profilePictureThumbnail = null;
+
+      // Best-effort: make the uploaded file publicly readable so the public
+      // GCS URL resolved by the Prisma extension actually works.
+      await makeFilePublic(profilePictureUrl);
     } catch (error) {
       logger.error("Profile picture processing failed", {
         userId,
@@ -125,10 +119,8 @@ export async function updateProfile(
       bio: (updatedProfile as any).bio || null,
       location: (updatedProfile as any).location || null,
       website: (updatedProfile as any).website || null,
-      profilePicture: getFileUrl((updatedProfile as any).profilePicture),
-      profilePictureThumbnail: getFileUrl(
-        (updatedProfile as any).profilePictureThumbnail
-      ),
+      profilePicture: (updatedProfile as any).profilePicture ?? null,
+      profilePictureThumbnail: (updatedProfile as any).profilePictureThumbnail ?? null,
     },
   };
 }

package/src/services/worksheet.ts

@@ -38,6 +38,7 @@ import {
   findStudentQuestionProgressByIdForStudentOrTeacher,
   findStudentQuestionProgressByIdForTeacherAndResponse,
 } from "../models/worksheet.js";
+import { enqueueEmbedding } from "./embedding.js";
 
 type MCQOptions = { id: string; text: string; isCorrect: boolean }[];
 
@@ -108,7 +109,10 @@ export async function updateWorksheetRecord(
       message: "Only class teachers can update worksheets",
     });
   }
-  return updateWorksheet(worksheetId, data);
+  const updated = await updateWorksheet(worksheetId, data);
+  // Re-index worksheet for RAG search
+  enqueueEmbedding(worksheet.classId, 'WORKSHEET', worksheetId);
+  return updated;
 }
 
 export async function deleteWorksheetRecord(worksheetId: string, userId: string) {
@@ -123,7 +127,10 @@ export async function deleteWorksheetRecord(worksheetId: string, userId: string)
 }
 
 export async function createWorksheetRecord(classId: string, name: string) {
-  return createWorksheet({ classId, name });
+  const worksheet = await createWorksheet({ classId, name });
+  // Auto-index worksheet for RAG search
+  enqueueEmbedding(classId, 'WORKSHEET', worksheet.id);
+  return worksheet;
 }
 
 /**

package/src/utils/streamBroadcast.ts

@@ -0,0 +1,48 @@
+/**
+ * Broadcast text content as sequential Pusher chunks so connected clients
+ * can render progressive streaming even when the underlying inference call
+ * returns the full text at once (structured-output pipelines).
+ */
+import { pusher, chatChannel } from '../lib/pusher.js';
+
+const CHUNK_SIZE = 80;
+
+interface BroadcastTextChunksOptions {
+  /** When true, skip the `message-stream-complete` event at the end.
+   *  Callers that need to broadcast additional events (e.g. tool-call
+   *  indicators) before the stream ends should set this to `true` and
+   *  call {@link broadcastStreamComplete} explicitly when done. */
+  skipComplete?: boolean;
+}
+
+export async function broadcastTextChunks(
+  conversationId: string,
+  messageId: string,
+  text: string,
+  options?: BroadcastTextChunksOptions,
+): Promise<void> {
+  for (let i = 0; i < text.length; i += CHUNK_SIZE) {
+    const chunk = text.slice(i, i + CHUNK_SIZE);
+    await pusher
+      .trigger(chatChannel(conversationId), 'message-stream-chunk', {
+        messageId,
+        chunk,
+      })
+      .catch(() => {});
+  }
+
+  if (!options?.skipComplete) {
+    await broadcastStreamComplete(conversationId, messageId);
+  }
+}
+
+export async function broadcastStreamComplete(
+  conversationId: string,
+  messageId: string,
+): Promise<void> {
+  await pusher
+    .trigger(chatChannel(conversationId), 'message-stream-complete', {
+      messageId,
+    })
+    .catch(() => {});
+}

package/src/workers/connection.ts

@@ -35,3 +35,22 @@ function buildBullConnection(): IORedis {
 }
 
 export const bullConnection = buildBullConnection();
+
+/**
+ * Key prefix applied to every BullMQ Queue and Worker.
+ *
+ * Without this, BullMQ defaults to the `bull` namespace, so ANY process
+ * pointed at the same Redis instance shares the same queues. That is a
+ * problem when a single Redis (e.g. a shared Upstash instance) is used across
+ * environments while each environment has its own database: a worker can pick
+ * up a job enqueued elsewhere, fail to find its `RunJob` row, and crash-loop
+ * with "No record was found for an update".
+ *
+ * Namespacing by environment keeps each environment's jobs isolated. Override
+ * with `BULL_PREFIX` when you need finer-grained separation (e.g. per
+ * developer sharing one Redis).
+ */
+export function getBullPrefix(): string {
+  const explicit = env.BULL_PREFIX?.trim();
+  return explicit && explicit.length > 0 ? explicit : `bull:${env.NODE_ENV}`;
+}

package/src/workers/index.ts

@@ -17,6 +17,7 @@ import { aiNewtonChatWorker } from './processors/aiNewtonChat.js';
 import { gradeWorksheetWorker } from './processors/gradeWorksheet.js';
 import { pdfToWorksheetWorker } from './processors/pdfToWorksheet.js';
 import { studentProgressChatWorker } from './processors/studentProgressChat.js';
+import { embedContentWorker } from './processors/embedContent.js';
 
 const workers: Worker<any>[] = [
   pdfToWorksheetWorker,
@@ -24,6 +25,7 @@ const workers: Worker<any>[] = [
   aiLabChatWorker,
   aiNewtonChatWorker,
   studentProgressChatWorker,
+  embedContentWorker,
 ];
 
 logger.info('Workers ready', {

package/src/workers/processors/createRunJobWorker.ts

@@ -17,7 +17,7 @@
  */
 import { Worker, type Job, type WorkerOptions } from 'bullmq';
 import { Prisma, type RunJobType } from '@prisma/client';
-import { bullConnection } from '../connection.js';
+import { bullConnection, getBullPrefix } from '../connection.js';
 import { prisma } from '../../lib/prisma.js';
 import { logger } from '../../utils/logger.js';
 import { QUEUE_NAMES, type JobInputs } from '../queues.js';
@@ -69,7 +69,21 @@ export function createRunJobWorker<T extends RunJobType>({
         select: { status: true, result: true, userId: true, classId: true },
       });
 
-      if (existing?.status === 'SUCCEEDED') {
+      if (!existing) {
+        // Orphaned job: the RunJob row this job points at does not exist in
+        // THIS database. Typically caused by a Redis instance shared across
+        // environments/databases (the `prefix` namespacing in this file's
+        // Worker options is the primary guard against that), or by a DB reset
+        // that left jobs behind in Redis. Discard instead of throwing on the
+        // `update` below and burning all retry attempts.
+        logger.warn(`${name} RunJob not found; discarding orphaned job`, {
+          runJobId,
+          bullJobId: job.id,
+        });
+        return null;
+      }
+
+      if (existing.status === 'SUCCEEDED') {
         logger.info(`${name} RunJob already succeeded; skipping re-run`, {
           runJobId,
           bullJobId: job.id,
@@ -81,7 +95,7 @@ export function createRunJobWorker<T extends RunJobType>({
         where: { id: runJobId },
         data: {
           status: 'RUNNING',
-          startedAt: existing?.status === 'RUNNING' ? undefined : new Date(),
+          startedAt: existing.status === 'RUNNING' ? undefined : new Date(),
           attempts: { increment: 1 },
         },
       });
@@ -90,8 +104,8 @@ export function createRunJobWorker<T extends RunJobType>({
         runJobId,
         bullJobId: job.id,
         attempt: job.attemptsMade + 1,
-        userId: existing?.userId ?? null,
-        classId: existing?.classId ?? null,
+        userId: existing.userId ?? null,
+        classId: existing.classId ?? null,
       });
 
       await prisma.runJob.update({
@@ -106,7 +120,7 @@ export function createRunJobWorker<T extends RunJobType>({
 
       return result;
     },
-    { connection: bullConnection, ...workerOptions },
+    { connection: bullConnection, prefix: getBullPrefix(), ...workerOptions },
   );
 
   worker.on('error', (err) => {
@@ -143,6 +157,18 @@ export function createRunJobWorker<T extends RunJobType>({
         },
       })
       .catch((updateError) => {
+        // P2025 = record not found. The RunJob row is gone (orphaned job from a
+        // shared/reset Redis), so there's nothing to flag as FAILED — log
+        // quietly instead of as an error to avoid noise.
+        if (
+          updateError instanceof Prisma.PrismaClientKnownRequestError &&
+          updateError.code === 'P2025'
+        ) {
+          logger.warn(`${name} failure not recorded; RunJob no longer exists`, {
+            runJobId,
+          });
+          return;
+        }
         logger.error(`Failed to record ${name} failure on RunJob`, {
           runJobId,
           error:

package/src/workers/processors/embedContent.ts

@@ -0,0 +1,90 @@
+/**
+ * Background worker for embedding content into pgvector.
+ * Handles indexing of files, assignments, worksheets, and announcements.
+ */
+import { createRunJobWorker } from './createRunJobWorker.js';
+import {
+  indexAssignment,
+  indexWorksheet,
+  indexAnnouncement,
+  indexContent,
+} from '../../services/embedding.js';
+import { prisma } from '../../lib/prisma.js';
+import { logger } from '../../utils/logger.js';
+import type { EmbeddingSourceType } from '@prisma/client';
+
+export const embedContentWorker = createRunJobWorker({
+  type: 'EMBED_CONTENT',
+  workerOptions: {
+    concurrency: 3,
+    limiter: { max: 10, duration: 60_000 },
+  },
+  run: async ({ classId, sourceType, sourceId }) => {
+    const typedSourceType = sourceType as EmbeddingSourceType;
+
+    switch (typedSourceType) {
+      case 'ASSIGNMENT':
+        await indexAssignment(classId, sourceId);
+        break;
+
+      case 'WORKSHEET':
+        await indexWorksheet(classId, sourceId);
+        break;
+
+      case 'ANNOUNCEMENT':
+        await indexAnnouncement(classId, sourceId);
+        break;
+
+      case 'FILE': {
+        // For files, fetch the file metadata and content
+        const file = await prisma.file.findUnique({
+          where: { id: sourceId },
+          select: { name: true, path: true, type: true },
+        });
+
+        if (!file) {
+          logger.warn('File not found for embedding', { sourceId });
+          return { skipped: true, reason: 'file_not_found' };
+        }
+
+        // For now, index the filename and any text-based content.
+        // PDF extraction would be added here with pdf-parse.
+        const text = `File: ${file.name}\nType: ${file.type}\nPath: ${file.path}`;
+        await indexContent({
+          classId,
+          sourceType: 'FILE',
+          sourceId,
+          text,
+          metadata: { name: file.name, type: file.type },
+        });
+        break;
+      }
+
+      case 'SECTION': {
+        const section = await prisma.section.findUnique({
+          where: { id: sourceId },
+          select: { name: true },
+        });
+
+        if (!section) {
+          return { skipped: true, reason: 'section_not_found' };
+        }
+
+        await indexContent({
+          classId,
+          sourceType: 'SECTION',
+          sourceId,
+          text: `Section: ${section.name}`,
+          metadata: { name: section.name },
+        });
+        break;
+      }
+
+      default:
+        logger.warn('Unknown embedding source type', { sourceType, sourceId });
+        return { skipped: true, reason: 'unknown_source_type' };
+    }
+
+    return { indexed: true, sourceType, sourceId };
+  },
+});

package/src/workers/queues.ts

@@ -8,7 +8,7 @@
  */
 import { Queue, type JobsOptions } from 'bullmq';
 import { Prisma, type RunJobType } from '@prisma/client';
-import { bullConnection } from './connection.js';
+import { bullConnection, getBullPrefix } from './connection.js';
 import { prisma } from '../lib/prisma.js';
 import { logger } from '../utils/logger.js';
 
@@ -47,6 +47,8 @@ export type JobInputs = {
    */
   AI_NEWTON_CHAT: { conversationId: string; aiMessageId: string };
   STUDENT_PROGRESS_CHAT: { classId: string; studentId: string; message: string };
+  /** Embed content into pgvector for RAG search. */
+  EMBED_CONTENT: { classId: string; sourceType: string; sourceId: string };
 };
 
 export const QUEUE_NAMES: Record<RunJobType, string> = {
@@ -55,6 +57,7 @@ export const QUEUE_NAMES: Record<RunJobType, string> = {
   AI_LAB_CHAT: 'aiLabChat',
   AI_NEWTON_CHAT: 'aiNewtonChat',
   STUDENT_PROGRESS_CHAT: 'studentProgressChat',
+  EMBED_CONTENT: 'embedContent',
 };
 
 /**
@@ -68,6 +71,7 @@ function getQueue(type: RunJobType): Queue {
   if (!queue) {
     queue = new Queue(QUEUE_NAMES[type], {
       connection: bullConnection,
+      prefix: getBullPrefix(),
       defaultJobOptions: DEFAULT_JOB_OPTIONS,
     });
     queueCache.set(type, queue);

package/tests/unit/pipelines/aiLabChatContract.test.ts

@@ -1,32 +1,49 @@
 import { describe, expect, test } from "vitest";
-import { labChatArrayFieldInstructions, labChatResponseFormat, labChatResponseSchema } from "../../../src/pipelines/aiLabChatContract.js";
+import {
+  assignmentToCreateSchema,
+  sectionToCreateSchema,
+  worksheetQuestionSchema,
+} from "../../../src/pipelines/aiLabChatContract.js";
 
 describe("aiLabChat contract", () => {
-  test("defaults worksheet and section collections to empty arrays", () => {
-    const parsed = labChatResponseSchema.parse({
-      text: "Summary",
-      docs: null,
-      assignmentsToCreate: null,
+  test("worksheet questions default options, mark scheme, and points", () => {
+    const parsed = worksheetQuestionSchema.parse({
+      type: "SHORT_ANSWER",
+      question: "What is osmosis?",
+      answer: "Diffusion of water across a membrane",
+      order: 0,
     });
 
-    expect(parsed.worksheetsToCreate).toEqual([]);
-    expect(parsed.sectionsToCreate).toEqual([]);
+    expect(parsed.options).toEqual([]);
+    expect(parsed.markScheme).toEqual([]);
+    expect(parsed.points).toBe(0);
   });
 
-  test("rejects null worksheet and section collections", () => {
-    expect(() => labChatResponseSchema.parse({
-      text: "Summary",
-      docs: null,
-      worksheetsToCreate: null,
-      sectionsToCreate: null,
-      assignmentsToCreate: null,
-    })).toThrow();
+  test("section color must be a hex value when provided", () => {
+    expect(() => sectionToCreateSchema.parse({ name: "Unit 1", color: "blue" })).toThrow();
+    expect(sectionToCreateSchema.parse({ name: "Unit 1", color: "#3B82F6" }).color).toBe(
+      "#3B82F6",
+    );
+    expect(sectionToCreateSchema.parse({ name: "Unit 1" }).color).toBeUndefined();
   });
 
-  test("prompt instructions require arrays for worksheet and section fields", () => {
-    expect(labChatResponseFormat).toContain(`"worksheetsToCreate": array`);
-    expect(labChatResponseFormat).toContain(`"sectionsToCreate": array`);
-    expect(labChatArrayFieldInstructions).toContain(`Use [] when there are no worksheets to create.`);
-    expect(labChatArrayFieldInstructions).toContain(`Use [] when there are no sections to create.`);
+  test("assignment requires an ISO datetime due date", () => {
+    const base = {
+      title: "Osmosis Quiz",
+      instructions: "Answer all questions.",
+      acceptFiles: false,
+      acceptExtendedResponse: false,
+      acceptWorksheet: true,
+      maxGrade: 10,
+      worksheetIds: [],
+      studentIds: [],
+      type: "QUIZ" as const,
+      attachments: [],
+    };
+
+    expect(() => assignmentToCreateSchema.parse({ ...base, dueDate: "not-a-date" })).toThrow();
+    expect(
+      assignmentToCreateSchema.parse({ ...base, dueDate: "2026-04-08T12:00:00Z" }).dueDate,
+    ).toBe("2026-04-08T12:00:00Z");
   });
 });

package/tests/unit/pipelines/labChatPrompt.test.ts

@@ -1,26 +1,24 @@
 import { describe, expect, test } from "vitest";
 
 import {
-  buildLabChatResponseMessages,
-  buildLabChatSystemPrompt,
+  buildLabChatAgentMessages,
+  buildLabChatAgentSystemPrompt,
 } from "../../../src/pipelines/labChatPrompt";
-import { labChatArrayFieldInstructions, labChatResponseFormat } from "../../../src/pipelines/aiLabChatContract";
 
-describe("buildLabChatSystemPrompt", () => {
-  test("requires arrays for worksheet and section structured output fields", () => {
-    const prompt = buildLabChatSystemPrompt("Context");
+describe("buildLabChatAgentSystemPrompt", () => {
+  test("instructs the model to create content via proposal tools", () => {
+    const prompt = buildLabChatAgentSystemPrompt("Context");
 
-    expect(prompt).toContain(labChatResponseFormat);
-    expect(prompt).toContain(labChatArrayFieldInstructions);
-    expect(prompt).toContain('Do not return null for "worksheetsToCreate" or "sectionsToCreate".');
-    expect(prompt).not.toContain('"worksheetsToCreate": null | array');
-    expect(prompt).not.toContain('"sectionsToCreate": null | array');
+    expect(prompt).toContain("Context");
+    expect(prompt).toContain("HOW TO CREATE CONTENT (TOOLS):");
+    expect(prompt).toContain("propose_assignment");
+    expect(prompt).toContain("propose_worksheet");
   });
 });
 
-describe("buildLabChatResponseMessages", () => {
-  test("builds response messages from history without replaying the latest teacher turn", () => {
-    const messages = buildLabChatResponseMessages({
+describe("buildLabChatAgentMessages", () => {
+  test("folds the class context into the system prompt, not the message list", () => {
+    const { system, messages } = buildLabChatAgentMessages({
       context: "Topic context",
       classContext: "CLASS: Biology",
       recentMessages: [
@@ -32,30 +30,19 @@ describe("buildLabChatResponseMessages", () => {
             profile: { displayName: "Ms Patel" },
           },
         },
-        {
-          senderId: "ai-user",
-          content: "I can do that.",
-        },
       ],
       isAIUser: (senderId) => senderId === "ai-user",
     });
 
-    const teacherTurns = messages.filter(
-      (message) =>
-        message.role === "user" &&
-        typeof message.content === "string" &&
-        message.content.includes("Create a quiz on osmosis"),
-    );
-
-    expect(teacherTurns).toHaveLength(1);
-    expect(messages.at(-2)).toMatchObject({
-      role: "developer",
-      content: expect.stringContaining("CLASS CONTEXT"),
-    });
+    expect(system).toContain("CLASS CONTEXT");
+    expect(system).toContain("CLASS: Biology");
+    expect(messages).toEqual([
+      { role: "user", content: "Ms Patel: Create a quiz on osmosis" },
+    ]);
   });
 
   test("sorts timestamped history into chronological order before prompt assembly", () => {
-    const messages = buildLabChatResponseMessages({
+    const { messages } = buildLabChatAgentMessages({
       context: "Topic context",
       classContext: "CLASS: Biology",
       recentMessages: [
@@ -79,18 +66,18 @@ describe("buildLabChatResponseMessages", () => {
       isAIUser: (senderId) => senderId === "ai-user",
     });
 
-    expect(messages[1]).toMatchObject({
+    expect(messages[0]).toMatchObject({
       role: "user",
       content: "Ms Patel: First request",
     });
-    expect(messages[2]).toMatchObject({
+    expect(messages[1]).toMatchObject({
       role: "assistant",
       content: "Second response",
     });
   });
 
   test("keeps original order among messages without timestamps", () => {
-    const messages = buildLabChatResponseMessages({
+    const { messages } = buildLabChatAgentMessages({
       context: "Topic context",
       classContext: "CLASS: Biology",
       recentMessages: [
@@ -114,11 +101,11 @@ describe("buildLabChatResponseMessages", () => {
       isAIUser: () => false,
     });
 
-    expect(messages[1]).toMatchObject({
+    expect(messages[0]).toMatchObject({
       role: "user",
       content: "Ms Patel: First untimed request",
     });
-    expect(messages[2]).toMatchObject({
+    expect(messages[1]).toMatchObject({
       role: "user",
       content: "Ms Patel: Second untimed request",
     });