Third revision: web search, MCP sign-in, exams, intelligent UI, clarifying questions
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>
This commit is contained in:
Elijah 2026-11-15 20:30:00 -07:00
parent 60cf2322f7
commit c595e0ff2c
54 changed files with 4710 additions and 387 deletions

View file

@ -19,7 +19,24 @@ import {
startImprove,
updateDraftPayload,
} from '../ai/generate.ts';
import { deleteMcpServer, listMcpServers, mcpServerInputSchema, mcpServerPatchSchema, saveMcpServer, testMcpServer } from '../ai/mcp.ts';
import {
deleteMcpServer,
finishMcpOAuth,
getWebSearch,
listChatSources,
listMcpServers,
mcpServerInputSchema,
mcpServerPatchSchema,
saveMcpServer,
saveWebSearch,
signOutMcp,
startMcpOAuth,
testMcpServer,
WEB_SEARCH_ID,
webSearchPatchSchema,
} from '../ai/mcp.ts';
import type { ToolActivity } from '../ai/activity.ts';
import { genUiPrompt } from '../ai/genui.ts';
import { CATALOG_UPDATED, listAdapterMeta } from '../ai/providers/index.ts';
import {
addManualModel,
@ -43,12 +60,21 @@ import {
usageSummary,
} from '../ai/service.ts';
import { embedTexts, embeddingSettingsSchema, getEmbeddingSettings, embeddingStatus, rebuildIndex, saveEmbeddingSettings, scheduleIndexing } from '../services/semantic.ts';
import { EXPLAIN_SYSTEM, explainPrompt } from '../ai/explain.ts';
import { citedPassages, citedPassagesPrompt, EXPLAIN_SYSTEM, explainPrompt } from '../ai/explain.ts';
import { AIError } from '../ai/types.ts';
import { badRequest, HttpError, idParam, notFound, readBody, type AppContext } from '../http.ts';
import { parseJson } from '../util.ts';
type Emit<T> = (event: T) => void;
/** Events of an explanation stream (owner and share links). */
export type ExplainEvent = { type: 'text'; delta: string } | { type: 'tool'; tool: ToolActivity } | { type: 'error'; message: string; code: string } | { type: 'done' };
/** A finished step that shows which source pages the explanation read. */
export function sourceActivity(sources: { label: string }[]): ToolActivity {
return { id: 'sources', name: 'read_sources', label: `Read your source: ${sources.map((s) => s.label).join('; ')}`, status: 'done', kind: 'tool', subject: sources.map((s) => s.label).join('; ') };
}
/** Server-sent events with ordered writes, keep-alive pings and abort propagation. */
export function sse<T extends { type: string }>(c: Context, run: (emit: Emit<T>, signal: AbortSignal) => Promise<void>) {
c.header('X-Accel-Buffering', 'no');
@ -142,6 +168,42 @@ export function aiRoutes(app: AppContext): Hono {
});
r.post('/ai/mcp/:id/test', async (c) => c.json({ result: await testMcpServer(app, idParam(c)) }));
/*
* OAuth sign-in for MCP servers (and the web search). The browser is sent to the server's
* sign-in page and comes back to the callback, which stores the tokens and returns to Settings.
*/
const oauthStartSchema = z.object({
origin: z.string().url().max(300).refine((u) => /^https?:\/\/[^/]+$/i.test(u.replace(/\/+$/, '')), 'Expected the app origin'),
returnTo: z.string().max(200).regex(/^\/[A-Za-z0-9/_-]*$/).optional(),
});
r.post('/ai/mcp/:id/oauth/start', async (c) => {
const body = await readBody(c, oauthStartSchema);
const url = await startMcpOAuth(app, idParam(c), body.origin, body.returnTo ?? '/settings/ai');
return c.json({ url });
});
r.get('/ai/mcp/oauth/callback', async (c) => {
const state = c.req.query('state') ?? '';
const code = c.req.query('code') ?? '';
const back = (returnTo: string, outcome: 'ok' | 'error', message: string) => c.redirect(`${returnTo}?mcp_oauth=${outcome}&message=${encodeURIComponent(message.slice(0, 200))}`, 302);
if (c.req.query('error')) return back('/settings/ai', 'error', c.req.query('error_description') || 'The sign-in was cancelled.');
try {
const done = await finishMcpOAuth(app, state, code);
return back(done.returnTo, 'ok', `Signed in to ${done.name}.`);
} catch (err) {
app.log('warn', 'MCP sign-in failed', err instanceof Error ? err.message : err);
return back('/settings/ai', 'error', err instanceof Error ? err.message : 'The sign-in failed.');
}
});
r.delete('/ai/mcp/:id/oauth', (c) => c.json({ server: signOutMcp(app, idParam(c)) }));
// The built-in web search.
r.get('/ai/web-search', (c) => c.json({ webSearch: getWebSearch(app) }));
r.patch('/ai/web-search', async (c) => c.json({ webSearch: saveWebSearch(app, await readBody(c, webSearchPatchSchema)) }));
r.post('/ai/web-search/test', async (c) => c.json({ result: await testMcpServer(app, WEB_SEARCH_ID), webSearch: getWebSearch(app) }));
/** Tool sources the chat may use, for the per-conversation switches. */
r.get('/ai/chat-tools', (c) => c.json({ sources: listChatSources(app) }));
r.get('/ai/models', (c) => c.json({ models: listModels(db) }));
r.post('/ai/models', async (c) => c.json({ model: addManualModel(app, await readBody(c, manualModelSchema)) }, 201));
r.patch('/ai/models/:id', async (c) => c.json({ model: patchModel(db, idParam(c), await readBody(c, modelPatchSchema)) }));
@ -256,9 +318,10 @@ export function aiRoutes(app: AppContext): Hono {
r.get('/ai/conversations/:id', (c) => {
const id = idParam(c);
const row = db.get<{ id: string; title: string; class_id: string | null }>('SELECT id, title, class_id FROM conversations WHERE id = ?', id);
const row = db.get<{ id: string; title: string; class_id: string | null; settings: string }>('SELECT id, title, class_id, settings FROM conversations WHERE id = ?', id);
if (!row) throw notFound('Conversation');
return c.json({ conversation: { id: row.id, title: row.title, classId: row.class_id, running: isTurnRunning(id) }, messages: displayMessages(db, id) });
const settings = parseJson<{ toolsOff?: string[] }>(row.settings, {});
return c.json({ conversation: { id: row.id, title: row.title, classId: row.class_id, running: isTurnRunning(id), toolsOff: settings.toolsOff ?? [] }, messages: displayMessages(db, id) });
});
r.delete('/ai/conversations/:id', (c) => {
@ -282,6 +345,8 @@ export function aiRoutes(app: AppContext): Hono {
selected: z.array(z.string().max(4000)).max(12).optional(),
rationale: z.string().max(20000).optional(),
ask: z.string().max(2000).optional(),
/** The quiz the question belongs to, to find the documents its rationale cites. */
quizId: z.string().max(64).optional(),
}),
z.object({ kind: z.literal('card'), front: z.string().max(20000), back: z.string().max(20000), ask: z.string().max(2000).optional() }),
z.object({ kind: z.literal('text'), text: z.string().max(40000), ask: z.string().max(2000).optional() }),
@ -291,17 +356,25 @@ export function aiRoutes(app: AppContext): Hono {
const body = await readBody(c, explainSchema);
const prompt = explainPrompt(body);
if (!prompt.trim()) throw badRequest('Nothing to explain');
return sse<{ type: 'text'; delta: string } | { type: 'error'; message: string; code: string } | { type: 'done' }>(c, async (emit, signal) => {
// The pages the rationale cites ("Source: Seizures, pp. 8-9"), from the quiz's class first.
let sources: ReturnType<typeof citedPassages> = [];
if (body.kind === 'question' && body.rationale) {
const classId = body.quizId ? db.get<{ class_id: string }>('SELECT class_id FROM quizzes WHERE id = ?', body.quizId)?.class_id : undefined;
sources = citedPassages(db, body.rationale, { classIds: classId ? [classId] : undefined, stem: body.stem });
if (!sources.length && classId) sources = citedPassages(db, body.rationale, { stem: body.stem });
}
return sse<ExplainEvent>(c, async (emit, signal) => {
try {
let wrote = false;
if (sources.length) emit({ type: 'tool', tool: sourceActivity(sources) });
await runChatWithMcp(
app,
{
task: 'quick',
purpose: 'explanation',
system: EXPLAIN_SYSTEM,
messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
maxOutputTokens: 1500,
system: EXPLAIN_SYSTEM + genUiPrompt(),
messages: [{ role: 'user', content: [{ type: 'text', text: prompt + citedPassagesPrompt(sources) }] }],
maxOutputTokens: 2500,
signal,
onEvent: (e) => {
if (e.type !== 'text') return;
@ -311,10 +384,11 @@ export function aiRoutes(app: AppContext): Hono {
},
'explain',
{
// Text before a tool call ends its paragraph.
onTool: () => {
if (wrote) emit({ type: 'text', delta: '\n\n' });
onTool: (tool) => {
// Text before a tool call ends its paragraph.
if (tool.status === 'running' && wrote) emit({ type: 'text', delta: '\n\n' });
wrote = false;
emit({ type: 'tool', tool });
},
},
);

22
server/routes/events.ts Normal file
View file

@ -0,0 +1,22 @@
import type { Context } from 'hono';
import { streamSSE } from 'hono/streaming';
import { onChange, type ChangeTopic } from '../services/events.ts';
/** GET /api/events: a long-lived stream of `{type: 'change', topics}` messages for the owner's tabs. */
export function liveChanges(c: Context) {
c.header('X-Accel-Buffering', 'no');
c.header('Cache-Control', 'no-cache, no-transform');
return streamSSE(c, async (stream) => {
let chain: Promise<unknown> = Promise.resolve();
const send = (data: unknown) => {
chain = chain.then(() => stream.writeSSE({ data: JSON.stringify(data) })).catch(() => undefined);
};
const off = onChange((topics: ChangeTopic[]) => send({ type: 'change', topics }));
const ping = setInterval(() => send({ type: 'ping' }), 25_000);
send({ type: 'ready' });
await new Promise<void>((resolve) => stream.onAbort(() => resolve()));
clearInterval(ping);
off();
await chain;
});
}

View file

@ -209,15 +209,17 @@ export function libraryRoutes(app: AppContext): Hono {
description: z.string().max(2000).optional(),
color: z.enum(CLASS_COLORS).optional(),
archived: z.boolean().optional(),
groupLabel: z.string().trim().min(1).max(24).optional(),
}),
);
db.run(
'UPDATE classes SET name = ?, code = ?, description = ?, color = ?, archived = ?, updated_at = ? WHERE id = ?',
'UPDATE classes SET name = ?, code = ?, description = ?, color = ?, archived = ?, group_label = ?, updated_at = ? WHERE id = ?',
body.name ?? cls.name,
body.code ?? cls.code,
body.description ?? cls.description,
body.color ?? cls.color,
body.archived === undefined ? cls.archived : body.archived ? 1 : 0,
body.groupLabel ?? cls.group_label ?? 'Exam',
now(),
cls.id,
);

View file

@ -6,15 +6,18 @@ import crypto from 'node:crypto';
import { getCookie, setCookie } from 'hono/cookie';
import { isHttps } from '../auth.ts';
import { safeEqual } from '../crypto.ts';
import { EXPLAIN_SYSTEM, explainPrompt } from '../ai/explain.ts';
import { citedPassages, citedPassagesPrompt, EXPLAIN_SYSTEM, explainPrompt } from '../ai/explain.ts';
import { genUiPrompt } from '../ai/genui.ts';
import { officePreviewHtml, PREVIEW_CSP } from '../documents/preview.ts';
import { aiStatus, runChatWithMcp } from '../ai/service.ts';
import { AIError, type ChatMessage } from '../ai/types.ts';
import { HttpError, idParam, notFound, readBody, type AppContext } from '../http.ts';
import { listCards, listQuestions } from '../services/content.ts';
import { searchChunks, sourceLabel, type ChunkHit } from '../services/documents.ts';
import { listChunks, searchChunks, sourceLabel, type ChunkHit } from '../services/documents.ts';
import { hybridSearch } from '../services/semantic.ts';
import { newId, newToken, now, parseJson } from '../util.ts';
import { sse } from './ai.ts';
import type { ToolActivity } from '../ai/activity.ts';
import { sourceActivity, sse, type ExplainEvent } from './ai.ts';
const KINDS = ['quiz', 'deck', 'folder', 'class', 'note', 'document'] as const;
type ShareKind = (typeof KINDS)[number];
@ -183,6 +186,11 @@ export function resetShareAiLimits(): void {
aiHits.clear();
}
/** What a visitor sees of a tool step: the step itself and its pages, not its raw input and output. */
function publicTool(tool: ToolActivity): ToolActivity {
return { id: tool.id, name: tool.kind === 'mcp' ? 'tool' : tool.name, label: tool.label, status: tool.status, kind: tool.kind, subject: tool.subject, sources: tool.sources };
}
const clipText = (text: string, max: number) => (text.length > max ? `${text.slice(0, max)}\n…(more not shown)` : text);
/** What the shared assistant may read: the shared item (or the one being viewed) and the documents in scope. */
@ -403,22 +411,33 @@ export function publicRoutes(app: AppContext): Hono {
const body = await readBody(c, explainSchema);
requireAi(c, share, 'explain');
let prompt: string;
let sources: ReturnType<typeof citedPassages> = [];
if (body.kind === 'question') {
if (!inScope(share, 'quiz', body.quizId)) throw gone();
const q = listQuestions(db, body.quizId).find((x) => x.id === body.questionId);
if (!q) throw gone();
const texts = new Set(q.options.map((o) => o.text));
prompt = explainPrompt({ kind: 'question', stem: q.stem, options: q.options.map((o) => ({ text: o.text, correct: o.correct })), selected: body.selected?.filter((s) => texts.has(s) || q.type === 'numeric').map((s) => s.slice(0, 200)), rationale: q.rationale, ask: body.ask });
// The pages the rationale cites, read only from the quiz's own class.
const classId = db.get<{ class_id: string }>('SELECT class_id FROM quizzes WHERE id = ?', body.quizId)?.class_id;
if (classId && q.rationale) sources = citedPassages(db, q.rationale, { classIds: [classId], stem: q.stem });
prompt += citedPassagesPrompt(sources);
} else {
if (!inScope(share, 'deck', body.deckId)) throw gone();
const card = listCards(db, body.deckId).find((x) => x.id === body.cardId);
if (!card) throw gone();
prompt = explainPrompt({ kind: 'card', front: card.front, back: card.back, ask: body.ask });
}
return sse<{ type: 'text'; delta: string } | { type: 'error'; message: string; code: string } | { type: 'done' }>(c, async (emit, signal) => {
return sse<ExplainEvent>(c, async (emit, signal) => {
try {
if (sources.length) emit({ type: 'tool', tool: sourceActivity(sources) });
// Only MCP servers the owner allowed on share links take part.
await runChatWithMcp(app, { task: 'quick', purpose: 'shared explanation', system: EXPLAIN_SYSTEM, messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }], maxOutputTokens: 1500, signal, onEvent: (e) => e.type === 'text' && emit({ type: 'text', delta: e.delta }) }, 'share');
await runChatWithMcp(
app,
{ task: 'quick', purpose: 'shared explanation', system: EXPLAIN_SYSTEM + genUiPrompt(), messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }], maxOutputTokens: 2500, signal, onEvent: (e) => e.type === 'text' && emit({ type: 'text', delta: e.delta }) },
'share',
{ onTool: (tool) => emit({ type: 'tool', tool: publicTool(tool) }) },
);
} catch (err) {
const ai = err instanceof AIError ? err : null;
if (ai?.code !== 'aborted') emit({ type: 'error', code: ai?.code ?? 'server', message: 'The explanation could not be generated. Try again later.' });
@ -458,11 +477,35 @@ export function publicRoutes(app: AppContext): Hono {
excerpts ? `RELEVANT DOCUMENT EXCERPTS:\n${excerpts}` : '',
]
.filter(Boolean)
.join('\n\n');
.join('\n\n') + genUiPrompt();
const messages: ChatMessage[] = body.messages.map((m) => ({ role: m.role, content: [{ type: 'text', text: m.text }] }));
return sse<{ type: 'text'; delta: string } | { type: 'error'; message: string; code: string } | { type: 'done' }>(c, async (emit, signal) => {
return sse<ExplainEvent>(c, async (emit, signal) => {
try {
await runChatWithMcp(app, { task: 'chat', purpose: 'shared assistant', system, messages, maxOutputTokens: 1500, signal, onEvent: (e) => e.type === 'text' && emit({ type: 'text', delta: e.delta }) }, 'share');
let wrote = false;
await runChatWithMcp(
app,
{
task: 'chat',
purpose: 'shared assistant',
system,
messages,
maxOutputTokens: 2500,
signal,
onEvent: (e) => {
if (e.type !== 'text') return;
wrote = true;
emit({ type: 'text', delta: e.delta });
},
},
'share',
{
onTool: (tool) => {
if (tool.status === 'running' && wrote) emit({ type: 'text', delta: '\n\n' });
wrote = false;
emit({ type: 'tool', tool: publicTool(tool) });
},
},
);
} catch (err) {
const ai = err instanceof AIError ? err : null;
if (ai?.code !== 'aborted') emit({ type: 'error', code: ai?.code ?? 'server', message: 'The assistant could not answer. Try again later.' });
@ -471,6 +514,55 @@ export function publicRoutes(app: AppContext): Hono {
});
});
/* ------------------------------ viewing documents ------------------------------ */
/** The document a link (or an item inside a shared collection) points at; membership is re-checked. */
const sharedDocument = (c: Context, nested: boolean): string => {
const share = load(c.req.param('token') ?? '');
if (!nested) {
if (share.kind !== 'document') throw gone();
return share.target_id;
}
if (share.kind !== 'class' && share.kind !== 'folder') throw gone();
const id = c.req.param('id') ?? '';
if (!collectionItems(app, share).some((i) => i.kind === 'document' && i.id === id)) throw gone();
return id;
};
/** Word and PowerPoint files as a sandboxed HTML page. */
const sendPreview = async (documentId: string) => {
const doc = db.get<{ kind: string; title: string; storage_name: string }>('SELECT kind, title, storage_name FROM documents WHERE id = ?', documentId);
if (!doc || (doc.kind !== 'docx' && doc.kind !== 'pptx')) throw gone();
const file = path.join(app.config.uploadsDir, path.basename(doc.storage_name));
if (!fs.existsSync(file)) throw gone();
let html: string;
try {
html = await officePreviewHtml(doc.kind, new Uint8Array(await fs.promises.readFile(file)), doc.title);
} catch (err) {
app.log('warn', 'Shared document preview failed', err instanceof Error ? err.message : err);
throw new HttpError(422, 'preview_failed', 'This file could not be shown. Download it to open it instead.');
}
return new Response(html, { headers: { 'Content-Type': 'text/html; charset=utf-8', 'Content-Security-Policy': PREVIEW_CSP, 'X-Content-Type-Options': 'nosniff', 'Cache-Control': 'private, no-store', 'X-Robots-Tag': 'noindex, nofollow' } });
};
/** The extracted text, page by page, for reading on any device. */
const sendText = (c: Context, documentId: string) => {
const offset = Math.max(0, Number(c.req.query('offset') ?? 0) || 0);
const limit = Math.min(60, Math.max(1, Number(c.req.query('limit') ?? 30) || 30));
const chunks = listChunks(db, documentId, offset, limit + 1);
c.header('Cache-Control', 'no-store');
c.header('X-Robots-Tag', 'noindex, nofollow');
return c.json({
chunks: chunks.slice(0, limit).map((ch) => ({ id: ch.id, seq: ch.seq, text: ch.text, heading: ch.heading, pageStart: ch.pageStart, pageEnd: ch.pageEnd })),
nextOffset: chunks.length > limit ? offset + limit : null,
});
};
r.get('/:token/preview', (c) => sendPreview(sharedDocument(c, false)));
r.get('/:token/items/document/:id/preview', (c) => sendPreview(sharedDocument(c, true)));
r.get('/:token/text', (c) => sendText(c, sharedDocument(c, false)));
r.get('/:token/items/document/:id/text', (c) => sendText(c, sharedDocument(c, true)));
/** Download for a document inside a shared class or folder. Membership is re-checked. */
r.get('/:token/items/document/:id/file', (c) => {
const share = load(c.req.param('token'));