@studious-lms/server 1.13.0 → 1.15.0

package/src/routes/aiStream.ts

@@ -0,0 +1,827 @@
+/**
+ * Express routes for AI streaming endpoints.
+ * These routes use the Vercel AI SDK's data stream protocol for streaming AI responses.
+ */
+import { Router } from 'express';
+import type { Request, Response } from 'express';
+import { streamText, stepCountIs, type ModelMessage } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { findUserBySessionToken } from '../models/auth.js';
+import { prisma } from '../lib/prisma.js';
+import { logger } from '../utils/logger.js';
+import { aiTools } from '../services/aiTools.js';
+import {
+  assignmentModifierTools,
+  worksheetModifierTools,
+  type ModifierFieldUpdate,
+} from '../services/aiModifierTools.js';
+import { getRedis } from '../lib/redis.js';
+import { pusher, chatChannel, teacherChannel } from '../lib/pusher.js';
+import { getAIUserId, ensureAIUserExists, isAIUser } from '../utils/aiUser.js';
+import { JobStatus } from '@prisma/client';
+import { updateAssignmentRecord } from '../services/assignment.js';
+import {
+  restoreWorksheetQuestions,
+  updateWorksheetRecord,
+  type WorksheetQuestionSnapshot,
+} from '../services/worksheet.js';
+
+export const aiStreamRouter = Router();
+
+/**
+ * Authenticate request from session token (header or cookie).
+ */
+async function authenticateRequest(req: Request) {
+  const userHeader = req.headers['x-user'];
+  const tokenFromUserHeader = typeof userHeader === 'string' ? userHeader : Array.isArray(userHeader) ? userHeader[0] : undefined;
+  const authorizationHeader = req.headers.authorization;
+  const tokenFromAuthorization =
+    typeof authorizationHeader === 'string' && authorizationHeader.startsWith('Bearer ')
+      ? authorizationHeader.slice(7)
+      : null;
+  const token = tokenFromUserHeader ?? tokenFromAuthorization ?? undefined;
+  if (!token) return null;
+  return findUserBySessionToken(token);
+}
+
+/**
+ * POST /api/ai/chat/stream
+ *
+ * Streams an AI response for a conversation (Lab Chat or Newton Tutor).
+ * Uses the Vercel AI SDK data stream protocol.
+ */
+aiStreamRouter.post('/chat/stream', async (req: Request, res: Response) => {
+  const user = await authenticateRequest(req);
+  if (!user) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+
+  const { conversationId } = req.body as { conversationId?: string };
+  if (!conversationId) {
+    return res.status(400).json({ error: 'conversationId is required' });
+  }
+
+  // Verify user has access to this conversation
+  const membership = await prisma.conversationMember.findFirst({
+    where: { conversationId, userId: user.id },
+  });
+  if (!membership) {
+    return res.status(403).json({ error: 'Access denied' });
+  }
+
+  // Determine context: Lab Chat or Newton Chat
+  const labChat = await prisma.labChat.findFirst({
+    where: { conversationId },
+    select: {
+      id: true,
+      classId: true,
+      context: true,
+      class: { select: { subject: true, name: true } },
+    },
+  });
+
+  const newtonChat = !labChat ? await prisma.newtonChat.findFirst({
+    where: { conversationId },
+    select: {
+      id: true,
+      submission: {
+        select: {
+          id: true,
+          assignment: {
+            select: {
+              title: true,
+              instructions: true,
+              aiPolicyLevel: true,
+              class: { select: { id: true, subject: true, name: true } },
+            },
+          },
+        },
+      },
+    },
+  }) : null;
+
+  if (!labChat && !newtonChat) {
+    return res.status(404).json({ error: 'No AI chat context found for this conversation' });
+  }
+
+  const classId = labChat?.classId || newtonChat?.submission.assignment.class.id;
+  if (!classId) {
+    return res.status(400).json({ error: 'Unable to determine class context' });
+  }
+
+  // Build message history from DB (include attachments so the LLM can see them)
+  const recentMessages = await prisma.message.findMany({
+    where: { conversationId, status: { not: JobStatus.PENDING } },
+    orderBy: { createdAt: 'asc' },
+    take: 20,
+    select: {
+      content: true,
+      senderId: true,
+      status: true,
+      attachments: {
+        select: { id: true, name: true, type: true, path: true },
+      },
+    },
+  });
+
+  const messages: ModelMessage[] = recentMessages
+    .filter((m) => m.content && m.content.length > 0)
+    .map((m) => {
+      const role = isAIUser(m.senderId) ? 'assistant' as const : 'user' as const;
+      if (role === 'assistant' || m.attachments.length === 0) {
+        return { role, content: m.content };
+      }
+      // Append file descriptions to user messages
+      const fileList = m.attachments.map((a) => `${a.name} (${a.type})`).join(', ');
+      return { role, content: `${m.content}\n[Attached files: ${fileList}]` };
+    });
+
+  // Build system prompt based on context type
+  let systemPrompt: string;
+  if (labChat) {
+    systemPrompt = buildLabChatSystemPrompt(labChat);
+  } else {
+    systemPrompt = buildNewtonSystemPrompt(newtonChat!);
+  }
+
+  // Create pending AI message
+  await ensureAIUserExists();
+  const aiMessage = await prisma.message.create({
+    data: {
+      content: '',
+      senderId: getAIUserId(),
+      conversationId,
+      status: JobStatus.PENDING,
+    },
+  });
+
+  // Broadcast pending state
+  await pusher.trigger(chatChannel(conversationId), 'new-message', {
+    id: aiMessage.id,
+    content: '',
+    senderId: getAIUserId(),
+    conversationId,
+    status: JobStatus.PENDING,
+    createdAt: aiMessage.createdAt,
+    sender: {
+      id: getAIUserId(),
+      username: 'Newton_AI',
+      profile: { displayName: 'Newton AI', profilePicture: null },
+    },
+    mentionedUserIds: [],
+    meta: {},
+    attachments: [],
+  });
+
+  // Cache stream content in Redis
+  const redis = getRedis();
+  const streamKey = `stream:${aiMessage.id}`;
+  if (redis) {
+    await redis.set(streamKey, '', 'EX', 600);
+  }
+
+  try {
+    const tools = aiTools(classId);
+
+    const result = streamText({
+      model: openai('gpt-4o-mini'),
+      system: systemPrompt,
+      messages,
+      tools,
+      temperature: 0.7,
+      maxOutputTokens: 4096,
+      stopWhen: stepCountIs(5),
+      onStepFinish: async ({ toolCalls }) => {
+        // Broadcast tool call events so all clients can show inline indicators
+        if (toolCalls && toolCalls.length > 0) {
+          for (const tc of toolCalls) {
+            await pusher.trigger(chatChannel(conversationId), 'message-tool-call', {
+              messageId: aiMessage.id,
+              toolName: tc.toolName,
+              status: 'executing',
+            }).catch((err: unknown) => {
+              logger.error('Failed to broadcast tool call event', { err, messageId: aiMessage.id });
+            });
+          }
+        }
+      },
+      onFinish: async ({ text }) => {
+        // Persist completed message
+        await prisma.message.update({
+          where: { id: aiMessage.id },
+          data: { content: text, status: JobStatus.COMPLETED },
+        });
+
+        // Broadcast final state
+        await pusher.trigger(chatChannel(conversationId), 'message-updated', {
+          id: aiMessage.id,
+          content: text,
+          senderId: getAIUserId(),
+          conversationId,
+          status: JobStatus.COMPLETED,
+          sender: {
+            id: getAIUserId(),
+            username: 'Newton_AI',
+            profile: { displayName: 'Newton AI', profilePicture: null },
+          },
+          mentionedUserIds: [],
+          meta: {},
+          attachments: [],
+        });
+
+        // Clean up Redis
+        if (redis) {
+          await redis.del(streamKey);
+        }
+
+        logger.info('AI stream completed', {
+          messageId: aiMessage.id,
+          conversationId,
+          contentLength: text.length,
+        });
+      },
+    });
+
+    // Stream to the requesting client via SSE and broadcast chunks via Pusher
+    // so other participants also see progressive updates.
+    res.writeHead(200, {
+      'Content-Type': 'text/plain; charset=utf-8',
+      'Transfer-Encoding': 'chunked',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    });
+
+    let chunkBuffer = '';
+    for await (const chunk of result.textStream) {
+      // Write to HTTP response for the requesting client
+      res.write(chunk);
+
+      // Buffer chunks to avoid excessive Pusher calls (batch per ~100 chars)
+      chunkBuffer += chunk;
+      if (chunkBuffer.length >= 100) {
+        await pusher.trigger(chatChannel(conversationId), 'message-stream-chunk', {
+          messageId: aiMessage.id,
+          chunk: chunkBuffer,
+        }).catch(() => {});
+        // Update Redis cache
+        if (redis) {
+          await redis.append(streamKey, chunkBuffer);
+        }
+        chunkBuffer = '';
+      }
+    }
+
+    // Flush remaining buffer
+    if (chunkBuffer.length > 0) {
+      await pusher.trigger(chatChannel(conversationId), 'message-stream-chunk', {
+        messageId: aiMessage.id,
+        chunk: chunkBuffer,
+      }).catch(() => {});
+      if (redis) {
+        await redis.append(streamKey, chunkBuffer);
+      }
+    }
+
+    res.end();
+  } catch (error) {
+    logger.error('AI stream error', { error, conversationId, messageId: aiMessage.id });
+
+    await prisma.message.update({
+      where: { id: aiMessage.id },
+      data: { status: JobStatus.FAILED },
+    });
+
+    if (redis) {
+      await redis.del(streamKey);
+    }
+
+    if (!res.headersSent) {
+      return res.status(500).json({ error: 'Stream failed' });
+    }
+  }
+});
+
+/**
+ * POST /api/ai/modify/stream
+ *
+ * Streams AI modifications to an assignment or worksheet.
+ * Uses ordered-key output format for progressive rendering.
+ */
+aiStreamRouter.post('/modify/stream', async (req: Request, res: Response) => {
+  const user = await authenticateRequest(req);
+  if (!user) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+
+  const { assignmentId, worksheetId, prompt, classId } = req.body as {
+    assignmentId?: string;
+    worksheetId?: string;
+    prompt?: string;
+    classId?: string;
+  };
+
+  if (!prompt || !classId) {
+    return res.status(400).json({ error: 'prompt and classId are required' });
+  }
+
+  if (!assignmentId && !worksheetId) {
+    return res.status(400).json({ error: 'Either assignmentId or worksheetId is required' });
+  }
+
+  // Verify teacher access to class
+  const teacherInClass = await prisma.class.findFirst({
+    where: {
+      id: classId,
+      teachers: { some: { id: user.id } },
+    },
+  });
+  if (!teacherInClass) {
+    return res.status(403).json({ error: 'Teacher access required' });
+  }
+
+  // Build context from existing resource and snapshot pre-edit state for undo
+  let resourceContext: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let preEditSnapshot: Record<string, any> | null = null;
+  if (assignmentId) {
+    const assignment = await prisma.assignment.findUnique({
+      where: { id: assignmentId },
+      include: {
+        markScheme: { select: { structured: true } },
+        gradingBoundary: { select: { structured: true } },
+        section: { select: { name: true } },
+        worksheets: { include: { questions: { orderBy: { order: 'asc' } } } },
+      },
+    });
+    if (!assignment) {
+      return res.status(404).json({ error: 'Assignment not found' });
+    }
+    resourceContext = buildAssignmentContext(assignment);
+    preEditSnapshot = {
+      title: assignment.title,
+      instructions: assignment.instructions,
+      dueDate: assignment.dueDate?.toISOString() ?? null,
+      type: assignment.type,
+      maxGrade: assignment.maxGrade,
+      graded: assignment.graded,
+      weight: assignment.weight,
+      acceptFiles: assignment.acceptFiles,
+      acceptExtendedResponse: assignment.acceptExtendedResponse,
+      acceptWorksheet: assignment.acceptWorksheet,
+      aiPolicyLevel: assignment.aiPolicyLevel,
+      modifiedAt: assignment.modifiedAt?.toISOString() ?? null,
+    };
+  } else {
+    const worksheet = await prisma.worksheet.findUnique({
+      where: { id: worksheetId! },
+      include: { questions: { orderBy: { order: 'asc' } } },
+    });
+    if (!worksheet) {
+      return res.status(404).json({ error: 'Worksheet not found' });
+    }
+    resourceContext = buildWorksheetContext(worksheet);
+    preEditSnapshot = {
+      name: worksheet.name,
+      questions: worksheet.questions.map((q) => ({
+        id: q.id,
+        type: q.type,
+        question: q.question,
+        answer: q.answer,
+        options: q.options,
+        markScheme: q.markScheme,
+        points: q.points,
+        order: q.order,
+      })),
+    };
+  }
+
+  const systemPrompt = buildModifierSystemPrompt(assignmentId ? 'assignment' : 'worksheet');
+
+  const messages: ModelMessage[] = [
+    {
+      role: 'user',
+      content: `Here is the current ${assignmentId ? 'assignment' : 'worksheet'}:\n\n${resourceContext}\n\nTeacher's request: ${prompt}`,
+    },
+  ];
+
+  const resourceId = assignmentId || worksheetId!;
+  const resourceType = assignmentId ? 'assignment' : 'worksheet';
+  const redis = getRedis();
+  const modifyingKey = `aiModifying:${resourceId}`;
+  const channel = teacherChannel(classId);
+
+  // Set Redis flag so other users know a modification is in progress
+  if (redis) {
+    await redis.set(modifyingKey, JSON.stringify({
+      userId: user.id,
+      username: user.username,
+      resourceType,
+      resourceId,
+      startedAt: Date.now(),
+    }), 'EX', 300); // 5 min TTL safety net
+
+    // Store pre-edit snapshot for undo (30 min TTL)
+    if (preEditSnapshot) {
+      const snapshotKey = `aiModifierSnapshot:${resourceId}`;
+      await redis.set(snapshotKey, JSON.stringify({
+        resourceType,
+        resourceId,
+        classId,
+        userId: user.id,
+        snapshot: preEditSnapshot,
+        createdAt: Date.now(),
+      }), 'EX', 1800);
+    }
+  }
+
+  // Broadcast modifier-started to all teachers in the class
+  await pusher.trigger(channel, 'modifier-started', {
+    resourceId,
+    resourceType,
+    userId: user.id,
+    username: user.username,
+  }).catch((err: unknown) => {
+    logger.error('Failed to broadcast modifier-started', { err, resourceId });
+  });
+
+  // Stream to requesting client via SSE; field changes are persisted by the
+  // tools and broadcast to all open editors so they update live + stay locked.
+  res.writeHead(200, {
+    'Content-Type': 'text/plain; charset=utf-8',
+    'Transfer-Encoding': 'chunked',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+  });
+
+  // Called after a tool persists a single field — apply it live everywhere.
+  const onFieldUpdate = async (update: ModifierFieldUpdate) => {
+    await pusher.trigger(channel, 'modifier-field-updated', {
+      resourceId,
+      resourceType,
+      field: update.field,
+      value: update.value,
+      label: update.label,
+    }).catch((err: unknown) => {
+      logger.warn('Failed to broadcast modifier-field-updated', { err, resourceId });
+    });
+    // Human-readable progress for the requesting client's bar.
+    res.write(`Updated ${update.label}.\n`);
+  };
+
+  try {
+    const tools = {
+      ...aiTools(classId),
+      ...(assignmentId
+        ? assignmentModifierTools(user.id, assignmentId, classId, onFieldUpdate)
+        : worksheetModifierTools(worksheetId!, user.id, onFieldUpdate)),
+    };
+
+    const result = streamText({
+      model: openai('gpt-4o-mini'),
+      system: systemPrompt,
+      messages,
+      tools,
+      temperature: 0.3,
+      maxOutputTokens: 8192,
+      stopWhen: stepCountIs(16),
+    });
+
+    // Drain the stream. Field writes happen inside the tools' execute (which
+    // call onFieldUpdate); any narration text is forwarded to the SSE client.
+    for await (const chunk of result.textStream) {
+      res.write(chunk);
+    }
+
+    // Clean up Redis flag and broadcast completion
+    if (redis) {
+      await redis.del(modifyingKey);
+    }
+    await pusher.trigger(channel, 'modifier-complete', {
+      resourceId,
+      resourceType,
+      canUndo: Boolean(redis && preEditSnapshot),
+    }).catch(() => {});
+
+    res.end();
+  } catch (error) {
+    logger.error('AI modify stream error', { error, assignmentId, worksheetId });
+
+    // Clean up Redis flag and broadcast failure
+    if (redis) {
+      await redis.del(modifyingKey);
+    }
+    await pusher.trigger(channel, 'modifier-failed', {
+      resourceId,
+      resourceType,
+    }).catch(() => {});
+
+    if (!res.headersSent) {
+      return res.status(500).json({ error: 'Stream failed' });
+    }
+  }
+});
+
+/**
+ * GET /api/ai/modify/status?resourceId=xxx
+ *
+ * Returns whether an AI modification is currently in progress for a resource.
+ */
+aiStreamRouter.get('/modify/status', async (req: Request, res: Response) => {
+  const user = await authenticateRequest(req);
+  if (!user) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+
+  const { resourceId } = req.query as { resourceId?: string };
+  if (!resourceId) {
+    return res.status(400).json({ error: 'resourceId is required' });
+  }
+
+  const redis = getRedis();
+  if (!redis) {
+    return res.json({ isModifying: false });
+  }
+
+  const data = await redis.get(`aiModifying:${resourceId}`);
+  if (!data) {
+    return res.json({ isModifying: false });
+  }
+
+  try {
+    const parsed = JSON.parse(data);
+    return res.json({
+      isModifying: true,
+      userId: parsed.userId,
+      username: parsed.username,
+      resourceType: parsed.resourceType,
+      startedAt: parsed.startedAt,
+    });
+  } catch {
+    return res.json({ isModifying: false });
+  }
+});
+
+/**
+ * POST /api/ai/modify/undo
+ *
+ * Reverts the most recent AI modifier run for a resource by restoring the
+ * pre-edit snapshot stored in Redis.
+ */
+aiStreamRouter.post('/modify/undo', async (req: Request, res: Response) => {
+  const user = await authenticateRequest(req);
+  if (!user) {
+    return res.status(401).json({ error: 'Authentication required' });
+  }
+
+  const { resourceId, classId } = req.body as { resourceId?: string; classId?: string };
+  if (!resourceId || !classId) {
+    return res.status(400).json({ error: 'resourceId and classId are required' });
+  }
+
+  // Verify teacher access to class
+  const teacherInClass = await prisma.class.findFirst({
+    where: {
+      id: classId,
+      teachers: { some: { id: user.id } },
+    },
+  });
+  if (!teacherInClass) {
+    return res.status(403).json({ error: 'Teacher access required' });
+  }
+
+  const redis = getRedis();
+  if (!redis) {
+    return res.status(400).json({ error: 'Undo not available' });
+  }
+
+  const snapshotKey = `aiModifierSnapshot:${resourceId}`;
+  const raw = await redis.get(snapshotKey);
+  if (!raw) {
+    return res.status(404).json({ error: 'No undo snapshot available (may have expired)' });
+  }
+
+  let parsed: {
+    resourceType: 'assignment' | 'worksheet';
+    resourceId: string;
+    classId: string;
+    userId: string;
+    snapshot: Record<string, unknown>;
+    createdAt: number;
+  };
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return res.status(500).json({ error: 'Corrupt snapshot data' });
+  }
+
+  try {
+    if (parsed.resourceType === 'assignment') {
+      const { modifiedAt: _modifiedAt, ...fields } = parsed.snapshot;
+      await updateAssignmentRecord(user.id, {
+        id: resourceId,
+        classId,
+        ...fields,
+      });
+    } else {
+      const { questions, ...fields } = parsed.snapshot;
+      await updateWorksheetRecord(resourceId, user.id, fields);
+      if (Array.isArray(questions)) {
+        await restoreWorksheetQuestions(
+          resourceId,
+          user.id,
+          questions as WorksheetQuestionSnapshot[],
+        );
+      }
+    }
+
+    // Remove the snapshot so undo can only be used once
+    await redis.del(snapshotKey);
+
+    // Broadcast undo to all teachers so they refresh
+    const channel = teacherChannel(classId);
+    await pusher.trigger(channel, 'modifier-undone', {
+      resourceId,
+      resourceType: parsed.resourceType,
+    }).catch((err: unknown) => {
+      logger.warn('Failed to broadcast modifier-undone', { err, resourceId });
+    });
+
+    return res.json({ success: true });
+  } catch (error) {
+    logger.error('AI modifier undo failed', { error, resourceId });
+    return res.status(500).json({ error: 'Failed to undo changes' });
+  }
+});
+
+// --- Helper functions ---
+
+function buildLabChatSystemPrompt(labChat: {
+  context: string | null;
+  class: { subject: string; name: string } | null;
+}): string {
+  return `You are Newton AI, an intelligent teaching assistant for the class "${labChat.class?.name}" (subject: ${labChat.class?.subject}).
+
+You help teachers create course materials, plan lessons, and manage their class. You have access to tools that let you search through class materials, assignments, and student data.
+
+${labChat.context ? `Context: ${labChat.context}` : ''}
+
+IMPORTANT RULES:
+- Use plain text responses (no markdown formatting)
+- Be conversational and helpful
+- When you need information about class materials or assignments, use the search_materials or search_assignments tools
+- Only ask clarifying questions about content/pedagogy, never about technical details
+- Make reasonable defaults for colors, formats, and technical choices
+- Keep responses concise (2-4 sentences for chat, longer for content creation)`;
+}
+
+function buildNewtonSystemPrompt(newtonChat: {
+  submission: {
+    assignment: {
+      title: string;
+      instructions: string | null;
+      aiPolicyLevel: number | null;
+      class: { subject: string | null; name: string };
+    };
+  };
+}): string {
+  const { assignment } = newtonChat.submission;
+  const policyLevel = assignment.aiPolicyLevel || 2;
+
+  return `You are Newton, an AI tutor helping a student with their assignment.
+
+Assignment: ${assignment.title}
+Subject: ${assignment.class.subject}
+Class: ${assignment.class.name}
+Instructions: ${assignment.instructions || 'No specific instructions provided'}
+AI Policy Level: ${policyLevel}/5
+
+Your role:
+- Help the student understand concepts related to their assignment
+- Guide them through problems without giving direct answers
+- Use the search_materials tool to find relevant class materials when helpful
+- Encourage critical thinking and self-discovery
+- Be supportive, clear, and educational
+- Use plain text only (no markdown)
+
+AI Policy Level ${policyLevel} means:
+${policyLevel <= 2 ? '- Very limited AI assistance. Do NOT provide direct answers or solutions. Only clarify concepts and ask guiding questions.' : ''}
+${policyLevel === 3 ? '- Moderate AI assistance. You can explain concepts and give examples, but avoid solving the exact assignment problems.' : ''}
+${policyLevel >= 4 ? '- Extended AI assistance allowed. You can provide detailed explanations, examples, and guided solutions.' : ''}
+
+NEVER provide complete answers regardless of policy level. Always guide learning.`;
+}
+
+function buildModifierSystemPrompt(resourceType: 'assignment' | 'worksheet'): string {
+  if (resourceType === 'assignment') {
+    return `You are an AI assistant that edits an existing assignment based on teacher instructions.
+
+HOW TO EDIT: You change the assignment by CALLING TOOLS — never by printing the new value as text.
+- Call \`update_assignment_field\` once for every individual field the teacher wants changed.
+  Editable fields: title, instructions, dueDate, type, maxGrade, graded, weight,
+  acceptFiles, acceptExtendedResponse, acceptWorksheet, aiPolicyLevel.
+- Pass the value as a string: booleans as "true"/"false", numbers as digits,
+  dueDate as an ISO 8601 datetime, and type as one of
+  HOMEWORK|QUIZ|TEST|PROJECT|ESSAY|DISCUSSION|PRESENTATION|LAB|OTHER.
+- Use \`search_materials\` first only if you need class context.
+
+RULES:
+- Only change the fields the teacher actually asked about. Do not touch anything else.
+- Each tool call saves immediately and is shown to the teacher live.
+- After making all the changes, write a brief conversational summary of what you did.
+  Be human and specific — mention the actual values. For example:
+  "Alright, I've changed the title to 'Chapter 5 Review' and pushed the due date to next Friday."
+  Do NOT dump the full assignment contents — just summarize the changes naturally.`;
+  }
+
+  return `You are an AI assistant that edits an existing worksheet based on teacher instructions.
+
+HOW TO EDIT: You change the worksheet by CALLING TOOLS — never by printing the new value as text.
+- Call \`update_worksheet_field\` for the field the teacher wants changed (currently: name).
+- Call \`add_worksheet_question\` once per new question. Question types:
+  MULTIPLE_CHOICE|TRUE_FALSE|SHORT_ANSWER|LONG_ANSWER|MATH_EXPRESSION|ESSAY.
+  For MULTIPLE_CHOICE provide \`options\` with exactly one \`isCorrect: true\`.
+- Call \`update_worksheet_question\` / \`delete_worksheet_question\` with the question's
+  Q_ID (shown in the worksheet context) to edit or remove existing questions.
+- Use \`search_materials\` first only if you need class context.
+
+RULES:
+- Only change what the teacher asked about.
+- Each tool call saves immediately and is shown to the teacher live.
+- Write real, pedagogically sound question content with correct answers — never placeholders.
+- After making all the changes, write a brief conversational summary of what you did.
+  Be human and specific — mention the actual values. For example:
+  "Done — I've renamed the worksheet to 'Unit 3 Practice Problems' and added two
+  questions on volumes of revolution."
+  Do NOT dump the full worksheet contents — just summarize naturally.`;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function buildAssignmentContext(assignment: any): string {
+  let context = `TITLE: ${assignment.title}
+INSTRUCTIONS: ${assignment.instructions || '(none)'}
+DUE_DATE: ${assignment.dueDate.toISOString()}
+TYPE: ${assignment.type}
+MAX_GRADE: ${assignment.maxGrade ?? 100}
+SECTION: ${assignment.section?.name || 'NONE'}
+ACCEPT_FILES: ${assignment.acceptFiles}
+ACCEPT_EXTENDED_RESPONSE: ${assignment.acceptExtendedResponse}
+ACCEPT_WORKSHEET: ${assignment.acceptWorksheet}`;
+
+  if (assignment.markScheme) {
+    try {
+      const ms = JSON.parse(assignment.markScheme.structured);
+      context += '\nMARK_SCHEME_START';
+      if (Array.isArray(ms.criteria)) {
+        for (const c of ms.criteria) {
+          context += `\nMS_CRITERION: ${c.description} | POINTS: ${c.points}`;
+        }
+      }
+      context += '\nMARK_SCHEME_END';
+    } catch { /* ignore malformed JSON */ }
+  }
+
+  if (assignment.worksheets && assignment.worksheets.length > 0) {
+    context += '\nQUESTIONS_START';
+    for (const ws of assignment.worksheets) {
+      for (const q of ws.questions) {
+        context += `\nQ_TYPE: ${q.type}`;
+        context += `\nQ_TEXT: ${q.question}`;
+        context += `\nQ_ANSWER: ${q.answer}`;
+        if (q.options && typeof q.options === 'object') {
+          const opts = Array.isArray(q.options) ? q.options : (q.options as Record<string, unknown>).options;
+          if (Array.isArray(opts)) {
+            context += `\nQ_OPTIONS: ${opts.map((o: { text?: string } | string) => typeof o === 'string' ? o : o.text || '').join('|')}`;
+          }
+        }
+        context += `\nQ_POINTS: ${q.points}`;
+        context += '\n---';
+      }
+    }
+    context += '\nQUESTIONS_END';
+  }
+
+  return context;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function buildWorksheetContext(worksheet: any): string {
+  let context = `WORKSHEET_NAME: ${worksheet.name}\nQUESTIONS_START`;
+
+  for (const q of worksheet.questions) {
+    context += `\nQ_ID: ${q.id}`;
+    context += `\nQ_TYPE: ${q.type}`;
+    context += `\nQ_TEXT: ${q.question}`;
+    context += `\nQ_ANSWER: ${q.answer}`;
+    if (q.options && typeof q.options === 'object') {
+      const opts = Array.isArray(q.options) ? q.options : (q.options as Record<string, unknown>).options;
+      if (Array.isArray(opts)) {
+        context += `\nQ_OPTIONS: ${opts.map((o: { text?: string } | string) => typeof o === 'string' ? o : o.text || '').join('|')}`;
+      }
+    }
+    context += `\nQ_POINTS: ${q.points}`;
+    context += '\n---';
+  }
+
+  context += '\nQUESTIONS_END';
+  return context;
+}