All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m0s
- 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>
441 lines
19 KiB
TypeScript
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;
|
|
}
|