Study/server/routes/ai.ts
Elijah 85d5c9186d
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m0s
Fifth revision: share-link AI safety, sturdier generation, cleaner UI
- Malformed model JSON is sent back for repair, then retried; a failed job
  starts over once before it fails. Visitors can dismiss failed sets.
- Generated sets get a short distinct name and description; flashcards are
  atomic and have no hints; standard study shows known/learning counts.
- Share links: "In progress" list, finished sets join the normal lists with a
  "New" tag, plain progress steps, newest exam first.
- Share-link AI expires after a week, can be limited to the US or Arizona
  (DB-IP Lite or Cloudflare headers) and is locked by abuse protection
  (migration 8).
- The assistant never answers from general knowledge; MCP and web search
  tools load without a manual test.
- Plain-text copy, no question count in exam mode, filler text removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 09:17:50 -07:00

441 lines
19 KiB
TypeScript

import { Hono, type Context } from 'hono';
import { streamSSE } from 'hono/streaming';
import { z } from 'zod';
import { assistantRequestSchema, displayMessages, followTurn, isTurnRunning, listConversations, mentionables, resolveAction, startAssistantTurn, stopTurn, type AssistantEvent } from '../ai/assistant.ts';
import {
cancelGeneration,
createDraft,
discardDraft,
draftSaveSchema,
generateRequestSchema,
getDraft,
improveRequestSchema,
instructionPatchSchema,
listInstructions,
saveInstruction,
listDrafts,
saveDraft,
startGeneration,
startImprove,
updateDraftPayload,
} from '../ai/generate.ts';
import {
deleteMcpServer,
finishMcpOAuth,
getWebSearch,
listChatSources,
listMcpServers,
mcpServerInputSchema,
mcpServerPatchSchema,
saveMcpServer,
saveWebSearch,
signOutMcp,
startMcpOAuth,
testMcpServer,
WEB_SEARCH_ID,
webSearchPatchSchema,
warmMcpServers,
} 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,
aiStatus,
deleteModel,
deleteProvider,
discoverModels,
getTaskSettings,
listModels,
listProviders,
manualModelSchema,
modelPatchSchema,
patchModel,
providerInputSchema,
runChat,
runChatWithMcp,
saveProvider,
saveTaskSettings,
TASK_INFO,
testProvider,
usageSummary,
} from '../ai/service.ts';
import { embedTexts, embeddingSettingsSchema, getEmbeddingSettings, embeddingStatus, rebuildIndex, saveEmbeddingSettings, scheduleIndexing } from '../services/semantic.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');
c.header('Cache-Control', 'no-cache, no-transform');
return streamSSE(c, async (stream) => {
const controller = new AbortController();
stream.onAbort(() => controller.abort());
let chain: Promise<unknown> = Promise.resolve();
const emit = (event: T | { type: 'ping' }) => {
chain = chain.then(() => stream.writeSSE({ data: JSON.stringify(event) })).catch(() => undefined);
};
const ping = setInterval(() => emit({ type: 'ping' }), 15_000);
try {
await run(emit, controller.signal);
} finally {
clearInterval(ping);
await chain;
}
});
}
const contentDraftSchema = z.discriminatedUnion('kind', [
z.object({
kind: z.literal('quiz'),
title: z.string().max(200),
description: z.string().max(4000).optional().default(''),
questions: z
.array(
z.object({
type: z.enum(['single', 'multi', 'numeric']),
stem: z.string().max(20000),
options: z.array(z.object({ text: z.string().max(4000), correct: z.boolean(), why: z.string().max(20000).optional() })).max(12),
rationale: z.string().max(20000).optional().default(''),
topic: z.string().max(80).optional().default(''),
difficulty: z.enum(['easy', 'medium', 'hard']).optional().default('medium'),
tags: z.array(z.string().max(40)).max(12).optional().default([]),
source: z.string().max(300).optional(),
}),
)
.max(1000),
}),
z.object({
kind: z.literal('deck'),
title: z.string().max(200),
description: z.string().max(4000).optional().default(''),
cards: z.array(z.object({ front: z.string().max(20000), back: z.string().max(20000), hint: z.string().max(20000).optional(), tags: z.array(z.string().max(40)).max(12).optional().default([]) })).max(5000),
}),
z.object({ kind: z.literal('note'), title: z.string().max(200), content: z.string().max(400000) }),
]);
export function aiRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
/* ------------------------------ configuration ------------------------------ */
r.get('/ai/meta', (c) => c.json({ adapters: listAdapterMeta(), tasks: TASK_INFO, catalogUpdated: CATALOG_UPDATED }));
/** Instructions the built-in generator sends to the model (editable in Settings → Templates). */
r.get('/ai/instructions', (c) => c.json({ instructions: listInstructions(db) }));
r.put('/ai/instructions', async (c) => {
saveInstruction(db, await readBody(c, instructionPatchSchema));
return c.json({ instructions: listInstructions(db) });
});
r.get('/ai/status', (c) => c.json(aiStatus(app)));
r.get('/ai/providers', (c) => c.json({ providers: listProviders(app) }));
r.post('/ai/providers', async (c) => c.json({ provider: saveProvider(app, null, await readBody(c, providerInputSchema)) }, 201));
r.patch('/ai/providers/:id', async (c) => c.json({ provider: saveProvider(app, idParam(c), await readBody(c, providerInputSchema)) }));
r.delete('/ai/providers/:id', (c) => {
const id = idParam(c);
deleteProvider(app, id);
// Semantic search cannot keep using a provider that no longer exists.
if (getEmbeddingSettings(db).providerId === id) saveEmbeddingSettings(app, { providerId: null, model: '', dimensions: null });
return c.json({ ok: true });
});
r.post('/ai/providers/:id/test', async (c) => c.json({ result: await testProvider(app, idParam(c)) }));
r.post('/ai/providers/:id/discover', async (c) => {
const result = await discoverModels(app, idParam(c));
return c.json({ ...result, models: listModels(db) });
});
// MCP servers the assistant can call as tools.
r.get('/ai/mcp', (c) => c.json({ servers: listMcpServers(app) }));
// Saving (or signing in) connects in the background, so the tools are ready without a manual test.
r.post('/ai/mcp', async (c) => {
const server = saveMcpServer(app, null, await readBody(c, mcpServerInputSchema));
warmMcpServers(app);
return c.json({ server }, 201);
});
r.patch('/ai/mcp/:id', async (c) => {
const server = saveMcpServer(app, idParam(c), await readBody(c, mcpServerPatchSchema));
warmMcpServers(app);
return c.json({ server });
});
r.delete('/ai/mcp/:id', (c) => {
deleteMcpServer(app, idParam(c));
return c.json({ ok: true });
});
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);
warmMcpServers(app);
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) => {
const webSearch = saveWebSearch(app, await readBody(c, webSearchPatchSchema));
warmMcpServers(app);
return c.json({ webSearch });
});
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)) }));
r.delete('/ai/models/:id', (c) => {
deleteModel(db, idParam(c));
return c.json({ ok: true });
});
r.get('/ai/tasks', (c) => c.json({ tasks: getTaskSettings(db) }));
r.put('/ai/tasks', async (c) => c.json({ tasks: saveTaskSettings(db, await c.req.json().catch(() => ({}))) }));
r.get('/ai/usage', (c) => c.json(usageSummary(db, Math.min(Math.max(Number(c.req.query('days') ?? 30) || 30, 1), 365))));
/* ------------------------------ generation + drafts ------------------------------ */
r.post('/ai/generate', async (c) => {
const body = await readBody(c, generateRequestSchema);
const { draftId } = startGeneration(app, body);
return c.json({ draftId }, 202);
});
r.post('/ai/improve', async (c) => {
const body = await readBody(c, improveRequestSchema);
const { draftId } = startImprove(app, body);
return c.json({ draftId }, 202);
});
r.get('/drafts', (c) => c.json({ drafts: listDrafts(db) }));
/** A blank or pre-filled draft, used by the import preview so imports and AI output share one review screen. */
r.post('/drafts', async (c) => {
const body = await readBody(c, z.object({ payload: contentDraftSchema, classId: z.string().nullish(), folderId: z.string().nullish() }));
const id = createDraft(db, { kind: body.payload.kind, classId: body.classId ?? null, folderId: body.folderId ?? null, title: body.payload.title, payload: body.payload as never, meta: { origin: 'import' } });
return c.json({ draft: getDraft(db, id) }, 201);
});
r.get('/drafts/:id', (c) => c.json({ draft: getDraft(db, idParam(c)) }));
r.put('/drafts/:id', async (c) => {
const body = await readBody(c, z.object({ payload: contentDraftSchema, classId: z.string().nullish(), folderId: z.string().nullish() }));
return c.json({ draft: updateDraftPayload(db, idParam(c), body.payload as never, { classId: body.classId, folderId: body.folderId }) });
});
r.post('/drafts/:id/save', async (c) => {
const body = await readBody(c, draftSaveSchema);
return c.json({ saved: saveDraft(app, idParam(c), body) });
});
r.post('/drafts/:id/cancel', (c) => {
cancelGeneration(idParam(c));
return c.json({ ok: true });
});
r.delete('/drafts/:id', (c) => {
discardDraft(db, idParam(c));
return c.json({ ok: true });
});
/* ------------------------------ assistant ------------------------------ */
/** Streams a running turn's events (replayed from its start) until it ends or the client leaves. */
const follow = (conversationId: string, emit: Emit<AssistantEvent>, signal: AbortSignal) =>
new Promise<void>((resolve) => {
let unsubscribe: (() => void) | null = null;
const finish = () => {
unsubscribe?.();
resolve();
};
unsubscribe = followTurn(conversationId, (event) => {
emit(event);
if (event.type === 'done') queueMicrotask(finish);
});
if (!unsubscribe) {
emit({ type: 'done', conversationId, title: '' });
return resolve();
}
// Leaving the page only stops the stream; the turn keeps running on the server.
signal.addEventListener('abort', finish, { once: true });
});
r.post('/ai/chat', async (c) => {
const body = await readBody(c, assistantRequestSchema);
return sse<AssistantEvent>(c, async (emit, signal) => {
let conversationId: string;
try {
({ conversationId } = startAssistantTurn(app, body));
} catch (err) {
// Failures before the turn starts (no model configured, bad input, already running) still reach the client as an event.
const ai = err instanceof AIError ? err : null;
const http = err instanceof HttpError ? err : null;
if (!ai && !http) app.log('error', 'Assistant request failed', err);
emit({ type: 'error', code: ai?.code ?? http?.code ?? 'server', message: ai?.message ?? http?.message ?? 'The assistant could not start.', detail: ai?.providerMessage });
emit({ type: 'done', conversationId: body.conversationId ?? '', title: '' });
return;
}
await follow(conversationId, emit, signal);
});
});
/** Re-attaches to a turn that is still running (after leaving and coming back). */
r.get('/ai/chat/:id/stream', (c) => {
const id = idParam(c);
return sse<AssistantEvent>(c, (emit, signal) => follow(id, emit, signal));
});
r.post('/ai/chat/:id/stop', (c) => c.json({ stopped: stopTurn(idParam(c)) }));
/** Library items that can be tagged with @ in the assistant. */
r.get('/ai/mentionables', (c) => c.json({ items: mentionables(db, { classId: c.req.query('classId') || null, q: c.req.query('q') ?? '' }) }));
r.get('/ai/conversations', (c) => c.json({ conversations: listConversations(db).map((x) => ({ ...x, running: isTurnRunning(x.id) })) }));
r.get('/ai/conversations/:id', (c) => {
const id = idParam(c);
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');
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) => {
const { changes } = db.run('DELETE FROM conversations WHERE id = ?', idParam(c));
if (!changes) throw notFound('Conversation');
return c.json({ ok: true });
});
r.post('/ai/actions/:id', async (c) => {
const body = await readBody(c, z.object({ confirm: z.boolean() }));
return c.json(resolveAction(app, idParam(c), body.confirm));
});
/* ------------------------------ inline explanations ------------------------------ */
const explainSchema = z.discriminatedUnion('kind', [
z.object({
kind: z.literal('question'),
stem: z.string().max(20000),
options: z.array(z.object({ text: z.string().max(4000), correct: z.boolean() })).max(12),
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() }),
]);
r.post('/ai/explain', async (c) => {
const body = await readBody(c, explainSchema);
const prompt = explainPrompt(body);
if (!prompt.trim()) throw badRequest('Nothing to explain');
// 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 + genUiPrompt('explain'),
messages: [{ role: 'user', content: [{ type: 'text', text: prompt + citedPassagesPrompt(sources) }] }],
maxOutputTokens: 2500,
signal,
onEvent: (e) => {
if (e.type !== 'text') return;
wrote = true;
emit({ type: 'text', delta: e.delta });
},
},
'explain',
{
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 });
},
},
);
} catch (err) {
const ai = err instanceof AIError ? err : null;
if (ai?.code !== 'aborted') emit({ type: 'error', code: ai?.code ?? 'server', message: ai?.message ?? 'The explanation could not be generated.' });
}
emit({ type: 'done' });
});
});
/* ------------------------------ semantic search ------------------------------ */
r.get('/ai/embeddings', (c) => c.json(embeddingStatus(app)));
r.put('/ai/embeddings', async (c) => {
saveEmbeddingSettings(app, await readBody(c, embeddingSettingsSchema));
return c.json(embeddingStatus(app));
});
/** Embeds one sentence to prove the model works before indexing everything. */
r.post('/ai/embeddings/test', async (c) => {
const started = Date.now();
const [v] = await embedTexts(app, ['Furosemide is a loop diuretic.'], 'query');
return c.json({ ok: true, dimensions: v.length, latencyMs: Date.now() - started });
});
r.post('/ai/embeddings/rebuild', (c) => {
rebuildIndex(app);
return c.json(embeddingStatus(app));
});
r.post('/ai/embeddings/resume', (c) => {
scheduleIndexing(app);
return c.json(embeddingStatus(app));
});
return r;
}