/** * The assistant: a tool-using agent that can read the library and documents, analyse * performance, and prepare new material. * * Safety model: * - Read tools run freely. * - Anything it writes lands in a DRAFT that the user reviews and saves. * - Deletes, moves and renames are only PROPOSED; they run after the user confirms. */ import { z } from 'zod'; import type { DraftCard, DraftQuestion } from '../../shared/content.ts'; import { draftsFromValue } from '../../shared/importer.ts'; import type { DB } from '../db.ts'; import { badRequest, HttpError, notFound, type AppContext } from '../http.ts'; import { getAppSettings } from '../settings.ts'; import { createAttempt, missedQuestionIds } from '../services/attempts.ts'; import { createClass, createFolder, getClass, getDeck, getQuiz, listCards, listQuestions, resolveFolder } from '../services/content.ts'; import { deleteDocument, listChunks, searchChunks, sourceLabel } from '../services/documents.ts'; import { hybridSearch } from '../services/semantic.ts'; import { dueCounts } from '../services/srs.ts'; import { topicStats, totals } from '../services/stats.ts'; import { newId, now, parseJson } from '../util.ts'; import { cancelGeneration, createDraft, getDraft, startGeneration, startImprove } from './generate.ts'; import { runPython } from './sandbox.ts'; import { resolveModel, runChat } from './service.ts'; import { pythonOutput, pythonPrelude, quizForPython, RUN_PYTHON_DESCRIPTION } from './verify.ts'; import { AIError, type ChatMessage, type ContentPart, type ToolDef } from './types.ts'; /* ------------------------------ UI event model ------------------------------ */ export type UiItem = | { type: 'draft'; draftId: string; kind: 'quiz' | 'deck' | 'note'; title: string; count: number; status: string } | { type: 'action'; actionId: string; summary: string; changes: string[]; status: 'pending' | 'confirmed' | 'cancelled' | 'failed'; result?: string } | { type: 'sources'; items: { ref: string; chunkId: number; documentId: string; label: string }[] } | { type: 'link'; kind: 'quiz' | 'deck' | 'note' | 'document' | 'class' | 'attempt'; id: string; title: string }; export interface ToolActivity { id: string; name: string; label: string; status: 'running' | 'done' | 'error'; summary?: string; } export type AssistantEvent = | { type: 'start'; conversationId: string; model: string } | { type: 'text'; delta: string } | { type: 'reasoning'; delta: string } | { type: 'tool'; tool: ToolActivity } | { type: 'ui'; item: UiItem } | { type: 'error'; message: string; code: string; detail?: string } | { type: 'done'; conversationId: string; title: string }; export interface AssistantContext { classId?: string | null; documentIds?: string[]; /** Materials the user tagged with @ in this message. */ items?: TaggedItem[]; } export const TAG_KINDS = ['quiz', 'deck', 'note', 'document', 'folder'] as const; export type TagKind = (typeof TAG_KINDS)[number]; export interface TaggedItem { kind: TagKind; id: string; title: string; } interface ToolRun { output: unknown; summary?: string; ui?: UiItem[]; } interface ToolSpec { def: ToolDef; label: (input: Record) => string; run: (input: Record, env: ToolEnv) => Promise | ToolRun; } interface ToolEnv { app: AppContext; conversationId: string; context: AssistantContext; signal?: AbortSignal; modelId?: string | null; } const obj = (properties: Record, required: string[] = []) => ({ type: 'object', properties, required }); const S = { type: 'string' } as const; const clip = (text: string, max: number) => (text.length > max ? `${text.slice(0, max)}…` : text); /* ------------------------------ tools ------------------------------ */ function classIdOr(env: ToolEnv, given: unknown): string | undefined { return (typeof given === 'string' && given) || env.context.classId || undefined; } function requireClass(env: ToolEnv, given: unknown): string { const id = classIdOr(env, given); if (!id) throw badRequest('class_id is required. Call list_classes to find it, or ask the user which class to use.'); getClass(env.app.db, id); return id; } async function runGenerate(env: ToolEnv, request: Record): Promise { const { draftId, done } = startGeneration(env.app, { ...request, modelId: undefined } as never, { conversationId: env.conversationId, origin: 'assistant' }); const onAbort = () => cancelGeneration(draftId); env.signal?.addEventListener('abort', onAbort, { once: true }); const draft = await done; env.signal?.removeEventListener('abort', onAbort); if (draft.status !== 'ready') throw new AIError('server', draft.error || 'Generation did not finish.'); const unit = draft.kind === 'quiz' ? 'questions' : draft.kind === 'deck' ? 'cards' : 'characters'; return { output: { draft_id: draftId, status: 'draft_ready_for_review', title: draft.title, [unit]: draft.itemCount, notes: draft.meta.notes ?? [], important: 'This is a DRAFT shown to the user as a preview card. It is not saved. Tell the user to review and save it; do not claim it was added to their library.', }, summary: `${draft.itemCount} ${unit}`, ui: [{ type: 'draft', draftId, kind: draft.kind, title: draft.title, count: draft.itemCount, status: 'ready' }], }; } const TOOLS: ToolSpec[] = [ { def: { name: 'list_classes', description: 'List every class with counts of quizzes, decks, documents and notes, and flashcards due.', parameters: obj({}) }, label: () => 'Looking at your classes', run: (_input, { app }) => { const s = getAppSettings(app.db, app.config.timezone); const rows = app.db.all>( `SELECT k.id, k.name, k.code, k.archived, (SELECT COUNT(*) FROM quizzes WHERE class_id = k.id) AS quizzes, (SELECT COUNT(*) FROM decks WHERE class_id = k.id) AS decks, (SELECT COUNT(*) FROM documents WHERE class_id = k.id) AS documents, (SELECT COUNT(*) FROM notes WHERE class_id = k.id) AS notes FROM classes k ORDER BY k.archived, k.sort_order`, ); return { output: rows.map((r) => ({ ...r, archived: Boolean(r.archived), flashcards_due: dueCounts(app.db, { classId: r.id }, s).total })), summary: `${rows.length} classes` }; }, }, { def: { name: 'list_materials', description: 'List the folders, quizzes, flashcard decks, uploaded documents and notes in one class, with ids.', parameters: obj({ class_id: { ...S, description: 'Defaults to the class the user is currently viewing.' } }), }, label: () => 'Listing class materials', run: (input, env) => { const { db } = env.app; const classId = requireClass(env, input.class_id); const cls = getClass(db, classId); const q = (sql: string) => db.all(sql, classId); const quizzes = q>(`SELECT z.id, z.title, z.folder_id, (SELECT COUNT(*) FROM questions WHERE quiz_id = z.id) AS questions FROM quizzes z WHERE z.class_id = ? ORDER BY z.sort_order`); const decks = q>(`SELECT d.id, d.title, d.folder_id, (SELECT COUNT(*) FROM cards WHERE deck_id = d.id) AS cards FROM decks d WHERE d.class_id = ? ORDER BY d.sort_order`); const documents = q>(`SELECT id, title, kind, status, page_count AS pages, token_count AS approx_tokens, folder_id FROM documents WHERE class_id = ? ORDER BY sort_order`); const notes = q>(`SELECT id, title, folder_id FROM notes WHERE class_id = ? ORDER BY sort_order`); const folders = q>(`SELECT id, name FROM folders WHERE class_id = ? ORDER BY sort_order`); const withUrl = (rows: Record[], base: string) => rows.map((x) => ({ ...x, url: `/${base}/${x.id}` })); return { output: { class: { id: cls.id, name: cls.name, url: `/classes/${cls.id}` }, folders, quizzes: withUrl(quizzes, 'quizzes'), decks: withUrl(decks, 'decks'), documents: withUrl(documents, 'documents'), notes: withUrl(notes, 'notes') }, summary: `${quizzes.length + decks.length + documents.length + notes.length} items in ${cls.name}`, }; }, }, { def: { name: 'search_documents', description: 'Full-text search inside the uploaded documents (textbook chapters, slides, notes). Returns the most relevant excerpts, each with a ref id like "c42". Use specific keywords; run several searches for different aspects of a question.', parameters: obj( { query: { ...S, description: 'Keywords to look for.' }, class_id: { ...S, description: 'Limit to one class. Defaults to the current class.' }, document_ids: { type: 'array', items: S, description: 'Limit to specific documents.' }, limit: { type: 'integer', description: 'Number of excerpts, 1-12. Default 6.' }, }, ['query'], ), }, label: (i) => `Searching documents for "${clip(String(i.query ?? ''), 50)}"`, run: async (input, env) => { const docIds = (Array.isArray(input.document_ids) && input.document_ids.length ? input.document_ids : env.context.documentIds) as string[] | undefined; const scope = docIds?.length ? { documentIds: docIds } : { classId: classIdOr(env, input.class_id) ?? null }; const limit = Math.max(1, Math.min(12, Number(input.limit) || 6)); const hits = await hybridSearch(env.app, String(input.query ?? ''), scope, limit); if (hits.length === 0) return { output: { results: [], note: 'No matching passages. Try different keywords, or list_materials to check which documents exist.' }, summary: 'No matches' }; return { output: { results: hits.map((h) => ({ ref: `c${h.id}`, document_id: h.documentId, source: sourceLabel(h), heading: h.heading || undefined, text: clip(h.text, 2400) })) }, summary: `${hits.length} passages`, ui: [{ type: 'sources', items: hits.map((h) => ({ ref: `c${h.id}`, chunkId: h.id, documentId: h.documentId, label: sourceLabel(h) })) }], }; }, }, { def: { name: 'read_document', description: 'Read a document sequentially (for summarising a chapter or a page range). Returns consecutive sections with ref ids; call again with next_start to continue.', parameters: obj( { document_id: S, start: { type: 'integer', description: 'Section index to start from. Default 0.' }, page: { type: 'integer', description: 'Start at this page or slide number instead of a section index.' }, max_sections: { type: 'integer', description: '1-30. Default 12.' }, }, ['document_id'], ), }, label: () => 'Reading a document', run: (input, { app }) => { const doc = app.db.get>('SELECT id, title, status, chunk_count, page_count FROM documents WHERE id = ?', String(input.document_id)); if (!doc) throw notFound('Document'); if (doc.status !== 'ready') return { output: { error: `This document is not ready (status: ${doc.status}).` } }; let start = Math.max(0, Number(input.start) || 0); if (input.page) { const row = app.db.get<{ seq: number }>('SELECT seq FROM chunks WHERE document_id = ? AND (page_end >= ? OR page_start >= ?) ORDER BY seq LIMIT 1', doc.id, Number(input.page), Number(input.page)); if (row) start = row.seq; } const max = Math.max(1, Math.min(30, Number(input.max_sections) || 12)); const chunks = listChunks(app.db, doc.id, start, max); const last = chunks[chunks.length - 1]; return { output: { document: { id: doc.id, title: doc.title, pages: doc.page_count, total_sections: doc.chunk_count }, sections: chunks.map((c) => ({ ref: `c${c.id}`, index: c.seq, source: sourceLabel(c), heading: c.heading || undefined, text: c.text })), next_start: last && last.seq + 1 < doc.chunk_count ? last.seq + 1 : null, }, summary: `${doc.title}: sections ${start + 1}-${start + chunks.length} of ${doc.chunk_count}`, ui: chunks.length ? [{ type: 'sources', items: chunks.map((c) => ({ ref: `c${c.id}`, chunkId: c.id, documentId: c.documentId, label: sourceLabel(c) })) }] : undefined, }; }, }, { def: { name: 'search_library', description: 'Search quiz questions, flashcards, notes and titles by keyword. Use to find existing material on a topic. Every result has a url you can link to.', parameters: obj({ query: S, class_id: S }, ['query']), }, label: (i) => `Searching your library for "${clip(String(i.query ?? ''), 50)}"`, run: (input, env) => { const { db } = env.app; const like = `%${String(input.query ?? '').replace(/[\\%_]/g, (m) => `\\${m}`)}%`; const classId = typeof input.class_id === 'string' && input.class_id ? input.class_id : null; const cls = classId ? 'AND z.class_id = ?' : ''; const p = classId ? [classId] : []; const questions = db.all>( `SELECT q.id, q.stem, q.topic, z.id AS quiz_id, z.title AS quiz FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE (q.stem LIKE ? ESCAPE '\\' OR q.topic LIKE ? ESCAPE '\\') ${cls} LIMIT 15`, like, like, ...p, ); const cards = db.all>( `SELECT c.id, c.front, c.back, z.id AS deck_id, z.title AS deck FROM cards c JOIN decks z ON z.id = c.deck_id WHERE (c.front LIKE ? ESCAPE '\\' OR c.back LIKE ? ESCAPE '\\') ${cls} LIMIT 15`, like, like, ...p, ); const URL_BASE: Record = { quiz: 'quizzes', deck: 'decks', note: 'notes', document: 'documents' }; const titles = [ ...db.all>(`SELECT 'quiz' AS kind, z.id, z.title FROM quizzes z WHERE z.title LIKE ? ESCAPE '\\' ${cls} LIMIT 8`, like, ...p), ...db.all>(`SELECT 'deck' AS kind, z.id, z.title FROM decks z WHERE z.title LIKE ? ESCAPE '\\' ${cls} LIMIT 8`, like, ...p), ...db.all>(`SELECT 'note' AS kind, z.id, z.title FROM notes z WHERE z.title LIKE ? ESCAPE '\\' ${cls} LIMIT 8`, like, ...p), ...db.all>(`SELECT 'document' AS kind, z.id, z.title FROM documents z WHERE z.title LIKE ? ESCAPE '\\' ${cls} LIMIT 8`, like, ...p), ].map((x) => ({ ...x, url: `/${URL_BASE[x.kind]}/${x.id}` })); const notes = db .all>(`SELECT z.id, z.title, z.content FROM notes z WHERE z.content LIKE ? ESCAPE '\\' ${cls} LIMIT 6`, like, ...p) .map((n) => { const at = Math.max(0, String(n.content).toLowerCase().indexOf(String(input.query ?? '').toLowerCase()) - 120); return { id: n.id, title: n.title, url: `/notes/${n.id}`, excerpt: clip(String(n.content).slice(at), 400) }; }); return { output: { titles, questions: questions.map((q) => ({ ...q, stem: clip(q.stem, 300), url: `/quizzes/${q.quiz_id}?q=${q.id}` })), cards: cards.map((c) => ({ ...c, front: clip(c.front, 200), back: clip(c.back, 300), url: `/decks/${c.deck_id}?card=${c.id}` })), notes, note: 'For passages inside uploaded documents, use search_documents.', }, summary: `${titles.length + questions.length + cards.length + notes.length} matches`, }; }, }, { def: { name: 'get_quiz', description: 'Get a quiz with its questions, answer choices and rationales.', parameters: obj({ quiz_id: S, offset: { type: 'integer' }, limit: { type: 'integer', description: 'Default 25, max 60.' } }, ['quiz_id']) }, label: () => 'Opening a quiz', run: (input, { app }) => { const quiz = getQuiz(app.db, String(input.quiz_id)); const all = listQuestions(app.db, quiz.id); const offset = Math.max(0, Number(input.offset) || 0); const limit = Math.max(1, Math.min(60, Number(input.limit) || 25)); return { output: { id: quiz.id, title: quiz.title, url: `/quizzes/${quiz.id}`, class_id: quiz.class_id, total_questions: all.length, questions: all.slice(offset, offset + limit).map((q) => ({ id: q.id, type: q.type, stem: q.stem, options: q.options.map((o) => ({ text: o.text, correct: o.correct })), rationale: clip(q.rationale, 800), topic: q.topic, })), }, summary: `${quiz.title} (${all.length} questions)`, }; }, }, { def: { name: 'get_deck', description: 'Get a flashcard deck with its cards.', parameters: obj({ deck_id: S, offset: { type: 'integer' }, limit: { type: 'integer', description: 'Default 60, max 150.' } }, ['deck_id']) }, label: () => 'Opening a deck', run: (input, { app }) => { const deck = getDeck(app.db, String(input.deck_id)); const all = listCards(app.db, deck.id); const offset = Math.max(0, Number(input.offset) || 0); const limit = Math.max(1, Math.min(150, Number(input.limit) || 60)); return { output: { id: deck.id, title: deck.title, url: `/decks/${deck.id}`, class_id: deck.class_id, total_cards: all.length, cards: all.slice(offset, offset + limit).map((c) => ({ id: c.id, front: clip(c.front, 300), back: clip(c.back, 500) })) }, summary: `${deck.title} (${all.length} cards)`, }; }, }, { def: { name: 'read_note', description: 'Read one of the user\'s notes or study guides (Markdown).', parameters: obj({ note_id: S }, ['note_id']) }, label: () => 'Reading a note', run: (input, { app }) => { const note = app.db.get<{ id: string; title: string; content: string; class_id: string }>('SELECT id, title, content, class_id FROM notes WHERE id = ?', String(input.note_id)); if (!note) throw notFound('Note'); return { output: { id: note.id, title: note.title, url: `/notes/${note.id}`, class_id: note.class_id, content: clip(note.content, 24000) }, summary: note.title }; }, }, { def: { name: 'get_performance', description: 'Study statistics: accuracy by topic (weakest first), the questions missed most often, recent totals, and flashcards due. Use before recommending what to study or building practice from weak areas.', parameters: obj({ class_id: { ...S, description: 'Omit for all classes.' }, days: { type: 'integer', description: 'Look-back window. Default 60.' } }), }, label: () => 'Reviewing your performance', run: (input, { app }) => { const { db } = app; const s = getAppSettings(db, app.config.timezone); const classId = typeof input.class_id === 'string' && input.class_id ? input.class_id : undefined; const days = Math.max(7, Math.min(365, Number(input.days) || 60)); const topics = topicStats(db, { classId }, days).filter((t) => t.seen >= 2).slice(0, 25); const missedIds = missedQuestionIds(db, { classId }, 20); const missed = missedIds .map((id) => db.get>( `SELECT q.id, q.stem, q.topic, z.title AS quiz, (SELECT COUNT(*) FROM responses r WHERE r.question_id = q.id) AS attempts, (SELECT COUNT(*) FROM responses r WHERE r.question_id = q.id AND r.correct = 0) AS wrong FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE q.id = ?`, id, ), ) .filter(Boolean) .map((q) => ({ ...q!, stem: clip(q!.stem, 240) })); const t = totals(db, s, { classId }, days); return { output: { window_days: days, totals: { questions_answered: t.questionsAnswered, accuracy_percent: t.accuracy === null ? null : Math.round(t.accuracy * 100), flashcards_reviewed: t.cardsReviewed, quizzes_completed: t.quizzesCompleted, study_days: t.studyDays }, flashcards_due_now: dueCounts(db, { classId }, s).total, topics: topics.map((x) => ({ topic: x.topic, class: x.className, answered: x.seen, accuracy_percent: Math.round(x.accuracy * 100) })), most_missed_questions: missed, }, summary: `${topics.length} topics, ${missed.length} missed questions`, }; }, }, { def: { name: 'generate_quiz', description: 'Write a new practice quiz and show it to the user as a draft to review. Runs a dedicated generation pipeline that reads the chosen source material itself, so do NOT paste document text into the arguments. Sources (combine as needed): specific documents, all documents in the class, the user\'s weak areas, an existing flashcard deck, or just a topic.', parameters: obj( { class_id: { ...S, description: 'Class the quiz belongs to. Defaults to the current class.' }, title: S, topic: { ...S, description: 'What the questions should focus on, e.g. "pediatric respiratory disorders". Also used to pick the relevant passages.' }, count: { type: 'integer', description: 'Number of questions, 1-100. Default 15.' }, style: { type: 'string', enum: ['nclex', 'standard', 'recall'], description: 'nclex = clinical-judgment items (default).' }, difficulty: { type: 'string', enum: ['easy', 'medium', 'hard', 'mixed'] }, sata_share: { type: 'number', description: 'Fraction (0-1) of select-all-that-apply questions.' }, document_ids: { type: 'array', items: S, description: 'Documents to base the quiz on.' }, use_all_class_documents: { type: 'boolean', description: 'Use every document in the class.' }, from_weak_areas: { type: 'boolean', description: 'Target the concepts behind the questions the user keeps missing.' }, from_deck_id: { ...S, description: 'Convert this flashcard deck into quiz questions.' }, instructions: { ...S, description: 'Any extra guidance from the user.' }, }, [], ), }, label: (i) => `Writing ${i.count ?? 15} quiz questions`, run: (input, env) => runGenerate(env, { kind: 'quiz', classId: requireClass(env, input.class_id), title: input.title || undefined, focus: input.topic || undefined, count: Math.max(1, Math.min(100, Number(input.count) || 15)), style: input.style || 'nclex', difficulty: input.difficulty || undefined, sataShare: typeof input.sata_share === 'number' ? Math.max(0, Math.min(1, input.sata_share)) : undefined, instructions: input.instructions || undefined, source: { documentIds: Array.isArray(input.document_ids) && input.document_ids.length ? input.document_ids : !input.use_all_class_documents && !input.from_weak_areas && !input.from_deck_id ? env.context.documentIds : undefined, allClassDocuments: Boolean(input.use_all_class_documents), weakAreas: Boolean(input.from_weak_areas), deckId: input.from_deck_id || undefined, }, }), }, { def: { name: 'generate_flashcards', description: 'Write a new flashcard deck and show it to the user as a draft to review. Reads the chosen source material itself. Sources: specific documents, all class documents, an existing quiz, or just a topic.', parameters: obj( { class_id: S, title: S, topic: { ...S, description: 'Focus, e.g. "medications and adverse effects".' }, count: { type: 'integer', description: 'Number of cards, 1-200. Default 30.' }, card_style: { type: 'string', enum: ['concise', 'detailed', 'medication', 'definition'] }, document_ids: { type: 'array', items: S }, use_all_class_documents: { type: 'boolean' }, from_quiz_id: { ...S, description: 'Convert this quiz into flashcards.' }, instructions: S, }, [], ), }, label: (i) => `Writing ${i.count ?? 30} flashcards`, run: (input, env) => runGenerate(env, { kind: 'deck', classId: requireClass(env, input.class_id), title: input.title || undefined, focus: input.topic || undefined, count: Math.max(1, Math.min(200, Number(input.count) || 30)), cardStyle: input.card_style || undefined, instructions: input.instructions || undefined, source: { documentIds: Array.isArray(input.document_ids) && input.document_ids.length ? input.document_ids : !input.use_all_class_documents && !input.from_quiz_id ? env.context.documentIds : undefined, allClassDocuments: Boolean(input.use_all_class_documents), quizId: input.from_quiz_id || undefined, }, }), }, { def: { name: 'write_study_guide', description: 'Write a study guide, summary, outline or cheat sheet from documents (handles long documents) and show it as a draft note to review.', parameters: obj( { class_id: S, title: S, format: { type: 'string', enum: ['study_guide', 'summary', 'outline', 'cheat_sheet'] }, topic: { ...S, description: 'Optional focus within the material (a chapter, section or concept).' }, document_ids: { type: 'array', items: S }, use_all_class_documents: { type: 'boolean' }, instructions: S, }, [], ), }, label: () => 'Writing a study guide', run: (input, env) => runGenerate(env, { kind: 'note', classId: requireClass(env, input.class_id), title: input.title || undefined, focus: input.topic || undefined, noteStyle: input.format || 'study_guide', instructions: input.instructions || undefined, source: { documentIds: Array.isArray(input.document_ids) && input.document_ids.length ? input.document_ids : !input.use_all_class_documents ? env.context.documentIds : undefined, allClassDocuments: Boolean(input.use_all_class_documents), }, }), }, { def: { name: 'create_draft', description: 'Show content YOU have written in this conversation as a draft for the user to review and save: a quiz (questions), a flashcard deck (cards) or a note (Markdown). Use for small or highly specific requests; for larger sets based on documents prefer generate_quiz / generate_flashcards / write_study_guide.', parameters: obj( { kind: { type: 'string', enum: ['quiz', 'deck', 'note'] }, class_id: S, title: S, questions: { type: 'array', items: obj( { type: { type: 'string', enum: ['single', 'multi', 'numeric'], description: 'numeric = the student types a number (calculations); its options hold only the correct answer, e.g. "12.5 mL".' }, stem: S, options: { type: 'array', items: obj({ text: S, correct: { type: 'boolean' }, why: S }, ['text', 'correct']) }, rationale: S, topic: S, difficulty: { type: 'string', enum: ['easy', 'medium', 'hard'] }, }, ['type', 'stem', 'options', 'rationale'], ), }, cards: { type: 'array', items: obj({ front: S, back: S, hint: S }, ['front', 'back']) }, content: { ...S, description: 'Markdown body, for kind = note.' }, }, ['kind', 'title'], ), }, label: (i) => `Preparing a ${i.kind === 'deck' ? 'flashcard' : i.kind} draft`, run: (input, env) => { const kind = input.kind as 'quiz' | 'deck' | 'note'; const classId = classIdOr(env, input.class_id) ?? null; const title = String(input.title ?? '').slice(0, 200) || 'Untitled'; let count = 0; let draftId: string; if (kind === 'note') { const content = String(input.content ?? ''); if (!content.trim()) throw badRequest('content is required for a note'); count = content.length; draftId = createDraft(env.app.db, { kind, classId, title, payload: { kind: 'note', title, content }, meta: { origin: 'assistant' }, conversationId: env.conversationId }); } else { const parsed = draftsFromValue(kind === 'quiz' ? { kind: 'quiz', title, questions: input.questions } : { kind: 'deck', title, cards: input.cards }).items[0]; if (!parsed || parsed.kind !== kind) throw badRequest(`Provide ${kind === 'quiz' ? 'questions' : 'cards'}`); const items: (DraftQuestion | DraftCard)[] = parsed.kind === 'quiz' ? parsed.questions : parsed.kind === 'deck' ? parsed.cards : []; if (items.length === 0) throw badRequest(`Provide at least one ${kind === 'quiz' ? 'question' : 'card'}`); count = items.length; draftId = createDraft(env.app.db, { kind, classId, title, payload: parsed, meta: { origin: 'assistant' }, conversationId: env.conversationId }); } return { output: { draft_id: draftId, status: 'draft_ready_for_review', important: 'Shown to the user as a preview card. Not saved until they review and save it.' }, summary: kind === 'note' ? 'Note draft' : `${count} ${kind === 'quiz' ? 'questions' : 'cards'}`, ui: [{ type: 'draft', draftId, kind, title, count, status: 'ready' }], }; }, }, { def: { name: 'improve_questions', description: 'Rewrite existing quiz questions (clearer stems, better distractors, fuller rationales). Produces a draft of revisions that the user can review and apply to the quiz.', parameters: obj({ quiz_id: S, question_ids: { type: 'array', items: S, description: 'Omit to review the whole quiz (first 60 questions).' }, instructions: S }, ['quiz_id']), }, label: () => 'Improving questions', run: async (input, env) => { const { draftId, done } = startImprove(env.app, { quizId: String(input.quiz_id), questionIds: Array.isArray(input.question_ids) ? input.question_ids : undefined, instructions: input.instructions || undefined }, { conversationId: env.conversationId }); const draft = await done; if (draft.status !== 'ready') throw new AIError('server', draft.error || 'Could not improve the questions.'); return { output: { draft_id: draftId, status: 'revisions_ready_for_review', revised: draft.itemCount, important: 'The revisions are shown as a draft. The original quiz is unchanged until the user applies them.' }, summary: `${draft.itemCount} revised`, ui: [{ type: 'draft', draftId, kind: 'quiz', title: `${draft.title} (revisions)`, count: draft.itemCount, status: 'ready' }], }; }, }, { def: { name: 'start_practice', description: 'Start a practice session from EXISTING questions (no new content is written): the questions the user misses most, one quiz, or specific topics. Returns a link the user can open.', parameters: obj( { source: { type: 'string', enum: ['missed', 'quiz', 'topics'] }, class_id: S, quiz_id: S, topics: { type: 'array', items: S }, count: { type: 'integer' }, mode: { type: 'string', enum: ['practice', 'exam'] }, }, ['source'], ), }, label: () => 'Setting up a practice session', run: (input, env) => { const { db } = env.app; const sata = getAppSettings(db, env.app.config.timezone).sataScoring; const source = input.source === 'quiz' ? { type: 'quiz' as const, quizId: String(input.quiz_id ?? '') } : input.source === 'topics' ? { type: 'topics' as const, classId: requireClass(env, input.class_id), topics: (input.topics ?? []) as string[] } : { type: 'missed' as const, classId: classIdOr(env, input.class_id) }; const id = createAttempt(db, { mode: input.mode === 'exam' ? 'exam' : 'practice', source, count: input.count ? Math.max(1, Number(input.count)) : undefined }, sata); const row = db.get<{ title: string; question_count: number }>('SELECT title, question_count FROM attempts WHERE id = ?', id)!; return { output: { session_id: id, title: row.title, questions: row.question_count, note: 'A link to open the session is shown to the user.' }, summary: `${row.question_count} questions`, ui: [{ type: 'link', kind: 'attempt', id, title: `Start: ${row.title} (${row.question_count} questions)` }], }; }, }, { def: { name: 'organize', description: 'Create a class or a folder inside a class. (Deleting, moving and renaming go through propose_changes.)', parameters: obj({ create: { type: 'string', enum: ['class', 'folder'] }, name: S, class_id: { ...S, description: 'Required for a folder.' }, code: { ...S, description: 'Optional course code for a class.' } }, ['create', 'name']), }, label: (i) => `Creating a ${i.create}`, run: (input, env) => { if (input.create === 'class') { const cls = createClass(env.app.db, { name: String(input.name), code: input.code ? String(input.code) : '' }); return { output: { class_id: cls.id, name: cls.name }, summary: cls.name, ui: [{ type: 'link', kind: 'class', id: cls.id, title: cls.name }] }; } const folder = createFolder(env.app.db, requireClass(env, input.class_id), String(input.name)); return { output: { folder_id: folder.id, name: folder.name }, summary: folder.name }; }, }, { def: { name: 'run_python', description: `${RUN_PYTHON_DESCRIPTION} Pass draft_id or quiz_id to load that draft or quiz as the variable \`draft\` / \`quiz\` (dict with "questions": [{"number", "type", "stem", "options": [{"number", "text", "correct"}], "rationale"}]); decks load as {"cards": [{"front", "back"}]}.`, parameters: obj( { code: { ...S, description: 'Python 3 source. Print the results you need.' }, draft_id: { ...S, description: 'Optional: load this draft as `draft`.' }, quiz_id: { ...S, description: 'Optional: load this saved quiz as `quiz`.' }, }, ['code'], ), }, label: () => 'Running Python', run: async (input, env) => { const { db } = env.app; const vars: Record = {}; if (typeof input.draft_id === 'string' && input.draft_id) { const d = getDraft(db, input.draft_id); vars.draft = d.payload.kind === 'quiz' ? { ...quizForPython(d.payload), request: d.meta.request ?? {} } : d.payload.kind === 'deck' ? { title: d.payload.title, cards: d.payload.cards.map((c) => ({ front: c.front, back: c.back })) } : { title: d.payload.title, content: d.payload.content }; } if (typeof input.quiz_id === 'string' && input.quiz_id) { const quiz = getQuiz(db, input.quiz_id); vars.quiz = quizForPython({ title: quiz.title, questions: listQuestions(db, quiz.id).map((q) => ({ ...q, options: q.options.map((o) => ({ text: o.text, correct: o.correct, why: o.why })) })) }); } const r = await runPython((Object.keys(vars).length ? pythonPrelude(vars) : '') + String(input.code ?? '')); const firstLine = (r.error ?? '').trim().split('\n').pop() ?? ''; return { output: pythonOutput(r), summary: r.ok ? (r.stdout.trim().split('\n').pop() ?? r.result ?? 'done').slice(0, 120) : firstLine.slice(0, 160) }; }, }, { def: { name: 'propose_changes', description: 'Propose deleting, moving or renaming quizzes, decks, notes, documents or folders. Nothing happens until the user presses Confirm on the card that appears. Group related changes into one call.', parameters: obj( { reason: { ...S, description: 'One sentence shown to the user explaining the change.' }, changes: { type: 'array', items: obj( { op: { type: 'string', enum: ['delete', 'move', 'rename'] }, kind: { type: 'string', enum: ['quiz', 'deck', 'note', 'document', 'folder'] }, id: S, title: { ...S, description: 'New title (rename).' }, class_id: { ...S, description: 'Destination class (move).' }, folder_id: { ...S, description: 'Destination folder (move). Omit for no folder.' }, }, ['op', 'kind', 'id'], ), }, }, ['reason', 'changes'], ), }, label: () => 'Preparing changes for your approval', run: (input, env) => { const parsed = changesSchema.parse(input.changes); const lines = parsed.map((c) => describeChange(env.app.db, c)); const id = newId(); const summary = String(input.reason ?? '').slice(0, 300) || 'Proposed changes'; env.app.db.run(`INSERT INTO ai_actions (id, conversation_id, kind, summary, payload, status, created_at) VALUES (?, ?, 'changes', ?, ?, 'pending', ?)`, id, env.conversationId, summary, JSON.stringify({ changes: parsed, lines }), now()); return { output: { action_id: id, status: 'awaiting_user_confirmation', changes: lines, important: 'Nothing has changed yet. The user must press Confirm. Do not say the changes were made.' }, summary: `${lines.length} change${lines.length === 1 ? '' : 's'} awaiting confirmation`, ui: [{ type: 'action', actionId: id, summary, changes: lines, status: 'pending' }], }; }, }, ]; /* ------------------------------ confirmable changes ------------------------------ */ const changesSchema = z .array( z.object({ op: z.enum(['delete', 'move', 'rename']), kind: z.enum(['quiz', 'deck', 'note', 'document', 'folder']), id: z.string(), title: z.string().trim().min(1).max(200).optional(), class_id: z.string().optional(), folder_id: z.string().nullish(), }), ) .min(1) .max(100); type Change = z.infer[number]; const CHANGE_TABLE = { quiz: 'quizzes', deck: 'decks', note: 'notes', document: 'documents', folder: 'folders' } as const; function itemTitle(db: DB, kind: Change['kind'], id: string): string { const col = kind === 'folder' ? 'name' : 'title'; const row = db.get<{ t: string }>(`SELECT ${col} AS t FROM ${CHANGE_TABLE[kind]} WHERE id = ?`, id); if (!row) throw badRequest(`No ${kind} with id ${id}. Use list_materials to get valid ids.`); return row.t; } function describeChange(db: DB, c: Change): string { const title = itemTitle(db, c.kind, c.id); if (c.op === 'delete') return `Delete ${c.kind} "${title}"${c.kind === 'folder' ? ' (its contents stay in the class)' : ''}`; if (c.op === 'rename') { if (!c.title) throw badRequest('rename needs a title'); return `Rename ${c.kind} "${title}" to "${c.title}"`; } if (c.kind === 'folder') throw badRequest('Folders cannot be moved'); const row = db.get<{ class_id: string }>(`SELECT class_id FROM ${CHANGE_TABLE[c.kind]} WHERE id = ?`, c.id)!; const classId = c.class_id ?? row.class_id; const cls = getClass(db, classId); const folder = c.folder_id ? db.get<{ name: string }>('SELECT name FROM folders WHERE id = ? AND class_id = ?', c.folder_id, classId) : null; return `Move ${c.kind} "${title}" to ${cls.name}${folder ? ` / ${folder.name}` : c.folder_id ? '' : ' (no folder)'}`; } function applyChange(app: AppContext, c: Change): void { const { db } = app; const table = CHANGE_TABLE[c.kind]; if (c.op === 'delete') { if (c.kind === 'document') return deleteDocument(app, c.id); db.tx(() => { db.run('DELETE FROM shares WHERE kind = ? AND target_id = ?', c.kind, c.id); if (c.kind === 'quiz') db.run(`DELETE FROM attempts WHERE quiz_id = ? AND status = 'active'`, c.id); db.run(`DELETE FROM ${table} WHERE id = ?`, c.id); }); return; } if (c.op === 'rename') { db.run(`UPDATE ${table} SET ${c.kind === 'folder' ? 'name' : 'title'} = ?, updated_at = ? WHERE id = ?`, c.title ?? '', now(), c.id); return; } const row = db.get<{ class_id: string }>(`SELECT class_id FROM ${table} WHERE id = ?`, c.id); if (!row) return; const classId = c.class_id ?? row.class_id; getClass(db, classId); db.run(`UPDATE ${table} SET class_id = ?, folder_id = ?, updated_at = ? WHERE id = ?`, classId, resolveFolder(db, classId, c.folder_id), now(), c.id); if (c.kind === 'document') db.run('UPDATE chunks SET class_id = ? WHERE document_id = ?', classId, c.id); } /** Runs (or cancels) a change set the assistant proposed, and records the outcome in the conversation for later turns. */ export function resolveAction(app: AppContext, actionId: string, confirm: boolean): { status: string; result: string } { const { db } = app; const row = db.get<{ id: string; conversation_id: string | null; payload: string; status: string; summary: string }>('SELECT * FROM ai_actions WHERE id = ?', actionId); if (!row) throw notFound('Action'); if (row.status !== 'pending') throw badRequest('This request was already answered'); const payload = parseJson<{ changes: Change[]; lines: string[] }>(row.payload, { changes: [], lines: [] }); let status = 'cancelled'; let result = 'Cancelled. Nothing was changed.'; if (confirm) { try { db.tx(() => payload.changes.forEach((c) => applyChange(app, c))); status = 'confirmed'; result = `Done: ${payload.lines.length} change${payload.lines.length === 1 ? '' : 's'} applied.`; } catch (err) { status = 'failed'; result = `Could not apply the changes: ${err instanceof Error ? err.message : 'unknown error'}`; } } db.run('UPDATE ai_actions SET status = ?, result = ?, resolved_at = ? WHERE id = ?', status, result, now(), actionId); if (row.conversation_id) { // A note in the transcript so the model knows what actually happened. const note: ChatMessage = { role: 'user', content: [{ type: 'text', text: `[System note: the user ${confirm ? 'CONFIRMED' : 'DECLINED'} the proposed changes "${row.summary}". Result: ${result}]` }] }; db.run(`INSERT INTO messages (conversation_id, role, content, meta, created_at) VALUES (?, 'user', ?, ?, ?)`, row.conversation_id, JSON.stringify(note), JSON.stringify({ hidden: true }), now()); } return { status, result }; } /* ------------------------------ conversations ------------------------------ */ interface MessageRow { id: number; conversation_id: string; role: string; content: string; meta: string; created_at: number; } interface MessageMeta { hidden?: boolean; toolResults?: boolean; /** Materials tagged in a user message. */ tags?: TaggedItem[]; tools?: ToolActivity[]; ui?: UiItem[]; model?: string; error?: string; } export interface DisplayMessage { id: number; role: 'user' | 'assistant'; text: string; tags?: TaggedItem[]; tools: ToolActivity[]; ui: UiItem[]; model?: string; error?: string; createdAt: number; } /** Collapses the raw model transcript (several steps and tool results per turn) into what the chat UI shows. */ export function displayMessages(db: DB, conversationId: string): DisplayMessage[] { const rows = db.all('SELECT * FROM messages WHERE conversation_id = ? ORDER BY id', conversationId); const out: DisplayMessage[] = []; let current: DisplayMessage | null = null; for (const row of rows) { const meta = parseJson(row.meta, {}); if (meta.hidden || meta.toolResults) continue; const msg = parseJson(row.content, { role: 'user', content: [] }); const text = msg.content.filter((p) => p.type === 'text').map((p) => (p as { text: string }).text).join(''); if (row.role === 'user') { current = null; out.push({ id: row.id, role: 'user', text, tools: [], ui: [], createdAt: row.created_at, ...(meta.tags?.length ? { tags: meta.tags } : {}) }); continue; } if (!current) { current = { id: row.id, role: 'assistant', text: '', tools: [], ui: [], createdAt: row.created_at }; out.push(current); } if (text) current.text += (current.text ? '\n\n' : '') + text; if (meta.tools) current.tools.push(...meta.tools); if (meta.ui) current.ui.push(...meta.ui); if (meta.model) current.model = meta.model; if (meta.error) current.error = meta.error; } // Reflect the live status of drafts and confirmations rather than the status at the time of the message. for (const m of out) { for (const item of m.ui) { if (item.type === 'draft') { const d = db.get<{ status: string; title: string }>('SELECT status, title FROM drafts WHERE id = ?', item.draftId); item.status = d?.status ?? 'discarded'; } else if (item.type === 'action') { const a = db.get<{ status: string; result: string }>('SELECT status, result FROM ai_actions WHERE id = ?', item.actionId); if (a) { item.status = a.status as typeof item.status; item.result = a.result; } } } } return out; } export function listConversations(db: DB) { return db .all<{ id: string; title: string; class_id: string | null; updated_at: number }>('SELECT id, title, class_id, updated_at FROM conversations ORDER BY updated_at DESC LIMIT 100') .map((c) => ({ id: c.id, title: c.title || 'New conversation', classId: c.class_id, updatedAt: c.updated_at })); } function estimateMessageTokens(m: ChatMessage): number { let chars = 0; for (const p of m.content) { if (p.type === 'text') chars += p.text.length; else if (p.type === 'tool_result') chars += p.output.length; else if (p.type === 'tool_call') chars += JSON.stringify(p.input).length + 40; else chars += 4000; } return Math.ceil(chars / 3.6) + 8; } /** Loads the transcript for the model, dropping the oldest whole turns when it would not fit. */ function loadHistory(db: DB, conversationId: string, budgetTokens: number): ChatMessage[] { const rows = db.all('SELECT * FROM messages WHERE conversation_id = ? ORDER BY id', conversationId); const messages = rows.map((r) => ({ msg: parseJson(r.content, { role: 'user', content: [] }), meta: parseJson(r.meta, {}) })).filter((m) => m.msg.content.length > 0); // Turn boundaries: a user message that is not a tool-result carrier. const starts: number[] = []; messages.forEach((m, i) => { if (m.msg.role === 'user' && !m.meta.toolResults) starts.push(i); }); let from = 0; let total = messages.reduce((n, m) => n + estimateMessageTokens(m.msg), 0); for (let s = 1; s < starts.length && total > budgetTokens; s += 1) { for (let i = from; i < starts[s]; i += 1) total -= estimateMessageTokens(messages[i].msg); from = starts[s]; } return messages.slice(from).map((m) => m.msg); } function systemPrompt(app: AppContext, context: AssistantContext): string { const { db } = app; const s = getAppSettings(db, app.config.timezone); const today = new Intl.DateTimeFormat('en-US', { timeZone: s.timezone, dateStyle: 'full' }).format(new Date()); const classes = db.all<{ id: string; name: string; code: string }>('SELECT id, name, code FROM classes WHERE archived = 0 ORDER BY sort_order LIMIT 40'); const lines = [ 'You are the study assistant built into Study Desk, a personal study app used by a nursing student. You help them learn, and you can act on their library through tools.', `Today is ${today}.`, classes.length ? `Their classes:\n${classes.map((c) => `- ${c.name}${c.code ? ` (${c.code})` : ''} — id ${c.id}`).join('\n')}` : 'They have not created any classes yet. Offer to create one with the organize tool when it would help.', ]; if (context.classId) { const cls = db.get<{ name: string }>('SELECT name FROM classes WHERE id = ?', context.classId); if (cls) lines.push(`The user is currently viewing the class "${cls.name}" (id ${context.classId}). Assume requests are about this class unless they say otherwise.`); } if (context.documentIds?.length) { const docs = db.all<{ id: string; title: string }>(`SELECT id, title FROM documents WHERE id IN (${context.documentIds.map(() => '?').join(',')})`, ...context.documentIds); if (docs.length) lines.push(`The user has these documents in focus: ${docs.map((d) => `"${d.title}" (id ${d.id})`).join(', ')}. Questions like "summarise this" refer to them.`); } if (context.items?.length) { const how: Record = { quiz: 'open it with get_quiz', deck: 'open it with get_deck', note: 'read it with read_note', document: 'search it with search_documents or read it with read_document; pass its id as a source when generating', folder: 'list its contents with list_materials', }; lines.push( `In their latest message the user tagged these materials, so "this", "these" and similar words refer to them. Use the ids directly instead of searching for them:\n${context.items .map((i) => `- ${i.kind} "${i.title}" — id ${i.id}${TAG_URL[i.kind] ? `, link ${TAG_URL[i.kind]}${i.id}` : ''} (${how[i.kind]})`) .join('\n')}`, ); } lines.push( `How to work: - Use tools instead of guessing. To answer questions about their material, search or read the documents first and base the answer on what you find. - Cite document passages inline with the ref id in square brackets right after the claim, exactly as given, e.g. [c42]. Only cite refs that a tool returned in this conversation. If the documents do not cover something, say so, then answer from general knowledge and label it as such. - You can browse everything: list_materials and search_library for quizzes, flashcards and notes; get_quiz, get_deck and read_note to open them; search_documents and read_document for uploaded files. - When you mention a specific quiz, deck, note or document, link it with Markdown using the url the tool gave you, for example [Cardiac drug cards](/decks/abc123). Never invent a url. - To create study material, call generate_quiz, generate_flashcards or write_study_guide. They read the source documents themselves, so pass ids and a topic rather than text. Do not search first unless you need to work out which documents are relevant. - Everything you create is a DRAFT shown as a preview card. Never say it was saved or added; tell the user to review and save it. - Deleting, moving and renaming require propose_changes and the user's confirmation. Never claim a change was made before a system note confirms it. - For "what should I study" questions, call get_performance and give specific, prioritised advice. - When a request is clear, act on it without asking for permission. Ask one short question only when a missing detail would change the result (for example which class, when it is ambiguous). - Be concise and concrete. Use Markdown. Teach like a good clinical instructor: explain the why, connect to patient care, and prefer current standard practice. - After a tool produces a draft or a session link, reply with one or two sentences; the card already shows the details. - Use run_python whenever exactness matters: dosage and rate calculations, unit conversions, counting questions, options or correct answers, checking that a quiz meets what was asked for. Quizzes from generate_quiz are already checked this way; when you write questions yourself with create_draft, check the draft with run_python (pass its draft_id) before telling the user it is ready, and fix problems you find.`, ); return lines.join('\n\n'); } export const assistantRequestSchema = z.object({ conversationId: z.string().nullish(), message: z.string().trim().min(1).max(20_000), context: z .object({ classId: z.string().nullish(), documentIds: z.array(z.string()).max(20).optional(), items: z.array(z.object({ kind: z.enum(TAG_KINDS), id: z.string().max(60) })).max(20).optional(), }) .optional(), modelId: z.string().nullish(), }); /** App paths for linking tagged items in answers (folders have no page of their own). */ const TAG_URL: Record = { quiz: '/quizzes/', deck: '/decks/', note: '/notes/', document: '/documents/', folder: '' }; const TAG_TABLE: Record = { quiz: { table: 'quizzes', title: 'title' }, deck: { table: 'decks', title: 'title' }, note: { table: 'notes', title: 'title' }, document: { table: 'documents', title: 'title' }, folder: { table: 'folders', title: 'name' }, }; /** Looks tagged items up so the model (and the transcript) get their real titles; unknown ids are dropped. */ function resolveTags(db: DB, items: { kind: TagKind; id: string }[] | undefined): TaggedItem[] { const out: TaggedItem[] = []; for (const i of items ?? []) { const meta = TAG_TABLE[i.kind]; const row = db.get<{ title: string }>(`SELECT ${meta.title} AS title FROM ${meta.table} WHERE id = ?`, i.id); if (row && !out.some((o) => o.kind === i.kind && o.id === i.id)) out.push({ kind: i.kind, id: i.id, title: row.title }); } return out; } /** Library items the user can tag with @: one class's materials, or a title search across everything. */ export function mentionables(db: DB, opts: { classId?: string | null; q?: string }): (TaggedItem & { className: string; classColor: string; folderName?: string })[] { const q = (opts.q ?? '').trim().slice(0, 80); const like = `%${q.replace(/[\\%_]/g, (m) => `\\${m}`)}%`; const out: (TaggedItem & { className: string; classColor: string; folderName?: string })[] = []; const limit = opts.classId ? 300 : 12; for (const kind of TAG_KINDS) { const meta = TAG_TABLE[kind]; const where = [opts.classId ? 't.class_id = ?' : '1 = 1', q ? `t.${meta.title} LIKE ? ESCAPE '\\'` : '1 = 1']; const params = [...(opts.classId ? [opts.classId] : []), ...(q ? [like] : [])]; const folderJoin = kind === 'folder' ? '' : 'LEFT JOIN folders f ON f.id = t.folder_id'; const folderCol = kind === 'folder' ? "'' AS folder_name" : 'f.name AS folder_name'; const rows = db.all<{ id: string; title: string; class_name: string; class_color: string; folder_name: string | null }>( `SELECT t.id, t.${meta.title} AS title, k.name AS class_name, k.color AS class_color, ${folderCol} FROM ${meta.table} t JOIN classes k ON k.id = t.class_id ${folderJoin} WHERE ${where.join(' AND ')} ${kind === 'document' ? "AND t.status = 'ready'" : ''} ORDER BY t.updated_at DESC LIMIT ?`, ...params, limit, ); for (const r of rows) out.push({ kind, id: r.id, title: r.title, className: r.class_name, classColor: r.class_color, ...(r.folder_name ? { folderName: r.folder_name } : {}) }); } return out; } /* ------------------------------ running turns ------------------------------ */ /** * A turn keeps running on the server when the browser disconnects (the user leaves the * page, closes the drawer, switches to another conversation). Its events are buffered so a * client that comes back can replay them and follow along; only "Stop" cancels it. */ interface LiveTurn { events: AssistantEvent[]; listeners: Set<(event: AssistantEvent) => void>; controller: AbortController; } const live = new Map(); export function isTurnRunning(conversationId: string): boolean { return live.has(conversationId); } /** Replays the running turn's events, then streams the rest. Returns an unsubscribe function, or null when nothing is running. */ export function followTurn(conversationId: string, listener: (event: AssistantEvent) => void): (() => void) | null { const turn = live.get(conversationId); if (!turn) return null; for (const e of turn.events) listener(e); turn.listeners.add(listener); return () => turn.listeners.delete(listener); } export function stopTurn(conversationId: string): boolean { const turn = live.get(conversationId); if (!turn) return false; turn.controller.abort(); return true; } /** * Starts a turn in the background and returns its conversation id at once. Problems that * prevent the turn from starting (no model configured, unknown model, a turn already * running in this conversation) throw here, before anything is saved. */ export function startAssistantTurn(app: AppContext, input: z.input): { conversationId: string } { const req = assistantRequestSchema.parse(input); if (req.conversationId && live.has(req.conversationId)) throw new HttpError(409, 'busy', 'The assistant is still answering in this conversation. Wait for it or press Stop.'); resolveModel(app, 'chat', req.modelId); const controller = new AbortController(); const turn: LiveTurn = { events: [], listeners: new Set(), controller }; let id = ''; const emit = (event: AssistantEvent) => { turn.events.push(event); for (const fn of turn.listeners) fn(event); }; const started = runAssistantTurn(app, req, emit, controller.signal, (conversationId) => { id = conversationId; live.set(conversationId, turn); }); void started .catch((err) => { const ai = err instanceof AIError ? err : null; if (!ai) app.log('error', 'Assistant turn failed', err); emit({ type: 'error', code: ai?.code ?? 'server', message: ai?.message ?? 'The assistant stopped unexpectedly.' }); emit({ type: 'done', conversationId: id, title: '' }); }) .finally(() => { if (id && live.get(id) === turn) live.delete(id); }); if (!id) throw new AIError('server', 'The assistant could not start.'); return { conversationId: id }; } const MAX_STEPS = 12; const TOOL_OUTPUT_LIMIT = 28_000; /** Runs one user turn: model steps and tool calls until the model answers in plain text. */ export async function runAssistantTurn( app: AppContext, input: z.input, emit: (event: AssistantEvent) => void, signal?: AbortSignal, /** Called synchronously, before the first await, with the conversation id. */ onConversation?: (conversationId: string) => void, ): Promise { const { db } = app; const req = assistantRequestSchema.parse(input); const tags = resolveTags(db, req.context?.items); // Tagged documents join the documents in focus so retrieval and generation use them. const taggedDocs = tags.filter((t) => t.kind === 'document').map((t) => t.id); const documentIds = [...new Set([...(req.context?.documentIds ?? []), ...taggedDocs])]; const context: AssistantContext = { classId: req.context?.classId ?? null, documentIds: documentIds.length ? documentIds : undefined, items: tags }; const resolved = resolveModel(app, 'chat', req.modelId); const at = now(); let conversationId = req.conversationId ?? null; let title = ''; if (conversationId) { const row = db.get<{ title: string }>('SELECT title FROM conversations WHERE id = ?', conversationId); if (!row) conversationId = null; else title = row.title; } if (!conversationId) { conversationId = newId(); title = req.message.replace(/\s+/g, ' ').slice(0, 70); db.run('INSERT INTO conversations (id, title, class_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?)', conversationId, title, context.classId && db.get('SELECT id FROM classes WHERE id = ?', context.classId) ? context.classId : null, at, at); } const save = (role: 'user' | 'assistant', message: ChatMessage, meta: MessageMeta = {}) => db.run('INSERT INTO messages (conversation_id, role, content, meta, created_at) VALUES (?, ?, ?, ?, ?)', conversationId, role, JSON.stringify(message), JSON.stringify(meta), now()); save('user', { role: 'user', content: [{ type: 'text', text: req.message }] }, tags.length ? { tags } : {}); db.run('UPDATE conversations SET updated_at = ? WHERE id = ?', now(), conversationId); onConversation?.(conversationId); emit({ type: 'start', conversationId, model: resolved.model.label }); const env: ToolEnv = { app, conversationId, context, signal, modelId: req.modelId }; const tools = resolved.model.capabilities.tools ? TOOLS : []; const system = systemPrompt(app, context) + (tools.length === 0 ? '\n\nNote: the selected model cannot use tools, so you cannot read the library or create drafts in this conversation. Say so if the user asks for that, and suggest choosing a tool-capable model in Settings.' : ''); const window = resolved.model.contextWindow ?? 32_000; const historyBudget = Math.max(6_000, Math.floor(window * 0.6)); try { for (let step = 0; step < MAX_STEPS; step += 1) { if (signal?.aborted) throw new AIError('aborted', 'Stopped.'); const result = await runChat(app, { task: 'chat', purpose: 'assistant', modelId: req.modelId, system, messages: loadHistory(db, conversationId, historyBudget), tools: tools.map((t) => t.def), toolChoice: tools.length ? (step === MAX_STEPS - 1 ? 'none' : 'auto') : undefined, signal, onEvent: (e) => { if (e.type === 'text') emit({ type: 'text', delta: e.delta }); else if (e.type === 'reasoning') emit({ type: 'reasoning', delta: e.delta }); }, }); const calls = result.message.content.filter((p): p is Extract => p.type === 'tool_call'); const activities: ToolActivity[] = []; const ui: UiItem[] = []; const results: ContentPart[] = []; for (const call of calls) { const spec = TOOLS.find((t) => t.def.name === call.name); const activity: ToolActivity = { id: call.id, name: call.name, label: spec ? spec.label(call.input) : call.name, status: 'running' }; emit({ type: 'tool', tool: { ...activity } }); let output: string; let isError = false; try { if (!spec) throw badRequest(`Unknown tool "${call.name}"`); const run = await spec.run(call.input, env); output = typeof run.output === 'string' ? run.output : JSON.stringify(run.output); activity.status = 'done'; activity.summary = run.summary; for (const item of run.ui ?? []) { ui.push(item); emit({ type: 'ui', item }); } } catch (err) { if (err instanceof AIError && err.code === 'aborted') throw err; isError = true; const message = err instanceof z.ZodError ? err.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ') : err instanceof Error ? err.message : 'Tool failed'; output = JSON.stringify({ error: message }); activity.status = 'error'; activity.summary = clip(message, 160); if (!(err instanceof Error && ('status' in err || err instanceof AIError || err instanceof z.ZodError))) app.log('error', `Assistant tool ${call.name} failed`, err); } if (output.length > TOOL_OUTPUT_LIMIT) output = `${output.slice(0, TOOL_OUTPUT_LIMIT)}… [truncated: ask for a smaller range]`; results.push({ type: 'tool_result', toolCallId: call.id, name: call.name, output, isError }); activities.push(activity); emit({ type: 'tool', tool: { ...activity } }); } save('assistant', result.message, { tools: activities, ui, model: resolved.model.label }); if (calls.length === 0) { if (result.stopReason === 'max_tokens') emit({ type: 'text', delta: '\n\n*(The reply was cut off by the output limit. Ask me to continue.)*' }); if (result.stopReason === 'refusal' && !result.text) emit({ type: 'text', delta: 'I can\'t help with that request.' }); break; } save('user', { role: 'user', content: results }, { toolResults: true }); } } catch (err) { const ai = err instanceof AIError ? err : null; if (ai?.code === 'aborted') { save('assistant', { role: 'assistant', content: [{ type: 'text', text: '*(Stopped.)*' }] }, { model: resolved.model.label }); } else { const message = ai?.message ?? (err instanceof Error && 'status' in err ? err.message : 'Something went wrong while talking to the AI model.'); if (!ai && !(err instanceof Error && 'status' in err)) app.log('error', 'Assistant turn failed', err); // Close any dangling tool calls so the transcript stays valid for the next turn. repairTranscript(db, conversationId); save('assistant', { role: 'assistant', content: [{ type: 'text', text: '' }] }, { error: message, model: resolved.model.label }); emit({ type: 'error', message, code: ai?.code ?? 'server', detail: ai?.providerMessage }); } } if (signal?.aborted) repairTranscript(db, conversationId); db.run('UPDATE conversations SET updated_at = ? WHERE id = ?', now(), conversationId); emit({ type: 'done', conversationId, title }); } /** If the last assistant message has tool calls without results (error or abort mid-step), append synthetic results. */ function repairTranscript(db: DB, conversationId: string): void { const last = db.get('SELECT * FROM messages WHERE conversation_id = ? ORDER BY id DESC LIMIT 1', conversationId); if (!last || last.role !== 'assistant') return; const msg = parseJson(last.content, { role: 'assistant', content: [] }); const calls = msg.content.filter((p): p is Extract => p.type === 'tool_call'); if (calls.length === 0) return; const results: ContentPart[] = calls.map((c) => ({ type: 'tool_result', toolCallId: c.id, name: c.name, output: JSON.stringify({ error: 'Interrupted before this tool finished.' }), isError: true })); db.run(`INSERT INTO messages (conversation_id, role, content, meta, created_at) VALUES (?, 'user', ?, ?, ?)`, conversationId, JSON.stringify({ role: 'user', content: results }), JSON.stringify({ toolResults: true }), now()); } export function assistantToolNames(): string[] { return TOOLS.map((t) => t.def.name); } /** Exposed for tests: run one tool directly. */ export async function runToolForTest(app: AppContext, name: string, input: Record, context: AssistantContext = {}): Promise { const spec = TOOLS.find((t) => t.def.name === name); if (!spec) throw new Error(`no tool ${name}`); const conversationId = newId(); app.db.run('INSERT INTO conversations (id, title, created_at, updated_at) VALUES (?, ?, ?, ?)', conversationId, 'test', now(), now()); return spec.run(input, { app, conversationId, context }); } export { getDraft };