@studious-lms/server 1.5.0 → 1.6.0

package/dist/workers/queues.d.ts

@@ -15,21 +15,37 @@ import { type RunJobType } from '@prisma/client';
  * The queue name string must match what the corresponding processor passes
  * to `new Worker(<name>, ...)`.
  */
-type JobInputs = {
+export type JobInputs = {
+    /**
+     * `worksheetId` is the placeholder Worksheet row created synchronously by
+     * the producer (so the client has an id to navigate to). The pipeline fills
+     * that row in asynchronously and broadcasts progress on the per-worksheet
+     * job channel.
+     */
     PDF_TO_WORKSHEET: {
         gcsUrl: string;
         classId: string;
+        worksheetId: string;
     };
     GRADE_WORKSHEET: {
         worksheetResponseId: string;
     };
+    /**
+     * `aiMessageId` is the placeholder AI Message row created synchronously by
+     * the producer before enqueue (so the client renders a PENDING bubble in
+     * the timeline). The pipeline fills in the content and flips the row to
+     * COMPLETED / FAILED. Used for both intros and replies — single shape.
+     */
     AI_LAB_CHAT: {
         conversationId: string;
-        messageId: string;
+        aiMessageId: string;
     };
+    /**
+     * `aiMessageId` placeholder pattern, same as AI_LAB_CHAT — see above.
+     */
     AI_NEWTON_CHAT: {
         conversationId: string;
-        messageId: string;
+        aiMessageId: string;
     };
     STUDENT_PROGRESS_CHAT: {
         classId: string;
@@ -37,6 +53,7 @@ type JobInputs = {
         message: string;
     };
 };
+export declare const QUEUE_NAMES: Record<RunJobType, string>;
 export interface EnqueueOptions {
     classId?: string | null;
     userId?: string | null;
@@ -65,5 +82,4 @@ export declare function enqueueRunJob<T extends RunJobType>(type: T, input: JobI
  * the producer side disconnects from Redis cleanly.
  */
 export declare function closeAllQueues(): Promise<void>;
-export {};
 //# sourceMappingURL=queues.d.ts.map

package/dist/workers/queues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queues.d.ts","sourceRoot":"/","sources":["workers/queues.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAYzD;;;;;;GAMG;AACH,KAAK,SAAS,GAAG;IACf,gBAAgB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,eAAe,EAAE;QAAE,mBAAmB,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,WAAW,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,cAAc,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,qBAAqB,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF,CAAC;AA4BF,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,UAAU,EACtD,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EACnB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA2DxB;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAGpD"}
+{"version":3,"file":"queues.d.ts","sourceRoot":"/","sources":["workers/queues.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAYzD;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;;OAKG;IACH,gBAAgB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,eAAe,EAAE;QAAE,mBAAmB,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD;;;;;OAKG;IACH,WAAW,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D;;OAEG;IACH,cAAc,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,qBAAqB,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAChF,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAMlD,CAAC;AAoBF,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qEAAqE;IACrE,UAAU,CAAC,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,UAAU,EACtD,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,EACnB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA2DxB;AAED;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAGpD"}

package/dist/workers/queues.js

@@ -7,7 +7,7 @@
  * which is the entrypoint of the separate long-running worker process.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f8634186-ae9e-551f-96ec-058802ec2c99")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="feefd10a-9381-5c30-a525-0ffe36e2e323")}catch(e){}}();
 import { Queue } from 'bullmq';
 import { bullConnection } from './connection.js';
 import { prisma } from '../lib/prisma.js';
@@ -18,7 +18,7 @@ const DEFAULT_JOB_OPTIONS = {
     removeOnComplete: { age: 60 * 60 }, // keep completed jobs in Redis for 1h, then drop
     removeOnFail: { age: 24 * 60 * 60 }, // keep failed jobs for 24h for inspection
 };
-const QUEUE_NAMES = {
+export const QUEUE_NAMES = {
     PDF_TO_WORKSHEET: 'pdfToWorksheet',
     GRADE_WORKSHEET: 'gradeWorksheet',
     AI_LAB_CHAT: 'aiLabChat',
@@ -116,4 +116,4 @@ export async function closeAllQueues() {
     queueCache.clear();
 }
 //# sourceMappingURL=queues.js.map
-//# debugId=f8634186-ae9e-551f-96ec-058802ec2c99
+//# debugId=feefd10a-9381-5c30-a525-0ffe36e2e323

package/dist/workers/queues.js.map

@@ -1 +1 @@
-{"version":3,"file":"queues.js","sources":["workers/queues.ts"],"sourceRoot":"/","sourcesContent":["/**\n * BullMQ queue producers and the `enqueueRunJob` helper.\n *\n * Producer side only — safe to import from HTTP routes / services running on\n * Vercel. Importing this file does NOT start any workers; workers live in\n * `src/workers/processors/*` and are wired up by `src/workers/index.ts`,\n * which is the entrypoint of the separate long-running worker process.\n */\nimport { Queue, type JobsOptions } from 'bullmq';\nimport { Prisma, type RunJobType } from '@prisma/client';\nimport { bullConnection } from './connection.js';\nimport { prisma } from '../lib/prisma.js';\nimport { logger } from '../utils/logger.js';\n\nconst DEFAULT_JOB_OPTIONS: JobsOptions = {\n  attempts: 3,\n  backoff: { type: 'exponential', delay: 5_000 },\n  removeOnComplete: { age: 60 * 60 }, // keep completed jobs in Redis for 1h, then drop\n  removeOnFail: { age: 24 * 60 * 60 }, // keep failed jobs for 24h for inspection\n};\n\n/**\n * Map RunJobType → (queue name, input payload shape).\n *\n * Add a new entry here whenever you introduce a new background job type.\n * The queue name string must match what the corresponding processor passes\n * to `new Worker(<name>, ...)`.\n */\ntype JobInputs = {\n  PDF_TO_WORKSHEET: { gcsUrl: string; classId: string };\n  GRADE_WORKSHEET: { worksheetResponseId: string };\n  AI_LAB_CHAT: { conversationId: string; messageId: string };\n  AI_NEWTON_CHAT: { conversationId: string; messageId: string };\n  STUDENT_PROGRESS_CHAT: { classId: string; studentId: string; message: string };\n};\n\nconst QUEUE_NAMES: Record<RunJobType, string> = {\n  PDF_TO_WORKSHEET: 'pdfToWorksheet',\n  GRADE_WORKSHEET: 'gradeWorksheet',\n  AI_LAB_CHAT: 'aiLabChat',\n  AI_NEWTON_CHAT: 'aiNewtonChat',\n  STUDENT_PROGRESS_CHAT: 'studentProgressChat',\n};\n\n/**\n * One Queue instance per type. Created lazily so that importing this module\n * does not eagerly open queues you may never use in a given runtime.\n */\nconst queueCache = new Map<RunJobType, Queue>();\n\nfunction getQueue(type: RunJobType): Queue {\n  let queue = queueCache.get(type);\n  if (!queue) {\n    queue = new Queue(QUEUE_NAMES[type], {\n      connection: bullConnection,\n      defaultJobOptions: DEFAULT_JOB_OPTIONS,\n    });\n    queueCache.set(type, queue);\n  }\n  return queue;\n}\n\nexport interface EnqueueOptions {\n  classId?: string | null;\n  userId?: string | null;\n  /** Override BullMQ job options (attempts, delay, priority, etc.). */\n  jobOptions?: JobsOptions;\n}\n\nexport interface EnqueueResult {\n  runJobId: string;\n  bullJobId: string | null;\n}\n\n/**\n * Create a `RunJob` audit row, enqueue the BullMQ job, and link the two.\n *\n * Returns immediately — the actual work happens on the worker process. The\n * caller can return `runJobId` to the client and have them poll `getRunJob`\n * (or subscribe over Pusher) to track progress.\n *\n * IMPORTANT: do not call this inside a Prisma `$transaction`. If the outer\n * transaction rolls back after the BullMQ job is added, the worker will pick\n * up an orphaned job pointing at a non-existent RunJob row. Enqueue *after*\n * the transaction commits.\n */\nexport async function enqueueRunJob<T extends RunJobType>(\n  type: T,\n  input: JobInputs[T],\n  options: EnqueueOptions = {},\n): Promise<EnqueueResult> {\n  const runJob = await prisma.runJob.create({\n    data: {\n      type,\n      status: 'PENDING',\n      classId: options.classId ?? null,\n      userId: options.userId ?? null,\n      input: input as unknown as Prisma.InputJsonValue,\n    },\n  });\n\n  try {\n    const queue = getQueue(type);\n    const job = await queue.add(\n      QUEUE_NAMES[type],\n      { runJobId: runJob.id, ...input },\n      options.jobOptions,\n    );\n\n    try {\n      await prisma.runJob.update({\n        where: { id: runJob.id },\n        data: { bullJobId: job.id ?? null },\n      });\n    } catch (linkError) {\n      logger.error('RunJob enqueued but bullJobId linkage failed', {\n        runJobId: runJob.id,\n        bullJobId: job.id ?? null,\n        type,\n        error: linkError instanceof Error ? linkError.message : String(linkError),\n      });\n    }\n\n    return { runJobId: runJob.id, bullJobId: job.id ?? null };\n  } catch (error) {\n    logger.error('Failed to enqueue RunJob; marking FAILED', {\n      runJobId: runJob.id,\n      type,\n      error: error instanceof Error ? error.message : String(error),\n    });\n\n    try {\n      await prisma.runJob.update({\n        where: { id: runJob.id },\n        data: {\n          status: 'FAILED',\n          error: error instanceof Error ? error.message : String(error),\n          finishedAt: new Date(),\n        },\n      });\n    } catch (updateError) {\n      logger.error('Failed to mark RunJob as FAILED after enqueue error', {\n        runJobId: runJob.id,\n        error: updateError instanceof Error ? updateError.message : String(updateError),\n      });\n    }\n\n    throw error;\n  }\n}\n\n/**\n * Close every cached queue. Call from the HTTP server's shutdown handler so\n * the producer side disconnects from Redis cleanly.\n */\nexport async function closeAllQueues(): Promise<void> {\n  await Promise.all(Array.from(queueCache.values()).map((q) => q.close()));\n  queueCache.clear();\n}\n"],"names":[],"mappings":"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","debug_id":"f8634186-ae9e-551f-96ec-058802ec2c99"}
+{"version":3,"file":"queues.js","sources":["workers/queues.ts"],"sourceRoot":"/","sourcesContent":["/**\n * BullMQ queue producers and the `enqueueRunJob` helper.\n *\n * Producer side only — safe to import from HTTP routes / services running on\n * Vercel. Importing this file does NOT start any workers; workers live in\n * `src/workers/processors/*` and are wired up by `src/workers/index.ts`,\n * which is the entrypoint of the separate long-running worker process.\n */\nimport { Queue, type JobsOptions } from 'bullmq';\nimport { Prisma, type RunJobType } from '@prisma/client';\nimport { bullConnection } from './connection.js';\nimport { prisma } from '../lib/prisma.js';\nimport { logger } from '../utils/logger.js';\n\nconst DEFAULT_JOB_OPTIONS: JobsOptions = {\n  attempts: 3,\n  backoff: { type: 'exponential', delay: 5_000 },\n  removeOnComplete: { age: 60 * 60 }, // keep completed jobs in Redis for 1h, then drop\n  removeOnFail: { age: 24 * 60 * 60 }, // keep failed jobs for 24h for inspection\n};\n\n/**\n * Map RunJobType → (queue name, input payload shape).\n *\n * Add a new entry here whenever you introduce a new background job type.\n * The queue name string must match what the corresponding processor passes\n * to `new Worker(<name>, ...)`.\n */\nexport type JobInputs = {\n  /**\n   * `worksheetId` is the placeholder Worksheet row created synchronously by\n   * the producer (so the client has an id to navigate to). The pipeline fills\n   * that row in asynchronously and broadcasts progress on the per-worksheet\n   * job channel.\n   */\n  PDF_TO_WORKSHEET: { gcsUrl: string; classId: string; worksheetId: string };\n  GRADE_WORKSHEET: { worksheetResponseId: string };\n  /**\n   * `aiMessageId` is the placeholder AI Message row created synchronously by\n   * the producer before enqueue (so the client renders a PENDING bubble in\n   * the timeline). The pipeline fills in the content and flips the row to\n   * COMPLETED / FAILED. Used for both intros and replies — single shape.\n   */\n  AI_LAB_CHAT: { conversationId: string; aiMessageId: string };\n  /**\n   * `aiMessageId` placeholder pattern, same as AI_LAB_CHAT — see above.\n   */\n  AI_NEWTON_CHAT: { conversationId: string; aiMessageId: string };\n  STUDENT_PROGRESS_CHAT: { classId: string; studentId: string; message: string };\n};\n\nexport const QUEUE_NAMES: Record<RunJobType, string> = {\n  PDF_TO_WORKSHEET: 'pdfToWorksheet',\n  GRADE_WORKSHEET: 'gradeWorksheet',\n  AI_LAB_CHAT: 'aiLabChat',\n  AI_NEWTON_CHAT: 'aiNewtonChat',\n  STUDENT_PROGRESS_CHAT: 'studentProgressChat',\n};\n\n/**\n * One Queue instance per type. Created lazily so that importing this module\n * does not eagerly open queues you may never use in a given runtime.\n */\nconst queueCache = new Map<RunJobType, Queue>();\n\nfunction getQueue(type: RunJobType): Queue {\n  let queue = queueCache.get(type);\n  if (!queue) {\n    queue = new Queue(QUEUE_NAMES[type], {\n      connection: bullConnection,\n      defaultJobOptions: DEFAULT_JOB_OPTIONS,\n    });\n    queueCache.set(type, queue);\n  }\n  return queue;\n}\n\nexport interface EnqueueOptions {\n  classId?: string | null;\n  userId?: string | null;\n  /** Override BullMQ job options (attempts, delay, priority, etc.). */\n  jobOptions?: JobsOptions;\n}\n\nexport interface EnqueueResult {\n  runJobId: string;\n  bullJobId: string | null;\n}\n\n/**\n * Create a `RunJob` audit row, enqueue the BullMQ job, and link the two.\n *\n * Returns immediately — the actual work happens on the worker process. The\n * caller can return `runJobId` to the client and have them poll `getRunJob`\n * (or subscribe over Pusher) to track progress.\n *\n * IMPORTANT: do not call this inside a Prisma `$transaction`. If the outer\n * transaction rolls back after the BullMQ job is added, the worker will pick\n * up an orphaned job pointing at a non-existent RunJob row. Enqueue *after*\n * the transaction commits.\n */\nexport async function enqueueRunJob<T extends RunJobType>(\n  type: T,\n  input: JobInputs[T],\n  options: EnqueueOptions = {},\n): Promise<EnqueueResult> {\n  const runJob = await prisma.runJob.create({\n    data: {\n      type,\n      status: 'PENDING',\n      classId: options.classId ?? null,\n      userId: options.userId ?? null,\n      input: input as unknown as Prisma.InputJsonValue,\n    },\n  });\n\n  try {\n    const queue = getQueue(type);\n    const job = await queue.add(\n      QUEUE_NAMES[type],\n      { runJobId: runJob.id, ...input },\n      options.jobOptions,\n    );\n\n    try {\n      await prisma.runJob.update({\n        where: { id: runJob.id },\n        data: { bullJobId: job.id ?? null },\n      });\n    } catch (linkError) {\n      logger.error('RunJob enqueued but bullJobId linkage failed', {\n        runJobId: runJob.id,\n        bullJobId: job.id ?? null,\n        type,\n        error: linkError instanceof Error ? linkError.message : String(linkError),\n      });\n    }\n\n    return { runJobId: runJob.id, bullJobId: job.id ?? null };\n  } catch (error) {\n    logger.error('Failed to enqueue RunJob; marking FAILED', {\n      runJobId: runJob.id,\n      type,\n      error: error instanceof Error ? error.message : String(error),\n    });\n\n    try {\n      await prisma.runJob.update({\n        where: { id: runJob.id },\n        data: {\n          status: 'FAILED',\n          error: error instanceof Error ? error.message : String(error),\n          finishedAt: new Date(),\n        },\n      });\n    } catch (updateError) {\n      logger.error('Failed to mark RunJob as FAILED after enqueue error', {\n        runJobId: runJob.id,\n        error: updateError instanceof Error ? updateError.message : String(updateError),\n      });\n    }\n\n    throw error;\n  }\n}\n\n/**\n * Close every cached queue. Call from the HTTP server's shutdown handler so\n * the producer side disconnects from Redis cleanly.\n */\nexport async function closeAllQueues(): Promise<void> {\n  await Promise.all(Array.from(queueCache.values()).map((q) => q.close()));\n  queueCache.clear();\n}\n"],"names":[],"mappings":"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","debug_id":"feefd10a-9381-5c30-a525-0ffe36e2e323"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studious-lms/server",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Backend server for Studious application",
   "main": "dist/exportType.js",
   "types": "dist/exportType.d.ts",
@@ -29,7 +29,7 @@
     "sentry:sourcemaps": "sentry-cli sourcemaps inject ./dist && sentry-cli sourcemaps upload --org \"${SENTRY_ORG:-studious-lms}\" --project \"${SENTRY_PROJECT:-server}\" ./dist"
   },
   "dependencies": {
-    "@google-cloud/storage": "^7.16.0",
+    "@google-cloud/storage": "^5.18.3",
     "@pdf-lib/fontkit": "^1.1.1",
     "@prisma/client": "^6.7.0",
     "@sentry/cli": "^2.58.2",
@@ -46,7 +46,7 @@
     "express-rate-limit": "^8.2.1",
     "helmet": "^8.1.0",
     "ioredis": "^5.10.0",
-    "nodemailer": "^7.0.4",
+    "nodemailer": "^8.0.7",
     "openai": "^5.23.0",
     "pdf-lib": "^1.17.1",
     "prisma": "^6.7.0",

package/src/index.ts

@@ -187,7 +187,18 @@ app.post('/api/pusher/auth', async (req, res) => {
       }
     }
 
-    if (channel_name.startsWith('private-worksheet-')) {
+    if (channel_name.startsWith('private-worksheet-job-')) {
+      const worksheetId = channel_name.replace('private-worksheet-job-', '');
+      const worksheet = await prisma.worksheet.findFirst({
+        where: {
+          id: worksheetId,
+          class: { teachers: { some: { id: user.id } } },
+        },
+      });
+      if (!worksheet) {
+        return res.status(403).json({ error: 'No access to this worksheet job' });
+      }
+    } else if (channel_name.startsWith('private-worksheet-')) {
       const worksheetId = channel_name.replace('private-worksheet-', '');
       const worksheet = await prisma.studentWorksheetResponse.findFirst({
         where: { id: worksheetId, OR: [

package/src/lib/config/cors.ts

@@ -8,6 +8,7 @@ type CorsEnv = {
 const productionOrigins = [
   'https://www.studious.sh',
   'https://studious.sh',
+  'https://dev.studious.sh',
 ];
 
 const nonProductionOrigins = [

package/src/lib/pusher.ts

@@ -12,5 +12,11 @@ const pusher = new Pusher({
 const chatChannel = (conversationId: string) => `private-conversation-${conversationId}`;
 const worksheetChannel = (worksheetResponseId: string) => `private-worksheet-${worksheetResponseId}`;
 const teacherChannel = (classId: string) => `private-teacher-${classId}`;
+/**
+ * Per-worksheet job channel used for asynchronous worksheet creation
+ * (e.g. PDF → worksheet conversion). Distinct prefix from the student
+ * worksheet-response channel so both can co-exist without auth collisions.
+ */
+const worksheetJobChannel = (worksheetId: string) => `private-worksheet-job-${worksheetId}`;
 
-export { pusher, chatChannel, worksheetChannel, teacherChannel };
+export { pusher, chatChannel, worksheetChannel, teacherChannel, worksheetJobChannel };

package/src/models/attendance.ts

@@ -113,6 +113,11 @@ export function findClassWithTeacher(classId: string, teacherId: string) {
       id: classId,
       ...classTeacherOrSchoolAdminWhere(teacherId),
     },
+    select: {
+      id: true,
+      name: true,
+      students: { select: { id: true } },
+    },
   });
 }
 
@@ -137,6 +142,16 @@ export function findAttendanceByClassAndEvent(classId: string, eventId: string |
       classId,
       eventId,
     },
+    include: {
+      event: {
+        select: {
+          id: true,
+          name: true,
+        },
+      },
+      late: { select: { id: true } },
+      absent: { select: { id: true } },
+    },
   });
 }
 

package/src/pipelines/aiLabChat.ts

@@ -4,10 +4,13 @@
  */
 import { isAIUser } from "../utils/aiUser.js";
 import { prisma } from "../lib/prisma.js";
-import { JobStatus } from "@prisma/client";
 import { pusher, teacherChannel } from "../lib/pusher.js";
 import type { Assignment, Class, File, Section, User } from "@prisma/client";
-import { inference, sendAIMessage } from "../utils/inference.js";
+import {
+  inference,
+  completePendingAIMessage,
+  failPendingAIMessage,
+} from "../utils/inference.js";
 import { logger } from "../utils/logger.js";
 import { createPdf } from "../lib/jsonConversion.js";
 import { v4 } from "uuid";
@@ -328,52 +331,53 @@ export const getBaseSystemPrompt = (
 
 
 /**
- * Generate and send AI introduction for lab chat
- * Uses the stored context directly from database
+ * Fill the AI introduction placeholder for a brand-new lab chat.
+ *
+ * The caller (service layer) must have already created a PENDING AI Message
+ * row — `aiMessageId` is that placeholder. This function flips it to
+ * COMPLETED with the intro content, or to FAILED on a hard error.
  */
 export const generateAndSendLabIntroduction = async (
     labChatId: string,
     conversationId: string,
     _contextString: string,
-    subject: string
+    _subject: string,
+    aiMessageId: string,
   ): Promise<void> => {
-    try {
-      const introMessage =
-        "Hello teaching team! I'm your AI assistant for course material development. I'll help you create educational content - when you have a clear request, I'll produce it directly. I only ask questions when I need to clarify the topic or scope. What would you like to work on?";
+    const introMessage =
+      "Hello teaching team! I'm your AI assistant for course material development. I'll help you create educational content - when you have a clear request, I'll produce it directly. I only ask questions when I need to clarify the topic or scope. What would you like to work on?";
 
-      await sendAIMessage(introMessage, conversationId, { subject });
-  
-      logger.info('AI Introduction sent', { labChatId, conversationId });
-  
+    try {
+      await completePendingAIMessage(aiMessageId, introMessage);
+      logger.info('AI Introduction sent', { labChatId, conversationId, aiMessageId });
     } catch (error) {
-      logger.error('Failed to generate AI introduction:', { error, labChatId });
-      
-      // Send fallback introduction
-      try {
-        const fallbackIntro = `Hello teaching team! I'm your AI assistant for course material development. I'll help you create educational content - when you have a clear request, I'll produce it directly. I only ask questions when I need to clarify the topic or scope. What would you like to work on?`;
-        
-        await sendAIMessage(fallbackIntro, conversationId, {
-          subject,
-        });
-  
-        logger.info('Fallback AI introduction sent', { labChatId });
-  
-      } catch (fallbackError) {
-        logger.error('Failed to send fallback AI introduction:', { error: fallbackError, labChatId });
-      }
+      logger.error('Failed to complete AI introduction placeholder:', {
+        error,
+        labChatId,
+        aiMessageId,
+      });
+      await failPendingAIMessage(aiMessageId, { reason: 'lab_intro_complete_failed' });
     }
   }
   
   /**
-   * Generate and send AI response to teacher message
-   * Uses the stored context directly from database
-   * @param emitOptions - When provided, emits lab-response-completed/failed on teacher channel
-   * `_teacherMessage` is retained for caller compatibility while generation is anchored by `emitOptions.messageId`.
+   * Fill the AI response placeholder for a teacher reply in a lab chat.
+   *
+   * `aiMessageId` is the PENDING AI Message row created by the service
+   * layer; the pipeline flips it to COMPLETED with content / attachments /
+   * meta, or FAILED on error.  Teacher-channel `lab-response-{pending,
+   * completed,failed}` events fire alongside the chat-channel status flips
+   * (which `completePendingAIMessage` / `failPendingAIMessage` already
+   * broadcast) so the lab list "AI busy" indicator stays accurate.
+   *
+   * `_teacherMessage` is retained for caller compatibility — the actual
+   * conversation history is reloaded from the DB anchored on the AI
+   * placeholder.
    */
   export const generateAndSendLabResponse = async (
     labChatId: string,
     _teacherMessage: string,
-    emitOptions?: { classId: string; messageId: string }
+    emitOptions: { classId: string; aiMessageId: string }
   ): Promise<void> => {
     try {
       // Get lab context from database
@@ -395,9 +399,15 @@ export const generateAndSendLabIntroduction = async (
   
       const conversationId = fullLabChat.conversationId;
   
-      const recentMessages = await loadRecentLabChatMessages(
+      // Anchor history on the AI placeholder — the slice will include the
+      // placeholder itself (empty content) at the top; drop it so the model
+      // does not see an empty assistant turn at the very end.
+      const anchoredMessages = await loadRecentLabChatMessages(
         conversationId,
-        emitOptions?.messageId,
+        emitOptions.aiMessageId,
+      );
+      const recentMessages = anchoredMessages.filter(
+        (msg) => msg.id !== emitOptions.aiMessageId,
       );
   
       const classData = await prisma.class.findUnique({
@@ -486,7 +496,7 @@ export const generateAndSendLabIntroduction = async (
           labChatId,
           conversationId,
           classId: fullLabChat.classId,
-          ...(emitOptions?.messageId ? { messageId: emitOptions.messageId } : {}),
+          aiMessageId: emitOptions.aiMessageId,
         },
       }),
       LAB_CHAT_RESPONSE_TIMEOUT_MS,
@@ -567,8 +577,7 @@ export const generateAndSendLabIntroduction = async (
           }
         }
   
-        // Send the text response to the conversation
-        await sendAIMessage(jsonData.text, conversationId, {
+        await completePendingAIMessage(emitOptions.aiMessageId, jsonData.text, {
           attachments: {
             connect: attachmentIds.map(id => ({ id })),
           },
@@ -586,32 +595,24 @@ export const generateAndSendLabIntroduction = async (
               id: v4(),
             })) || null,
           },
-          subject: fullLabChat.class?.subject || 'Lab',
         });
       } catch (parseError) {
         logger.error('Failed to parse AI response or generate PDF:', { error: parseError, labChatId });
-        // Fallback: send the raw response if parsing fails
-        await sendAIMessage(response.text, conversationId, {
-          subject: fullLabChat.class?.subject || 'Lab',
-        });
+        // Fallback: complete the placeholder with the raw text so the
+        // teacher still sees something useful instead of FAILED.
+        await completePendingAIMessage(emitOptions.aiMessageId, response.text);
       }
 
-      if (emitOptions) {
-        await prisma.message.update({
-          where: { id: emitOptions.messageId },
-          data: { status: JobStatus.COMPLETED },
+      try {
+        await pusher.trigger(teacherChannel(emitOptions.classId), "lab-response-completed", {
+          labChatId,
+          messageId: emitOptions.aiMessageId,
         });
-        try {
-          await pusher.trigger(teacherChannel(emitOptions.classId), "lab-response-completed", {
-            labChatId,
-            messageId: emitOptions.messageId,
-          });
-        } catch (broadcastError) {
-          logger.error("Failed to broadcast lab response completed:", { error: broadcastError });
-        }
+      } catch (broadcastError) {
+        logger.error("Failed to broadcast lab response completed:", { error: broadcastError });
       }
 
-      logger.info('AI response sent', { labChatId, conversationId });
+      logger.info('AI response sent', { labChatId, conversationId, aiMessageId: emitOptions.aiMessageId });
 
     } catch (error) {
       console.error('Full error object:', error);
@@ -621,31 +622,22 @@ export const generateAndSendLabIntroduction = async (
           stack: error.stack,
           name: error.name
         } : error,
-        labChatId
+        labChatId,
+        aiMessageId: emitOptions.aiMessageId,
       });
 
-      if (emitOptions) {
-        try {
-          await prisma.message.update({
-            where: { id: emitOptions.messageId },
-            data: { status: JobStatus.FAILED },
-          });
-        } catch (statusError) {
-          logger.error("Failed to set message status FAILED:", {
-            error: statusError,
-            labChatId,
-            messageId: emitOptions.messageId,
-          });
-        }
-        try {
-          await pusher.trigger(teacherChannel(emitOptions.classId), "lab-response-failed", {
-            labChatId,
-            messageId: emitOptions.messageId,
-            error: "AI response generation failed",
-          });
-        } catch (broadcastError) {
-          logger.error("Failed to broadcast lab response failed:", { error: broadcastError });
-        }
+      await failPendingAIMessage(emitOptions.aiMessageId, {
+        reason: 'lab_response_generation_failed',
+      });
+
+      try {
+        await pusher.trigger(teacherChannel(emitOptions.classId), "lab-response-failed", {
+          labChatId,
+          messageId: emitOptions.aiMessageId,
+          error: "AI response generation failed",
+        });
+      } catch (broadcastError) {
+        logger.error("Failed to broadcast lab response failed:", { error: broadcastError });
       }
 
       throw error; // Re-throw to see the full error in the calling function

package/src/pipelines/aiNewtonChat.ts

@@ -3,11 +3,13 @@
  * Uses assignment context and AI policy levels for tutoring.
  */
 import { prisma } from "../lib/prisma.js";
-import { inference } from "../utils/inference.js";
+import {
+  inference,
+  completePendingAIMessage,
+  failPendingAIMessage,
+} from "../utils/inference.js";
 import { logger } from "../utils/logger.js";
-import { sendAIMessage } from "../utils/inference.js";
 import { isAIUser } from "../utils/aiUser.js";
-import { Assignment } from "@prisma/client";
 
 
 // AI Policy Levels Configuration
@@ -79,12 +81,18 @@ export interface AIPolicyLevel {
   ];
   
 /**
- * Generate and send AI introduction for Newton chat
+ * Fill the Newton tutor introduction placeholder.
+ *
+ * `aiMessageId` is the PENDING AI Message row created by the service layer
+ * (see `getTutorConversation`). On success we flip it to COMPLETED with the
+ * generated intro; on failure we fall back to a hardcoded greeting before
+ * marking the placeholder FAILED only as a last resort.
  */
 export const generateAndSendNewtonIntroduction = async (
     newtonChatId: string,
     conversationId: string,
-    submissionId: string
+    submissionId: string,
+    aiMessageId: string,
   ): Promise<void> => {
     try {
       // Get submission details for context
@@ -144,6 +152,7 @@ export const generateAndSendNewtonIntroduction = async (
           newtonChatId,
           conversationId,
           submissionId: submission.id,
+          aiMessageId,
         },
         model: 'command-a-03-2025',
         maxTokens: 300,
@@ -154,28 +163,22 @@ export const generateAndSendNewtonIntroduction = async (
         throw new Error('No response generated from inference API');
       }
   
-      // Send AI introduction using centralized sender
-      await sendAIMessage(response, conversationId, {
-        subject: submission.assignment.class.subject || 'Assignment',
-      });
+      await completePendingAIMessage(aiMessageId, response);
   
-      logger.info('AI Introduction sent', { newtonChatId, conversationId });
+      logger.info('AI Introduction sent', { newtonChatId, conversationId, aiMessageId });
   
     } catch (error) {
-      logger.error('Failed to generate AI introduction:', { error, newtonChatId });
+      logger.error('Failed to generate AI introduction:', { error, newtonChatId, aiMessageId });
       
-      // Send fallback introduction
+      // Fallback: still complete the placeholder so the student isn't stuck
+      // staring at an empty bubble.
       try {
         const fallbackIntro = `Hello! I'm Newton, your AI tutor. I'm here to help you with your assignment. I can answer questions, explain concepts, and guide you through your work. What would you like help with today?`;
-        
-        await sendAIMessage(fallbackIntro, conversationId, {
-          subject: 'Assignment',
-        });
-  
-        logger.info('Fallback AI introduction sent', { newtonChatId });
-  
+        await completePendingAIMessage(aiMessageId, fallbackIntro);
+        logger.info('Fallback AI introduction sent', { newtonChatId, aiMessageId });
       } catch (fallbackError) {
-        logger.error('Failed to send fallback AI introduction:', { error: fallbackError, newtonChatId });
+        logger.error('Failed to send fallback AI introduction:', { error: fallbackError, newtonChatId, aiMessageId });
+        await failPendingAIMessage(aiMessageId, { reason: 'newton_intro_fallback_failed' });
       }
     }
   }
@@ -209,7 +212,11 @@ export const generateAndSendNewtonIntroduction = async (
   };
   
   /**
-   * Generate and send AI response to student message
+   * Fill the Newton AI response placeholder for a student turn.
+   *
+   * `aiMessageId` is the PENDING AI Message row the service created post-tx;
+   * the pipeline flips it to COMPLETED with the generated content (the
+   * helper broadcasts `message-updated` on the chat channel) or to FAILED.
    */
   export const generateAndSendNewtonResponse = async (
     newtonChatId: string,
@@ -225,13 +232,17 @@ export const generateAndSendNewtonIntroduction = async (
           subject: string | null;
         };
       };
-    }
+    },
+    aiMessageId: string,
   ): Promise<void> => {
     try {
-      // Get recent conversation history
+      // Get recent conversation history (excluding the empty AI placeholder
+      // we just created — otherwise the model sees a blank assistant turn at
+      // the very end of the transcript).
       const recentMessages = await prisma.message.findMany({
         where: {
           conversationId,
+          id: { not: aiMessageId },
         },
         include: {
           sender: {
@@ -329,6 +340,7 @@ export const generateAndSendNewtonIntroduction = async (
           newtonChatId,
           conversationId,
           submissionId: submission.id,
+          aiMessageId,
         },
       });
       
@@ -336,13 +348,10 @@ export const generateAndSendNewtonIntroduction = async (
         throw new Error('No response generated from inference API');
       }
   
-      // Send the text response to the conversation
-      await sendAIMessage(response, conversationId, {
-        subject: submission.assignment.class.subject || 'Assignment',
-      });
-  
-      logger.info('AI response sent', { newtonChatId, conversationId });
-  
+      await completePendingAIMessage(aiMessageId, response);
+
+      logger.info('AI response sent', { newtonChatId, conversationId, aiMessageId });
+
     } catch (error) {
       logger.error('Failed to generate AI response:', { 
         error: error instanceof Error ? {
@@ -350,8 +359,15 @@ export const generateAndSendNewtonIntroduction = async (
           stack: error.stack,
           name: error.name
         } : error,
-        newtonChatId 
+        newtonChatId,
+        aiMessageId,
       });
+
+      await failPendingAIMessage(aiMessageId, {
+        reason: 'newton_response_generation_failed',
+      });
+
+      throw error;
     }
   }