Study/server/ai/assistant.ts
Elijah f0aabe4d5d
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m2s
First revision: DeepSeek, numeric questions, background assistant, UI fixes
Providers and pricing
- Add a DeepSeek provider: thinking mode with low/high/max effort, reasoning_content
  replayed between tool steps, cache-hit usage, /models discovery and catalog prices.
- Fix "does not support tool calling": a rejected forced tool_choice (DeepSeek thinking
  mode) now asks for the call in the prompt; only a genuine no-tools 400 is "unsupported".
- Seven reasoning-effort levels (Off to Max) mapped per adapter.
- Cached-input price per model, cache-write and DeepSeek off-peak aware cost estimates.
- Built-in bge-small embedding model (transformers.js) as the semantic search default.

Quizzes
- Numeric (type-the-answer) questions: units ignored, optional ± tolerance; editor,
  runner, importer, templates and generation prompts.
- Quiz start screen instead of showing answers; navigator ring no longer clipped and
  key legend removed; clock only for timed exams; 7-point letter grades.

Assistant and generation
- Assistant turns run on the server independently of the browser, with re-attach and
  an explicit stop; drafts tray shows generations in progress.
- Per-chat model switcher, @-tagging of class materials, full-width assistant page and
  a smaller assistant button.
- Editable generation instructions and built-in presets, separate from the chatbot
  import instructions.

Other
- Dialog footer padding, keyboard hints removed, copy buttons work over plain HTTP,
  class and folder shares include documents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 12:48:17 -07:00

1186 lines
63 KiB
TypeScript

/**
* 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 { resolveModel, runChat } from './service.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, unknown>) => string;
run: (input: Record<string, any>, env: ToolEnv) => Promise<ToolRun> | ToolRun;
}
interface ToolEnv {
app: AppContext;
conversationId: string;
context: AssistantContext;
signal?: AbortSignal;
modelId?: string | null;
}
const obj = (properties: Record<string, unknown>, 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<string, unknown>): Promise<ToolRun> {
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<Record<string, any>>(
`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 = <T>(sql: string) => db.all<T>(sql, classId);
const quizzes = q<Record<string, any>>(`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<Record<string, any>>(`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<Record<string, any>>(`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<Record<string, any>>(`SELECT id, title, folder_id FROM notes WHERE class_id = ? ORDER BY sort_order`);
const folders = q<Record<string, any>>(`SELECT id, name FROM folders WHERE class_id = ? ORDER BY sort_order`);
const withUrl = (rows: Record<string, any>[], 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<Record<string, any>>('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<Record<string, any>>(
`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<Record<string, any>>(
`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<string, string> = { quiz: 'quizzes', deck: 'decks', note: 'notes', document: 'documents' };
const titles = [
...db.all<Record<string, any>>(`SELECT 'quiz' AS kind, z.id, z.title FROM quizzes z WHERE z.title LIKE ? ESCAPE '\\' ${cls} LIMIT 8`, like, ...p),
...db.all<Record<string, any>>(`SELECT 'deck' AS kind, z.id, z.title FROM decks z WHERE z.title LIKE ? ESCAPE '\\' ${cls} LIMIT 8`, like, ...p),
...db.all<Record<string, any>>(`SELECT 'note' AS kind, z.id, z.title FROM notes z WHERE z.title LIKE ? ESCAPE '\\' ${cls} LIMIT 8`, like, ...p),
...db.all<Record<string, any>>(`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<Record<string, any>>(`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<Record<string, any>>(
`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: '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<typeof changesSchema>[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<MessageRow>('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<MessageMeta>(row.meta, {});
if (meta.hidden || meta.toolResults) continue;
const msg = parseJson<ChatMessage>(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<MessageRow>('SELECT * FROM messages WHERE conversation_id = ? ORDER BY id', conversationId);
const messages = rows.map((r) => ({ msg: parseJson<ChatMessage>(r.content, { role: 'user', content: [] }), meta: parseJson<MessageMeta>(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<TagKind, string> = {
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.`,
);
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<TagKind, string> = { quiz: '/quizzes/', deck: '/decks/', note: '/notes/', document: '/documents/', folder: '' };
const TAG_TABLE: Record<TagKind, { table: string; title: string }> = {
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<string, LiveTurn>();
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<typeof assistantRequestSchema>): { 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<typeof assistantRequestSchema>,
emit: (event: AssistantEvent) => void,
signal?: AbortSignal,
/** Called synchronously, before the first await, with the conversation id. */
onConversation?: (conversationId: string) => void,
): Promise<void> {
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<ContentPart, { type: 'tool_call' }> => 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<MessageRow>('SELECT * FROM messages WHERE conversation_id = ? ORDER BY id DESC LIMIT 1', conversationId);
if (!last || last.role !== 'assistant') return;
const msg = parseJson<ChatMessage>(last.content, { role: 'assistant', content: [] });
const calls = msg.content.filter((p): p is Extract<ContentPart, { type: 'tool_call' }> => 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<string, unknown>, context: AssistantContext = {}): Promise<ToolRun> {
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 };