All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m0s
- Built-in Parallel web search (keyless; optional sign-in for higher limits and research) with its own settings page; OAuth sign-in (RFC 9728/8414/7591, PKCE, RFC 8707) for any MCP server, with token refresh and pre-registered client support - Friendly tool steps (icon, name, status; details on click) and ids stripped from results; per-chat tool switches; taller thinking box - Exams within classes: exam tabs, scoped lists, uploads, imports and Generate; exam-only material for generation; class setting for what the groups are called - Assistant can ask clarifying questions in an inline form before generating - OpenUI blocks (charts, questions, flashcards, inputs) in assistant, Explain and share chats - Explain beside the quiz on wide screens, grounded in the cited source pages - Quiz results: percentage ring coloured by score band, rainbow at 100 - Share links: assistant button like the owner's, hidden during quizzes; documents readable in the browser - Live draft and library updates over server-sent events Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1406 lines
77 KiB
TypeScript
1406 lines
77 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 { clipOutput, mcpActivity, type ToolActivity } from './activity.ts';
|
|
import { genUiPrompt } from './genui.ts';
|
|
import { loadMcpTools, mcpPromptNote, type WebSource } from './mcp.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 }
|
|
/** Clarifying questions shown as an inline form; the user's answers arrive as the next message. */
|
|
| { type: 'questions'; id: string; intro?: string; questions: AskQuestion[] };
|
|
|
|
export interface AskQuestion {
|
|
id: string;
|
|
question: string;
|
|
/** 'choice' shows options (one or several), 'text' and 'number' a field. Choices also take a typed answer. */
|
|
input: 'choice' | 'text' | 'number';
|
|
options?: { label: string; description?: string }[];
|
|
multi?: boolean;
|
|
/** Labels pre-selected (choice) or the prefilled value (text, number). */
|
|
defaults?: string[];
|
|
placeholder?: string;
|
|
}
|
|
|
|
export type { ToolActivity } from './activity.ts';
|
|
|
|
export type AssistantEvent =
|
|
| { type: 'start'; conversationId: string; model: string }
|
|
| { type: 'text'; delta: string }
|
|
| { type: 'reasoning'; delta: string }
|
|
/** A new model step begins (after tool results): text that follows is a new paragraph. */
|
|
| { type: 'step' }
|
|
| { 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;
|
|
/** The exam (folder) of that class the user is viewing. */
|
|
folderId?: 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[];
|
|
sources?: WebSource[];
|
|
/** The turn ends after this step: the model waits for the user (ask_user). */
|
|
endTurn?: boolean;
|
|
}
|
|
|
|
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;
|
|
}
|
|
|
|
/** The exam (folder) to work in: the one named, else the one in view when it belongs to the class. */
|
|
function examIdOr(env: ToolEnv, classGiven: unknown, given: unknown): string | undefined {
|
|
const classId = classIdOr(env, classGiven);
|
|
const id = (typeof given === 'string' && given) || env.context.folderId || undefined;
|
|
if (!id || !classId) return undefined;
|
|
const folder = env.app.db.get<{ class_id: string }>('SELECT class_id FROM folders WHERE id = ?', id);
|
|
if (!folder) {
|
|
if (typeof given === 'string' && given) throw badRequest(`No exam with id ${given}. Use the exam ids listed in the system prompt or list_materials.`);
|
|
return undefined;
|
|
}
|
|
return folder.class_id === classId ? id : 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.' },
|
|
exam_id: { ...S, description: 'Limit to one exam (folder) of the class.' },
|
|
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 examId = typeof input.exam_id === 'string' && input.exam_id ? input.exam_id : undefined;
|
|
const examDocs = examId ? env.app.db.all<{ id: string }>(`SELECT id FROM documents WHERE folder_id = ? AND status = 'ready'`, examId).map((d) => d.id) : [];
|
|
const docIds = (Array.isArray(input.document_ids) && input.document_ids.length ? input.document_ids : examDocs.length ? examDocs : 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, or 50 for an exam.' },
|
|
format: { type: 'string', enum: ['practice', 'exam'], description: 'exam = a full practice exam (50 questions by default, at most 5 calculations). Use it when the user asks for an exam or test.' },
|
|
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, or in the exam when there is an exam_id.' },
|
|
exam_id: { ...S, description: 'Exam (folder) id: uses only the documents of that exam and saves the draft into it. Defaults to the exam the user is viewing.' },
|
|
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 ?? (i.format === 'exam' ? 50 : 15)} quiz questions`,
|
|
run: (input, env) =>
|
|
runGenerate(env, {
|
|
kind: 'quiz',
|
|
classId: requireClass(env, input.class_id),
|
|
folderId: examIdOr(env, input.class_id, input.exam_id),
|
|
title: input.title || undefined,
|
|
focus: input.topic || undefined,
|
|
count: Math.max(1, Math.min(100, Number(input.count) || (input.format === 'exam' ? 50 : 15))),
|
|
format: input.format === 'exam' ? 'exam' : 'practice',
|
|
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', description: 'Use every document in the class, or in the exam when there is an exam_id.' },
|
|
exam_id: { ...S, description: 'Exam (folder) id: uses only the documents of that exam and saves the draft into it. Defaults to the exam the user is viewing.' },
|
|
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),
|
|
folderId: examIdOr(env, input.class_id, input.exam_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', description: 'Use every document in the class, or in the exam when there is an exam_id.' },
|
|
exam_id: { ...S, description: 'Exam (folder) id: uses only the documents of that exam and saves the draft into it. Defaults to the exam the user is viewing.' },
|
|
instructions: S,
|
|
},
|
|
[],
|
|
),
|
|
},
|
|
label: () => 'Writing a study guide',
|
|
run: (input, env) =>
|
|
runGenerate(env, {
|
|
kind: 'note',
|
|
classId: requireClass(env, input.class_id),
|
|
folderId: examIdOr(env, input.class_id, input.exam_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<string, unknown> = {};
|
|
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' }],
|
|
};
|
|
},
|
|
},
|
|
{
|
|
def: {
|
|
name: 'ask_user',
|
|
description:
|
|
"Ask the user up to 4 short clarifying questions BEFORE doing the work, when a detail that changes the result is missing: which exam or materials to use, how many questions or cards, the difficulty or focus. They appear as a small inline form with your options; your turn ends and the answers arrive as the user's next message. Offer concrete options (the class's exams, its documents by title, sensible counts) with the usual choice first and in `defaults`. Do not ask what the user already said or what is clear from context, ask at most once per request, and do not write the answer in the same turn.",
|
|
parameters: obj(
|
|
{
|
|
intro: { ...S, description: 'Optional: one short sentence shown above the questions.' },
|
|
questions: {
|
|
type: 'array',
|
|
minItems: 1,
|
|
maxItems: 4,
|
|
items: obj(
|
|
{
|
|
id: { ...S, description: 'Short key, e.g. "exam", "count".' },
|
|
question: { ...S, description: 'The question, e.g. "Which exam is this for?"' },
|
|
input: { type: 'string', enum: ['choice', 'text', 'number'], description: 'choice (default when options are given), text or number.' },
|
|
options: { type: 'array', maxItems: 12, items: obj({ label: S, description: { ...S, description: 'Optional short hint.' } }, ['label']) },
|
|
multi: { type: 'boolean', description: 'Several options may be chosen (e.g. materials).' },
|
|
defaults: { type: 'array', items: S, description: 'Option labels selected at first, or the prefilled value.' },
|
|
placeholder: S,
|
|
},
|
|
['question'],
|
|
),
|
|
},
|
|
},
|
|
['questions'],
|
|
),
|
|
},
|
|
label: () => 'Asking you a few questions',
|
|
run: (input) => {
|
|
const parsed = askSchema.parse(input);
|
|
const questions: AskQuestion[] = parsed.questions.map((q, i) => ({
|
|
id: q.id || `q${i + 1}`,
|
|
question: q.question,
|
|
input: q.options?.length ? (q.input === 'text' || q.input === 'number' ? q.input : 'choice') : q.input === 'number' ? 'number' : 'text',
|
|
options: q.options?.length ? q.options : undefined,
|
|
multi: q.multi || undefined,
|
|
defaults: q.defaults?.length ? q.defaults : undefined,
|
|
placeholder: q.placeholder || undefined,
|
|
}));
|
|
return {
|
|
output: { status: 'waiting_for_answers', important: "The questions are shown to the user. Stop now and wait: their answers arrive as the next message. Don't guess the answers or start the work." },
|
|
summary: `${questions.length} question${questions.length === 1 ? '' : 's'}`,
|
|
ui: [{ type: 'questions', id: newId(), intro: parsed.intro || undefined, questions }],
|
|
endTurn: true,
|
|
};
|
|
},
|
|
},
|
|
];
|
|
|
|
const askSchema = z.object({
|
|
intro: z.string().trim().max(300).nullish(),
|
|
questions: z
|
|
.array(
|
|
z.object({
|
|
id: z.string().trim().max(40).nullish(),
|
|
question: z.string().trim().min(1).max(300),
|
|
input: z.enum(['choice', 'text', 'number']).nullish(),
|
|
options: z.array(z.object({ label: z.string().trim().min(1).max(160), description: z.string().trim().max(200).nullish().transform((v) => v || undefined) })).max(12).nullish(),
|
|
multi: z.boolean().nullish(),
|
|
defaults: z.array(z.string().max(160)).max(12).nullish(),
|
|
placeholder: z.string().max(120).nullish(),
|
|
}),
|
|
)
|
|
.min(1)
|
|
.max(4),
|
|
});
|
|
|
|
/* ------------------------------ 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;
|
|
/** The model's reasoning text for this step, when it shows any (kept for the "Thinking" view). */
|
|
reasoning?: string;
|
|
}
|
|
|
|
/** The order things happened in one assistant reply: text, tool steps and cards interleaved. */
|
|
export type MessagePart = { kind: 'text'; text: string } | { kind: 'tool'; id: string } | { kind: 'ui'; index: number };
|
|
|
|
export interface DisplayMessage {
|
|
id: number;
|
|
role: 'user' | 'assistant';
|
|
text: string;
|
|
tags?: TaggedItem[];
|
|
tools: ToolActivity[];
|
|
ui: UiItem[];
|
|
parts?: MessagePart[];
|
|
reasoning?: string;
|
|
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: [], parts: [], createdAt: row.created_at };
|
|
out.push(current);
|
|
}
|
|
const parts = current.parts!;
|
|
// Within one step the model writes its text first, then calls tools; cards come from the tools.
|
|
if (text) {
|
|
current.text += (current.text ? '\n\n' : '') + text;
|
|
parts.push({ kind: 'text', text });
|
|
}
|
|
if (meta.tools) {
|
|
current.tools.push(...meta.tools);
|
|
for (const t of meta.tools) parts.push({ kind: 'tool', id: t.id });
|
|
}
|
|
if (meta.ui) {
|
|
for (const u of meta.ui) parts.push({ kind: 'ui', index: current.ui.length + meta.ui.indexOf(u) });
|
|
current.ui.push(...meta.ui);
|
|
}
|
|
if (meta.reasoning) current.reasoning = `${current.reasoning ? `${current.reasoning}\n\n` : ''}${meta.reasoning}`;
|
|
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];
|
|
}
|
|
const out: ChatMessage[] = [];
|
|
for (const m of messages.slice(from)) {
|
|
const prev = out[out.length - 1];
|
|
// A turn that ended waiting for the user (ask_user) leaves tool results right before the
|
|
// user's answer: send them as one user message, which every provider accepts.
|
|
if (prev && prev.role === 'user' && m.msg.role === 'user' && prev.content.every((p) => p.type === 'tool_result')) out[out.length - 1] = { role: 'user', content: [...prev.content, ...m.msg.content] };
|
|
else out.push(m.msg);
|
|
}
|
|
return out;
|
|
}
|
|
|
|
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.',
|
|
];
|
|
lines.push(
|
|
"Clarifying questions: when a request to generate a quiz, flashcards or a study guide leaves out something that changes the result (which exam or which materials when the class has several, how many questions or cards), call ask_user once with those questions and concrete options, then stop. Don't ask when the user already said it, when the page in view makes it clear, or when they asked you to just go ahead; then use sensible defaults and say which you used.",
|
|
);
|
|
if (context.classId) {
|
|
const cls = db.get<{ name: string; group_label: string }>('SELECT name, group_label 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.`);
|
|
const label = (cls.group_label || 'Exam').toLowerCase();
|
|
const exams = db.all<{ id: string; name: string; docs: number }>(
|
|
`SELECT f.id, f.name, (SELECT COUNT(*) FROM documents d WHERE d.folder_id = f.id AND d.status = 'ready') AS docs FROM folders f WHERE f.class_id = ? ORDER BY f.sort_order, f.created_at LIMIT 30`,
|
|
context.classId,
|
|
);
|
|
if (exams.length) {
|
|
lines.push(
|
|
`This class is divided into ${label}s, each with its own documents, quizzes and flashcards:\n${exams.map((e) => `- ${e.name} — exam_id ${e.id} (${e.docs} document${e.docs === 1 ? '' : 's'})`).join('\n')}\nMaterial for one ${label} must come only from that ${label}'s documents: pass its exam_id when generating or searching.`,
|
|
);
|
|
}
|
|
const current = context.folderId ? exams.find((e) => e.id === context.folderId) : undefined;
|
|
if (current) lines.push(`They are looking at "${current.name}" (exam_id ${current.id}). Use it unless they name another ${label}.`);
|
|
}
|
|
}
|
|
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.
|
|
- Talk while you work, like a person would: before a tool call that does real work (generating, checking, searching several places), first say in one short sentence what you are about to do ("I'll write 20 questions from the lecture, then check them with Python."), then call the tool in the same reply. After each step, say briefly what happened before the next one.
|
|
- After a tool produces a draft or a session link, reply with one or two sentences; the card already shows the details.
|
|
- Never mention tool names, ids (draft, search, extract or session ids) or raw tool output to the user. The app already shows each step as it happens; just say what you did and what you found.
|
|
- 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(),
|
|
folderId: 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(),
|
|
/** Tool sources (web search, MCP servers) switched off for this conversation. Saved with it. */
|
|
toolsOff: z.array(z.string().max(60)).max(40).optional(),
|
|
});
|
|
|
|
/** 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, folderId: req.context?.folderId ?? 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 = '';
|
|
let toolsOff: string[] = req.toolsOff ?? [];
|
|
if (conversationId) {
|
|
const row = db.get<{ title: string; settings: string }>('SELECT title, settings FROM conversations WHERE id = ?', conversationId);
|
|
if (!row) conversationId = null;
|
|
else {
|
|
title = row.title;
|
|
if (!req.toolsOff) toolsOff = parseJson<{ toolsOff?: string[] }>(row.settings, {}).toolsOff ?? [];
|
|
}
|
|
}
|
|
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 = ?, settings = ? WHERE id = ?', now(), JSON.stringify({ toolsOff }), conversationId);
|
|
onConversation?.(conversationId);
|
|
emit({ type: 'start', conversationId, model: resolved.model.label });
|
|
|
|
const env: ToolEnv = { app, conversationId, context, signal, modelId: req.modelId };
|
|
// Tools from the user's MCP servers join the built-in ones for this turn.
|
|
const mcp = resolved.model.capabilities.tools ? await loadMcpTools(app, 'chat', signal, { exclude: toolsOff }) : { tools: [], servers: [], unavailable: [] };
|
|
const mcpByName = new Map(mcp.tools.map((b) => [b.def.name, b]));
|
|
const mcpSpecs: ToolSpec[] = mcp.tools.map((b) => ({
|
|
def: b.def,
|
|
label: (input) => mcpActivity(b, '', input).label,
|
|
run: async (input, e) => {
|
|
const result = await b.call(input, e.signal);
|
|
return { output: result.text, sources: result.sources };
|
|
},
|
|
}));
|
|
const tools = resolved.model.capabilities.tools ? [...TOOLS, ...mcpSpecs] : [];
|
|
const system =
|
|
systemPrompt(app, context) +
|
|
mcpPromptNote(mcp) +
|
|
genUiPrompt() +
|
|
(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.');
|
|
let stepReasoning = '';
|
|
if (step > 0) emit({ type: 'step' });
|
|
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') {
|
|
stepReasoning += e.delta;
|
|
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[] = [];
|
|
let endTurn = false;
|
|
|
|
for (const call of calls) {
|
|
const spec = tools.find((t) => t.def.name === call.name);
|
|
const binding = mcpByName.get(call.name);
|
|
const activity: ToolActivity = binding
|
|
? mcpActivity(binding, call.id, call.input)
|
|
: { id: call.id, name: call.name, label: spec ? spec.label(call.input) : call.name, status: 'running', kind: 'tool', input: clip(JSON.stringify(call.input ?? {}, null, 2), 2000) };
|
|
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;
|
|
activity.sources = run.sources;
|
|
activity.output = clipOutput(output);
|
|
if (run.endTurn) endTurn = true;
|
|
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, ...(stepReasoning ? { reasoning: stepReasoning.slice(-20_000) } : {}) });
|
|
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 });
|
|
// The model asked the user something: wait for the answers in the next message.
|
|
if (endTurn) break;
|
|
}
|
|
} 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 };
|