papilot 0.7.0 → 0.8.0

package/src/server/cursor.ts

@@ -0,0 +1,153 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Adapter, loadPackage, toolItem, type Item, type Thread, type Turn } from './agents.ts';
+import { imageType } from './attachments.ts';
+import { DATA } from './paths.ts';
+
+// The parts of @cursor/sdk Papilot uses. The SDK is fetched on first use, so
+// its types are restated here instead of being a build dependency.
+export const CURSOR_SDK_VERSION = '1.2.0';
+interface ModelSelection { id: string; params?: { id: string; value: string }[] }
+interface CursorModel { id: string; displayName: string; parameters?: { id: string; values: { value: string; displayName?: string }[] }[]; variants?: { params: { id: string; value: string }[]; isDefault?: boolean }[] }
+interface CursorMessage { type: string; call_id?: string; name?: string; status?: string; args?: any; result?: any; message?: { content: { type: string; text?: string }[] } }
+interface CursorRun { stream(): AsyncGenerator<CursorMessage, void>; wait(): Promise<{ status: 'finished' | 'error' | 'cancelled'; error?: { message: string } }>; cancel(): Promise<void> }
+interface CursorAgentHandle { agentId: string; send(message: string | { text: string; images?: { data: string; mimeType: string }[] }, options?: { model?: ModelSelection; onDelta?: (args: { update: { type: string; text?: string } }) => void }): Promise<CursorRun>; close(): void }
+interface AgentOptions { model?: ModelSelection; name?: string; local: { cwd: string; settingSources: string[]; sandboxOptions: { enabled: boolean } } }
+export interface CursorSdk {
+  Agent: { create(options: AgentOptions): Promise<CursorAgentHandle>; resume(agentId: string, options: Partial<AgentOptions>): Promise<CursorAgentHandle> };
+  Cursor: { me(): Promise<{ apiKeyName: string; userEmail?: string }>; models: { list(): Promise<CursorModel[]> } };
+}
+
+const CURSOR_KEY = 'Cursor needs a Cursor API key: start Papilot with CURSOR_API_KEY set (create one in the Cursor dashboard). The SDK does not use the Cursor app or CLI login.';
+// The SDK reads CURSOR_API_KEY, then the login it stores itself.
+export function cursorConfigured(env: NodeJS.ProcessEnv = process.env) {
+  return Boolean(env.CURSOR_API_KEY) || fs.existsSync(path.join(os.homedir(), '.cursor/sdk/auth.json'));
+}
+let cursor: Promise<CursorSdk> | null = null;
+export function loadCursor() {
+  cursor ??= loadPackage('@cursor/sdk', CURSOR_SDK_VERSION, 'the Cursor SDK for Cursor tasks', () => { if (!cursorConfigured()) throw new Error(CURSOR_KEY); })
+    .catch(error => { cursor = null; throw error; });
+  return cursor;
+}
+
+// Effort is a model parameter in Cursor's catalog.
+const effortParameter = (model?: CursorModel) => model?.parameters?.find(parameter => /effort|reasoning/i.test(parameter.id));
+
+// Cursor runs as a local SDK agent in the task worktree, with Cursor's own
+// sandbox: writes stay in the worktree and temporary folders, and commands
+// run without network access. The SDK has no interactive approvals, so
+// anything outside the sandbox fails and is reported in the conversation.
+// Each Papilot thread maps to a Cursor agent ID, resumed after a restart.
+export class CursorAgent extends Adapter {
+  private user: { apiKeyName: string; userEmail?: string } | null = null;
+  private catalog: CursorModel[] = [];
+  private agents = new Map<string, CursorAgentHandle>();
+  private ids: Record<string, string> = {};
+  constructor(private load: () => Promise<CursorSdk> = loadCursor, private file = path.join(DATA, 'cursor-agents.json'), private configured = () => cursorConfigured()) {
+    super();
+    try { this.ids = JSON.parse(fs.readFileSync(this.file, 'utf8')); } catch { /* None yet. */ }
+  }
+  detect() { return this.configured(); }
+  async start() {
+    if (this.ready) return;
+    const sdk = await this.load();
+    const [user, models] = await Promise.all([sdk.Cursor.me(), sdk.Cursor.models.list()]);
+    this.user = user; this.catalog = models; this.ready = true;
+  }
+  private defaultModel() { return this.catalog.find(model => model.id === 'auto') || this.catalog[0]; }
+  protected account() {
+    return this.user ? { account: { email: this.user.userEmail, type: 'Cursor API key' }, requiresOpenaiAuth: false } : { account: null, requiresOpenaiAuth: true, reason: CURSOR_KEY };
+  }
+  protected models() {
+    const preferred = this.defaultModel();
+    return { data: this.catalog.map(model => {
+      const parameter = effortParameter(model), fallback = model.variants?.find(variant => variant.isDefault)?.params.find(param => param.id === parameter?.id)?.value;
+      return { model: model.id, displayName: model.displayName, isDefault: model === preferred,
+        supportedReasoningEfforts: (parameter?.values || []).map(value => ({ reasoningEffort: value.value })), defaultReasoningEffort: fallback || null };
+    }) };
+  }
+  private selection(model: string | null, effort: string | null): ModelSelection | undefined {
+    const entry = this.catalog.find(item => item.id === model) || (model ? undefined : this.defaultModel());
+    const id = entry?.id || model;
+    if (!id) return undefined;
+    const parameter = effortParameter(entry);
+    if (effort && !parameter?.values.some(value => value.value === effort)) throw new Error(`Cursor does not support reasoning effort ${effort} for this model.`);
+    return { id, ...(effort && parameter ? { params: [{ id: parameter.id, value: effort }] } : {}) };
+  }
+  private async agent(threadId: string, cwd: string, model: ModelSelection | undefined) {
+    const known = this.agents.get(threadId);
+    if (known) return known;
+    const sdk = await this.load();
+    const options: AgentOptions = { local: { cwd, settingSources: ['project'], sandboxOptions: { enabled: true } } };
+    const id = this.ids[threadId];
+    const agent = id ? await sdk.Agent.resume(id, options) : await sdk.Agent.create({ ...options, name: 'Papilot task', ...(model ? { model } : {}) });
+    if (!id) { this.ids[threadId] = agent.agentId; this.save(); }
+    this.agents.set(threadId, agent);
+    return agent;
+  }
+  protected run(turn: Turn, thread: Thread, text: string, effort: string | null, images: string[]) { void this.execute(turn, thread, text, effort, images); }
+  private async execute(turn: Turn, thread: Thread, text: string, effort: string | null, images: string[]) {
+    let stopped = false, run: CursorRun | null = null;
+    turn.stop = () => { stopped = true; void run?.cancel().catch(() => {}); if (!run) this.finish(turn, 'interrupted'); };
+    let live = '', segment = 0, streamed = false;
+    const flush = () => {
+      if (live.trim()) this.item(turn, { id: `${turn.id}:text:${segment}`, type: 'agentMessage', text: live });
+      if (live) segment++;
+      live = '';
+    };
+    try {
+      const model = this.selection(thread.model, effort);
+      const agent = await this.agent(turn.threadId, thread.cwd, model);
+      // Cursor's harness prompt stays in place: the first turn carries Papilot's instructions.
+      const prompt = thread.started ? text : `${thread.instructions}\n\n---\n\n${text}`;
+      const attached = await Promise.all(images.map(async file => {
+        const bytes = await fs.promises.readFile(file), mimeType = imageType(bytes);
+        if (!mimeType) throw new Error('This image format is not supported.');
+        return { data: bytes.toString('base64'), mimeType };
+      }));
+      if (stopped) return;
+      run = await agent.send(attached.length ? { text: prompt, images: attached } : prompt, { ...(model ? { model } : {}), onDelta: ({ update }) => {
+        if (update.type !== 'text-delta' || !update.text) return;
+        streamed = true; live += update.text;
+        this.notify('item/agentMessage/delta', { threadId: turn.threadId, turnId: turn.id, itemId: `${turn.id}:text:${segment}`, delta: update.text });
+      } });
+      this.threads.set(turn.threadId, { ...thread, started: true });
+      if (stopped) await run.cancel().catch(() => {});
+      for await (const message of run.stream()) {
+        if (message.type === 'tool_call' && message.call_id) { flush(); this.tool(turn, message); }
+        // Without text deltas, the completed assistant text is the reply.
+        else if (message.type === 'assistant' && !streamed) for (const block of message.message?.content || []) if (block.type === 'text' && block.text) live += block.text;
+      }
+      const result = await run.wait();
+      flush();
+      if (stopped || result.status === 'cancelled') this.finish(turn, 'interrupted');
+      else if (result.status === 'finished') this.finish(turn, 'completed');
+      else this.finish(turn, 'failed', result.error?.message || 'Cursor stopped with an error.');
+    } catch (error) {
+      flush();
+      this.agents.delete(turn.threadId);
+      this.finish(turn, stopped ? 'interrupted' : 'failed', stopped ? undefined : error instanceof Error ? error.message : String(error));
+    }
+  }
+  private tool(turn: Turn, message: CursorMessage) {
+    const id = `${turn.id}:${message.call_id}`, args = message.args && typeof message.args === 'object' ? message.args : {};
+    const status = message.status === 'error' || message.result?.status === 'error' ? 'failed' : message.status === 'completed' ? 'completed' : 'inProgress';
+    let item: Item;
+    if (message.name === 'shell') {
+      const value = message.result?.value || {}, output = [value.stdout, value.stderr].filter(Boolean).join('\n') || (message.result?.error ? String(message.result.error.message || message.result.error) : '');
+      item = { id, type: 'commandExecution', command: String(args.command || 'shell'), aggregatedOutput: output.slice(-40000), status };
+    } else if (['edit', 'write', 'delete'].includes(message.name || '') && typeof args.path === 'string') {
+      item = { id, type: 'fileChange', changes: [{ path: args.path }], status };
+    } else item = { ...toolItem(id, message.name || 'tool', { ...args, file_path: args.path, pattern: args.pattern || args.globPattern }), status };
+    this.item(turn, item, status !== 'inProgress');
+  }
+  private save() {
+    try { fs.mkdirSync(path.dirname(this.file), { recursive: true }); fs.writeFileSync(this.file, JSON.stringify(this.ids)); } catch { /* A later turn starts a new agent. */ }
+  }
+  close() {
+    super.close();
+    for (const agent of this.agents.values()) { try { agent.close(); } catch { /* Already closed. */ } }
+    this.agents.clear(); this.ready = false;
+  }
+}

package/src/server/latex-installation.ts

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFile } from 'node:child_process';
+import type { LatexInstallation } from '../shared.ts';
+
+type Probe = (file: string, args: string[], env: NodeJS.ProcessEnv) => Promise<string | null>;
+const command: Probe = (file, args, env) => new Promise(resolve => {
+  const child = execFile(file, args, { env, cwd: os.homedir(), timeout: 5000, killSignal: 'SIGKILL', maxBuffer: 128 * 1024 }, (error, stdout) => resolve(error ? null : stdout.trim()));
+  child.stdin?.end();
+});
+
+// Identify the installation actually found on the server's PATH. In particular,
+// a MacTeX receipt elsewhere on the machine must not relabel another TeX Live.
+export async function detectLatex(env: NodeJS.ProcessEnv = process.env, platform = process.platform, probe: Probe = command): Promise<LatexInstallation | null> {
+  const suffix = platform === 'win32' ? '.exe' : '';
+  const executable = (name: string) => (env.PATH || '').split(path.delimiter).filter(Boolean).map(directory => path.resolve(directory, name + suffix)).find(candidate => {
+      try { fs.accessSync(candidate, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK); return fs.statSync(candidate).isFile(); } catch { return false; }
+    });
+  let found = false;
+  for (const engine of ['pdflatex', 'xelatex', 'lualatex']) {
+    const file = executable(engine);
+    if (!file) continue;
+    found = true;
+    const banner = await probe(file, ['--version'], env);
+    if (!banner) continue;
+    const texlive = banner.match(/\bTeX Live (\d{4})\b/i);
+    const miktex = banner.match(/\bMiKTeX[ \t]+([\d.]+)/i);
+    let distribution: LatexInstallation['distribution'] = texlive ? 'TeX Live' : /\bMiKTeX\b/i.test(banner) ? 'MiKTeX' : null;
+    const resolved = fs.realpathSync(file);
+    const root = await probe(path.join(path.dirname(file), 'kpsewhich' + suffix), ['-var-value=TEXMFROOT'], env);
+    const location = root && path.isAbsolute(root) && !/[\r\n]/.test(root) ? root : path.dirname(resolved);
+    if (platform === 'darwin' && texlive) {
+      const receipt = await probe('/usr/sbin/pkgutil', ['--file-info', resolved], env);
+      const ids = [...(receipt || '').matchAll(/^pkgid:\s*(\S+)/gm)].map(match => match[1]);
+      if (ids.some(id => /^org\.tug\.mactex\.basictex\d*$/i.test(id))) distribution = 'BasicTeX';
+      else if (ids.some(id => /^org\.tug\.mactex\.texlive\d*$/i.test(id))) distribution = 'MacTeX';
+    }
+    return { distribution, version: texlive?.[1] || miktex?.[1] || null, path: location };
+  }
+  if (found) throw new Error('Could not read the LaTeX installation.');
+  return null;
+}

package/src/server/manuscript.ts

@@ -1,3 +1,4 @@
+import type { ReviewSnapshot } from './ai-review.ts';
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { EventEmitter } from 'node:events';
@@ -7,10 +8,11 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 import { pathToFileURL } from 'node:url';
 import { ENGINE } from './paths.ts';
-import type { Annotation, GitFile, GitStatus, ManuscriptBuild } from '../shared.ts';
+import type { Annotation, BuildProblem, GitFile, GitStatus, ManuscriptBuild, ManuscriptProblems } from '../shared.ts';
 import { notesInstructions } from '../notes.ts';
 import { ignorePattern } from '../commit.ts';
 import { AnnotationPages, placeAnnotation } from './annotation-placement.ts';
+import { collectProblems, countProblems, locateProblems, scrubLog, sortProblems, type StoredProblem } from './build-problems.ts';
 
 type Rect = [number, number, number, number];
 
@@ -340,12 +342,21 @@ export async function pdfWords(pdf: string, page: number) {
   } finally { document.close(); }
 }
 
-interface Build { tree: string; status: ManuscriptBuild['status']; key?: string; pdf?: string; root?: string; sourceDir?: string; pages?: [number, number][]; builtAt?: number; error?: string }
+// `problems` come from the last finished build. They are placed on the PDF
+// named `problemsKey`; a failed build has no PDF of its own to place them on.
+interface Build {
+  tree: string; status: ManuscriptBuild['status']; key?: string; pdf?: string; root?: string; sourceDir?: string; pages?: [number, number][]; builtAt?: number; error?: string;
+  problems?: StoredProblem[]; problemsKey?: string; log?: string; logFolder?: string;
+}
+
+
 
 export class Manuscripts extends EventEmitter {
   private builds = new Map<string, Build>();
   private oldPdfs = new Map<string, string | null>();
   private placements = new Map<string, (Pick<Annotation, 'key' | 'page' | 'rect' | 'rects' | 'source'>) | null>();
+  // Placed problems per problem list; a rebuild in progress shares its predecessor's list.
+  private located = new WeakMap<StoredProblem[], Promise<BuildProblem[]>>();
   get busyForUpdate() { return [...this.builds.values()].some(build => build.status === 'building'); }
   busyForProject(id: string) { return this.builds.get(id)?.status === 'building'; }
   forgetProject(id: string) { this.builds.delete(id); }
@@ -355,29 +366,55 @@ export class Manuscripts extends EventEmitter {
     let build = this.builds.get(projectId);
     if (!build || (build.status !== 'building' && (build.tree !== tree || rebuild))) build = this.start(projectId, root, tree, build, rebuild);
     const { status: state, key, pages, builtAt, error } = build;
-    return { git: status, build: { status: state, key, pages, builtAt, error, current: build.tree === tree && state === 'ready' } };
+    return { git: status, build: { status: state, key, pages, builtAt, error, current: build.tree === tree && state === 'ready', problems: build.problems && countProblems(build.problems) } };
   }
 
   // Keep the previous pages visible while a newer working tree compiles.
   private start(projectId: string, root: string, tree: string, previous?: Build, force = false) {
     if (previous?.key && previous.pdf) this.oldPdfs.set(`${root}:${previous.key}`, previous.pdf);
-    const build: Build = { tree, status: 'building', key: previous?.key, pdf: previous?.pdf, root: previous?.root, sourceDir: previous?.sourceDir, pages: previous?.pages, builtAt: previous?.builtAt };
+    const build: Build = { tree, status: 'building', key: previous?.key, pdf: previous?.pdf, root: previous?.root, sourceDir: previous?.sourceDir, pages: previous?.pages, builtAt: previous?.builtAt, problems: previous?.problems, problemsKey: previous?.problemsKey, log: previous?.log, logFolder: previous?.logFolder };
     this.builds.set(projectId, build);
     void (async () => {
+      let project: { source_dir?: string; doc_dir?: string; state: string } | undefined;
       try {
         const { Builder, Repo, loadProject, mupdf } = await engine();
-        const project = loadProject(root), result = await new Builder(project, new Repo(root)).build(tree, ['full'], null, { force });
+        project = loadProject(root);
+        const result = await new Builder(project, new Repo(root)).build(tree, ['full'], null, { force });
         const document = mupdf.Document.openDocument(fs.readFileSync(result.pdf), 'application/pdf');
         const pages: [number, number][] = [];
         for (let i = 0; i < document.countPages(); i++) { const [x0, y0, x1, y1] = document.loadPage(i).getBounds(); pages.push([Math.round(x1 - x0), Math.round(y1 - y0)]); }
         document.destroy?.();
         const key = createHash('sha256').update(result.key + result.pdf).digest('hex').slice(0, 16);
         if (this.builds.get(projectId) !== build) return;
-        Object.assign(build, { status: 'ready', key, pdf: result.pdf, root: result.root, sourceDir: project.source_dir || '', pages, builtAt: Date.now(), error: undefined });
+        const log = String(result.pdf).replace(/\.pdf$/, '.log');
+        let problems: StoredProblem[] = [];
+        try { problems = collectProblems(fs.readFileSync(log), { cwd: result.cwd, root: result.root, sourceDir: project!.source_dir || '', outDir: path.dirname(result.pdf) }); } catch { /* A build without a readable log reports no problems. */ }
+        Object.assign(build, { status: 'ready', key, pdf: result.pdf, root: result.root, sourceDir: project!.source_dir || '', pages, builtAt: Date.now(), error: undefined, problems, problemsKey: key, log: fs.existsSync(log) ? log : undefined, logFolder: path.dirname(result.root) });
+        // Place the problems now, so the list is ready when someone opens it.
+        if (problems.length) void this.problems(projectId).catch(() => undefined);
       } catch (error) {
         if (this.builds.get(projectId) !== build) return;
-        const detail = error as { message?: string; details?: string[] };
-        Object.assign(build, { status: 'failed', error: [detail.message, ...(detail.details || [])].filter(Boolean).join('\n') || 'The manuscript could not be compiled.' });
+        const detail = error as { message?: string; details?: string[]; log?: string };
+        const message = [detail.message, ...(detail.details || [])].filter(Boolean).join('\n') || 'The manuscript could not be compiled.';
+        // The engine keeps latexmk's transcript and the TeX log of a failed
+        // build; its sources are gone, so files resolve in the working tree.
+        let problems: StoredProblem[] = [];
+        if (detail.log && project) try {
+          const kept = fs.readFileSync(detail.log), marker = Buffer.from('\n\n--- TeX log ---\n'), at = kept.indexOf(marker);
+          // TeX stopped in its first pass, before references resolve, so only
+          // the errors of a failed run mean anything.
+          if (at >= 0) problems = collectProblems(kept.subarray(at + marker.length), { cwd: path.join(root, project.doc_dir || '.'), root: path.join(root, project.source_dir || '.'), sourceDir: project.source_dir || '' })
+            .filter(problem => problem.severity === 'error').map(({ source: _source, ...problem }) => problem);
+        } catch { /* Fall back to the compiler's own message below. */ }
+        // BibTeX, Biber, latexmk and helper programs fail outside the TeX log;
+        // whatever the compiler said that the parsed errors do not cover stays.
+        const plain = (text: string) => text.replace(/\s+/g, ' ').trim();
+        const unexplained = (detail.details || []).filter(line => line.trim() && !/==> Fatal error occurred|^Emergency stop/.test(line) && !problems.some(problem => plain(line).includes(plain(problem.message).replace(/^[^:]+:\d+: /, ''))));
+        const logFolder = detail.log && project ? path.join(project.state, 'cache/builds', path.basename(detail.log, '.log')) : undefined;
+        if (!problems.length || unexplained.length) problems.push({ kind: 'error', severity: 'error', message: scrubLog([...(problems.length ? [] : [detail.message || 'The manuscript could not be compiled.']), ...unexplained].join('\n'), logFolder) });
+        // The previous PDF stays on screen, and so do its warnings and places.
+        const shown = build.problemsKey && build.problemsKey === build.key ? (build.problems || []).filter(problem => problem.severity !== 'error') : [];
+        Object.assign(build, { status: 'failed', error: message, problems: [...problems, ...shown], problemsKey: shown.length ? build.problemsKey : undefined, log: detail.log && fs.existsSync(detail.log) ? detail.log : undefined, logFolder });
       }
       this.emit('change', projectId);
     })();
@@ -400,21 +437,7 @@ export class Manuscripts extends EventEmitter {
         if (!this.placements.has(cacheKey)) {
           let placement: Pick<Annotation, 'key' | 'page' | 'rect' | 'rects' | 'source'> | null = null;
           try {
-            const lookup = `${root}:${note.key}`;
-            if (!this.oldPdfs.has(lookup)) {
-              const cache = path.join(loadProject(root).state, 'cache/builds');
-              let found: string | null = null;
-              for (const entry of fs.readdirSync(cache, { withFileTypes: true })) {
-                if (!entry.isDirectory() || entry.name.endsWith('.lock')) continue;
-                try {
-                  const folder = path.join(cache, entry.name), saved = JSON.parse(fs.readFileSync(path.join(folder, 'result.json'), 'utf8'));
-                  if (typeof saved.pdf !== 'string' || !path.resolve(saved.pdf).startsWith(path.resolve(folder) + path.sep)) continue;
-                  if (createHash('sha256').update(saved.key + saved.pdf).digest('hex').slice(0, 16) === note.key && fs.existsSync(saved.pdf)) { found = saved.pdf; break; }
-                } catch { /* An incomplete or pruned build cannot locate a note. */ }
-              }
-              this.oldPdfs.set(lookup, found);
-            }
-            const pdf = this.oldPdfs.get(lookup);
+            const pdf = await this.cachedPdf(root, note.key);
             if (pdf) {
               if (!old.has(pdf)) { const document = new PdfDocument(pdf); old.set(pdf, { document, pages: new AnnotationPages(document) }); }
               const match = placeAnnotation(note, old.get(pdf)!.pages, target);
@@ -435,6 +458,125 @@ export class Manuscripts extends EventEmitter {
     } finally { current.close(); for (const entry of old.values()) entry.document.close(); }
   }
 
+  // Every problem of the last finished build, placed on its PDF when there is
+  // one. Placing runs SyncTeX per problem, once per build.
+  async problems(projectId: string): Promise<ManuscriptProblems> {
+    const build = this.builds.get(projectId);
+    if (!build?.problems) return { status: build?.status || 'building', problems: [], log: Boolean(build?.log) };
+    const { problems, problemsKey: key, pdf } = build;
+    if (!key || key !== build.key || !pdf) return { status: build.status, problems: sortProblems(problems.map(({ source: _source, occurrence: _occurrence, ...problem }) => problem)), log: Boolean(build.log) };
+    let placed = this.located.get(problems);
+    if (!placed) {
+      placed = (async () => {
+        const { PdfDocument } = await engine();
+        const document = new PdfDocument(pdf), pages = new Map<number, ReturnType<typeof document.page>>();
+        try {
+          return sortProblems(await locateProblems(problems, pdf, page => {
+            if (!Number.isInteger(page) || page < 0 || page >= document.length) return null;
+            if (!pages.has(page)) pages.set(page, document.page(page));
+            return pages.get(page)!;
+          }));
+        } finally { for (const page of pages.values()) page.close(); document.close(); }
+      })();
+      placed.catch(() => this.located.delete(problems));
+      this.located.set(problems, placed);
+    }
+    return { status: build.status, key, problems: await placed, log: Boolean(build.log) };
+  }
+
+  log(projectId: string) {
+    const build = this.builds.get(projectId);
+    if (!build?.log || !fs.existsSync(build.log)) throw Object.assign(new Error('There is no compilation log yet.'), { statusCode: 404 });
+    return scrubLog(fs.readFileSync(build.log, 'utf8'), build.logFolder);
+  }
+
+  // Compile the task's frozen source tree, then retain its PDF outside the build cache.
+  async captureReview(root: string, worktree: string, taskId: string): Promise<ReviewSnapshot> {
+    const { Builder, Repo, loadProject } = await engine();
+    const tree = await workingTree(worktree);
+    const result = await new Builder(loadProject(root), new Repo(root)).build(tree, ['full']);
+    const pdf = await this.preserveReviewPdf(root, taskId, result.pdf);
+    const key = createHash('sha256').update(fs.readFileSync(pdf)).digest('hex').slice(0, 16);
+    return { ...await this.snapshotPdf(pdf, key), pdf };
+  }
+
+  private async reviewPdfPath(root: string, taskId: string) {
+    const { loadProject } = await engine();
+    return path.join(loadProject(root).state, 'ai-reviews', createHash('sha256').update(taskId).digest('hex'), 'review.pdf');
+  }
+
+  async savedReviewPdf(root: string, taskId: string): Promise<string | null> {
+    const pdf = await this.reviewPdfPath(root, taskId);
+    return fs.existsSync(pdf) ? pdf : null;
+  }
+
+  async preserveReviewPdf(root: string, taskId: string, source: string) {
+    const pdf = await this.reviewPdfPath(root, taskId), folder = path.dirname(pdf);
+    fs.mkdirSync(folder, { recursive: true });
+    // A retry always uses the original task copy, even after its build cache is pruned.
+    if (!fs.existsSync(pdf)) { const temporary = path.join(folder, 'review.tmp'); fs.copyFileSync(source, temporary); fs.renameSync(temporary, pdf); }
+    return pdf;
+  }
+
+  async cachedPdf(root: string, key: string): Promise<string | null> {
+    const lookup = `${root}:${key}`;
+    if (this.oldPdfs.has(lookup)) return this.oldPdfs.get(lookup)!;
+    const { loadProject } = await engine();
+    const cache = path.join(loadProject(root).state, 'cache/builds');
+    let found: string | null = null;
+    if (fs.existsSync(cache)) for (const entry of fs.readdirSync(cache, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.endsWith('.lock')) continue;
+      try {
+        const folder = path.join(cache, entry.name), saved = JSON.parse(fs.readFileSync(path.join(folder, 'result.json'), 'utf8'));
+        if (typeof saved.pdf !== 'string' || !path.resolve(saved.pdf).startsWith(path.resolve(folder) + path.sep)) continue;
+        if (createHash('sha256').update(saved.key + saved.pdf).digest('hex').slice(0, 16) === key && fs.existsSync(saved.pdf)) { found = saved.pdf; break; }
+      } catch { /* Incomplete builds have no usable PDF. */ }
+    }
+    this.oldPdfs.set(lookup, found); return found;
+  }
+
+  async placeReviewNote(projectId: string, root: string, note: Annotation, pdf: string): Promise<Annotation> {
+    const state = await this.state(projectId, root);
+    if (!state.build.current || !state.build.key) throw new Error('Wait for the current manuscript PDF to finish compiling, then copy the suggestion again.');
+    const key = state.build.key, { PdfDocument } = await engine();
+    const original = new PdfDocument(pdf), current = new PdfDocument(this.pdf(projectId, key));
+    try {
+      const match = placeAnnotation(note, new AnnotationPages(original), new AnnotationPages(current));
+      if (!match) throw new Error('This passage could not be located reliably in the current manuscript. The suggestion remains in the review task.');
+      const { source } = await this.locate(projectId, key, match.page, match.rect, match.rects, note.quote);
+      const latest = await this.state(projectId, root);
+      if (!latest.build.current || latest.build.key !== key) throw new Error('The manuscript changed while copying this suggestion. Try again.');
+      return { ...note, ...match, key, source };
+    } finally { original.close(); current.close(); }
+  }
+
+  async reviewSnapshot(projectId: string, key: string): Promise<ReviewSnapshot> {
+    return this.snapshotPdf(this.pdf(projectId, key), key);
+  }
+
+  private async snapshotPdf(pdf: string, key: string): Promise<ReviewSnapshot> {
+    const { PdfDocument } = await engine();
+    const document = new PdfDocument(pdf), lines: ReviewSnapshot['lines'] = [];
+    let length = 0;
+    try {
+      for (let index = 0; index < document.length; index++) {
+        const page = document.page(index), [left, top, right, bottom] = page.bounds;
+        for (const [number, line] of page.lines.entries()) {
+          const text = line.chars.map((char: { text: string }) => char.text).join('').trim();
+          if (!text) continue;
+          length += text.length;
+          if (length > 180000) throw new Error('This PDF is too long for one AI review (180,000 characters maximum).');
+          const [x0, y0, x1, y1] = line.rect;
+          const rect = [(x0 - left) / (right - left), (y0 - top) / (bottom - top), (x1 - left) / (right - left), (y1 - top) / (bottom - top)].map(value => Math.max(0, Math.min(1, value))) as Rect;
+          if (rect[2] <= rect[0] || rect[3] <= rect[1]) continue;
+          lines.push({ id: `p${index + 1}-l${number + 1}`, page: index, text, rect });
+        }
+      }
+      if (!lines.length) throw new Error('This PDF has no selectable text to review.');
+      return { key, lines };
+    } finally { document.close(); }
+  }
+
   pdf(projectId: string, key: string) {
     const build = this.builds.get(projectId);
     if (!build?.pdf || build.key !== key) throw Object.assign(new Error('This manuscript preview is out of date. Refresh it and try again.'), { statusCode: 404 });

package/src/server/paths.ts

@@ -12,4 +12,4 @@ export const OWNER = process.env.PAPILOT_TAILSCALE_LOGIN || '';
 // port its proxy (such as Tailscale Funnel) forwards to.
 export const ACCOUNT_ORIGIN = (process.env.PAPILOT_ACCOUNT_ORIGIN || '').replace(/\/+$/, '');
 export const ACCOUNT_PORT = Number(process.env.PAPILOT_ACCOUNT_PORT || 7275);
-export const CODEX = process.env.PAPILOT_CODEX_BIN || (fs.existsSync(path.join(ROOT, 'node_modules/.bin/codex')) ? path.join(ROOT, 'node_modules/.bin/codex') : 'codex');
+export const CODEX = process.env.PAPILOT_CODEX_BIN || [path.join(ROOT, 'node_modules/.bin/codex'), path.join(DATA, 'agents/node_modules/.bin/codex')].find(file => fs.existsSync(file)) || 'codex';

package/src/server/references.ts

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { DATA, ENGINE } from './paths.ts';
+import type { BibliographyReport, ReferenceCheck } from '../shared.ts';
+
+// The paper's bibliography as it is on disk: every entry, where it is cited,
+// what is wrong with it without looking anything up, and, when asked, what
+// Crossref, DBLP and arXiv know of it. The review engine does the reading
+// and the checking; this is where Papilot asks it for a whole paper.
+
+type Input = { id: string; type: string; fields: Record<string, string> };
+interface Checker { lookup(inputs: Input[], start?: boolean, retry?: boolean): { checks: Record<string, ReferenceCheck>; pending: number } }
+interface Confirmations { of(inputs: Input[]): Record<string, number>; set(input: Input, on: boolean): void }
+interface Engine {
+  bibliographyReport(doc: { read(file: string): string | null; main: string; outline: unknown[] }): Omit<BibliographyReport, 'checks' | 'pending' | 'confirmed'>;
+  buildOutline(read: (file: string) => string | null, main: string): { nodes: unknown[] };
+  loadProject(root: string): { main: string };
+  checkInputs(references: unknown): Input[];
+  entryInputs(entries: unknown[]): Input[];
+  ReferenceChecker: new (file: string) => Checker;
+  Confirmations: new (file: string) => Confirmations;
+  Repo: new (root: string) => { gitDir(): string };
+}
+let loading: Promise<Engine> | undefined;
+export function engine(): Promise<Engine> {
+  const load = (file: string) => import(pathToFileURL(path.join(ENGINE, file)).href);
+  loading ??= Promise.all(['src/core/bib.ts', 'src/core/outline.ts', 'src/core/config.ts', 'src/core/verify.ts', 'src/core/git.ts'].map(load))
+    .then(modules => Object.assign({}, ...modules) as Engine);
+  return loading;
+}
+// One checker for Papilot's process, so that the panel and the review of
+// uncommitted changes share their results and their file.
+let shared: Checker | undefined;
+export async function checker(file = path.join(DATA, 'references.json')) {
+  const { ReferenceChecker } = await engine();
+  return shared ??= new ReferenceChecker(file);
+}
+// Confirmations live beside the review engine's state in the repository, so
+// a task's review, the uncommitted changes and this panel agree.
+export async function confirmations(root: string) {
+  const { Confirmations, Repo } = await engine();
+  return new Confirmations(path.join(new Repo(root).gitDir(), 'latex-review', 'references-confirmed.json'));
+}
+
+// A file of the paper, read only from inside its folder.
+function reader(root: string) {
+  const base = fs.realpathSync(root);
+  return (file: string) => {
+    const target = path.resolve(base, file);
+    if (target !== base && !target.startsWith(base + path.sep)) return null;
+    try { return fs.statSync(target).isFile() ? fs.readFileSync(target, 'utf8') : null; } catch { return null; }
+  };
+}
+async function report(root: string) {
+  const mods = await engine(), read = reader(root), { main } = mods.loadProject(root);
+  const result = mods.bibliographyReport({ read, main, outline: mods.buildOutline(read, main).nodes });
+  return { result, inputs: mods.entryInputs(result.entries) };
+}
+
+export async function bibliography(root: string, check: boolean, retry: boolean): Promise<BibliographyReport> {
+  const { result, inputs } = await report(root);
+  return { ...result, ...(await checker()).lookup(inputs, check, retry), confirmed: (await confirmations(root)).of(inputs) };
+}
+export async function confirmEntry(root: string, id: string, on: boolean) {
+  const { inputs } = await report(root), input = inputs.find(item => item.id === id);
+  if (!input) throw Object.assign(new Error('This entry is no longer in the bibliography. Refresh the panel.'), { statusCode: 404 });
+  (await confirmations(root)).set(input, on);
+  return bibliography(root, false, false);
+}

package/src/server/review.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { ENGINE } from './paths.ts';
 import type { Task } from '../shared.ts';
 
-export interface ReviewClient { url: string; token: string; get<T = any>(route: string): Promise<T>; post<T = any>(route: string, body?: unknown): Promise<T> }
+export interface ReviewClient { url: string; token: string; get<T = any>(route: string): Promise<T>; post<T = any>(route: string, body?: unknown, timeout?: number): Promise<T> }
 let modulePromise: Promise<{ connect: (root: string) => Promise<ReviewClient> }> | null = null;
 export function reviewClient(root: string): Promise<ReviewClient> {
   modulePromise ??= import(pathToFileURL(path.join(ENGINE, 'src/client.ts')).href);
@@ -41,8 +41,8 @@ export function annotateReviewState(value: unknown, tasks: readonly Task[]): unk
 
 export function allowedReviewRoute(route: string, method: string): boolean {
   if (route.includes('..') || route.includes('\\')) return false;
-  if (method === 'GET') return route === '/' || /^\/(assets|fonts)\/[\w./-]+$/.test(route) || /^\/files\/[a-z0-9-]+\/\d+\/[\w.-]+\.(svg|png)$/.test(route) || /^\/api\/tasks(?:\/[a-z0-9-]+(?:\/(?:state|rounds\/\d+(?:\/effects\/c\d+)?))?)?$/.test(route);
-  return method === 'POST' && /^\/api\/tasks\/[a-z0-9-]+\/(decide|undo|note)$/.test(route);
+  if (method === 'GET') return route === '/' || /^\/(assets|fonts)\/[\w./-]+$/.test(route) || /^\/files\/[a-z0-9-]+\/\d+\/[\w.-]+\.(svg|png)$/.test(route) || /^\/api\/tasks(?:\/[a-z0-9-]+(?:\/(?:state|rounds\/\d+(?:\/effects\/c\d+|\/references)?))?)?$/.test(route);
+  return method === 'POST' && /^\/api\/tasks\/[a-z0-9-]+\/(decide|undo|note|rounds\/\d+\/references\/confirm)$/.test(route);
 }
 export function rewriteReviewJson(value: any, prefix: string): any {
   if (Array.isArray(value)) return value.map(v => rewriteReviewJson(v, prefix));

package/src/server/skills.ts

@@ -3,6 +3,8 @@ import path from 'node:path';
 import os from 'node:os';
 import { ROOT } from './paths.ts';
 import type { Skill } from '../shared.ts';
+import { isSkillIcon } from '../skill-icons.ts';
+import { skillMetadata, skillInstructions } from '../skill-metadata.ts';
 
 // Skills are Markdown instructions an author runs with "/" in the composer.
 // Papilot ships some in skills/; ~/.papilot/skills/ adds the author's
@@ -33,14 +35,9 @@ export function skillFiles(dir: string): { id: string; file: string; folder?: st
 
 export function parseSkill(text: string, id: string, source: Skill['source'], folder?: string): SkillFile | null {
   text = text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
-  const header = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(text), fields: Record<string, string> = {};
-  for (const line of header?.[1].split('\n') || []) {
-    const field = /^([A-Za-z-]+):\s*(.*)$/.exec(line);
-    if (field) fields[field[1].toLowerCase()] = field[2].trim().replace(/^(['"])(.*)\1$/, '$2');
-  }
-  const body = text.slice(header ? header[0].length : 0).trim().slice(0, 20000);
+  const fields = skillMetadata(text), body = skillInstructions(text).trim().slice(0, 20000);
   if (!body) return null;
-  return { id, name: (fields.name || id).slice(0, 60), description: (fields.description || '').slice(0, 300), hint: (fields.hint || '').slice(0, 200), source, body, ...(folder ? { folder } : {}), order: fields.order && Number.isFinite(Number(fields.order)) ? Number(fields.order) : 1000 };
+  return { id, name: (fields.name || id).slice(0, 60), description: (fields.description || '').slice(0, 300), hint: (fields.hint || '').slice(0, 200), ...(isSkillIcon(fields.icon) ? { icon: fields.icon } : {}), source, body, ...(fields.output === 'annotations' ? { output: 'annotations' as const } : {}), ...(folder ? { folder } : {}), order: fields.order && Number.isFinite(Number(fields.order)) ? Number(fields.order) : 1000 };
 }
 
 function read(dir: string, source: Skill['source']): SkillFile[] {
@@ -67,4 +64,4 @@ export function findSkill(paper: string, id: string) {
   return skill;
 }
 
-export const listedSkill = ({ id, name, description, hint, source }: SkillFile): Skill => ({ id, name, description, hint, source });
+export const listedSkill = ({ id, name, description, hint, source, icon, output }: SkillFile): Skill => ({ id, name, description, hint, source, ...(icon ? { icon } : {}), ...(output ? { output } : {}) });