papilot 0.7.0 → 0.8.0

package/src/server/workspace.ts

@@ -1,13 +1,17 @@
+import { aiReviewInstructions, parseAiReview, reviewPrompt, REVIEW_AGENTS, type ReviewSnapshot } from './ai-review.ts';
 import { createHash, randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { EventEmitter } from 'node:events';
 import { Store } from './store.ts';
 import { Attachments } from './attachments.ts';
 import { Codex, RpcResponseError } from './codex.ts';
-import { AGENT_NAMES, AntigravityAgent, ClaudeAgent, type AgentRuntime } from './agents.ts';
+import { AGENT_NAMES, AntigravityAgent, ClaudeAgent, GlmAgent, type AgentRuntime } from './agents.ts';
+import { ACP_PROFILES, AcpAgent } from './acp.ts';
+import { CursorAgent } from './cursor.ts';
 import { reviewClient, taskRoute, confirmedReviewResponse, type ReviewClient } from './review.ts';
 import { VERSION } from './paths.ts';
 import { prepareRepository } from './imports.ts';
@@ -18,6 +22,7 @@ import { taskCaptionFrom, taskCaptionInstructions } from '../task-caption.ts';
 import { notesInstructions, reviewNotesInstructions, summarizeNotes } from '../notes.ts';
 import { canonicalGroup, groupsWithoutInstructions, parseGroupInstructions, type GroupInstructions } from '../note-groups.ts';
 import { commitChanges, conflictMarkers, gitCommit, gitRemote, gitStatus, mergeConflicts, mergeInProgress } from './manuscript.ts';
+import { AGENT_IDS, isTaskReviewNote } from '../shared.ts';
 import type { Task, Run, TimelineItem, PendingRequest, RuntimeStatus, Snapshot, PendingReview, AgentModel, Usage, AgentId, MessageMeta, FeedbackSummary, BuildFailure, Author, Annotation, NoteSummary } from '../shared.ts';
 
 const execute = promisify(execFile);
@@ -53,8 +58,26 @@ const BUSY = new Set(['running', 'waiting_input', 'building', 'uncertain', 'dele
 // publish.ts), and the request keys of the turns that send them back to it.
 const FIXABLE = /^(Some edits are outside the task scope|The revised document could not be compiled)/;
 const BUILD_FIX = 'build-fix-';
+// The tool Papilot gives Codex threads for looking at the typeset paper. The
+// review engine compiles the task worktree as it is and draws the pages.
+export const VIEW_PDF = 'view_pdf';
+export const VIEW_PDF_TOOL = {
+  type: 'function', name: VIEW_PDF,
+  description: 'Compile the paper in your task worktree as it is now and draw typeset pages as PNG files. Ask for the pages where source lines are typeset (locations, such as "main/chapters/intro.tex:42") or for page numbers as printed on the pages; up to 4 pages per call. The result lists each page\'s file: open the ones you need with your image viewer (view_image) to see them. Set accepted to true to draw the author\'s accepted text, before your edits, instead. Only the chapters needed are compiled when the paper allows it, but this can still take a minute or more.',
+  inputSchema: {
+    type: 'object', additionalProperties: false,
+    properties: {
+      locations: { type: 'array', items: { type: 'string' }, maxItems: 4, description: 'Source lines as file:line, relative to the worktree.' },
+      pages: { type: 'array', items: { type: 'string' }, maxItems: 4, description: 'Printed page numbers, such as "12" or "iv", when the PDF provides page labels. Use locations if numbering metadata is unavailable.' },
+      accepted: { type: 'boolean', description: 'Show the accepted text instead of your worktree.' },
+    },
+  },
+};
+const VIEW_PDF_UNSUPPORTED = /dynamicTools|experimental/i;
+// What a view_pdf call asked for, as the chat shows it.
+const viewedPlaces = (args: any) => [...(Array.isArray(args?.locations) ? args.locations : []), ...(Array.isArray(args?.pages) ? args.pages.map((page: unknown) => `p. ${page}`) : [])].filter(place => typeof place === 'string').join(', ') + (args?.accepted === true ? ' (accepted)' : '');
 
-const AGENTS: AgentId[] = ['codex', 'claude', 'antigravity'];
+const AGENTS: AgentId[] = AGENT_IDS;
 // The small model an agent offers for short text such as a commit message,
 // by the names agents give them (GPT Luna and mini, Claude Haiku, Gemini Flash).
 const LIGHT = /\b(?:luna|mini|nano|haiku|flash|lite)\b/i;
@@ -67,11 +90,13 @@ const blankRuntime = (): RuntimeStatus => ({ connected: false, authenticated: fa
 
 export class Workspace extends EventEmitter {
   // Each task runs on one agent; `runtime` is Codex's status, kept for older clients.
-  runtimes: Record<AgentId, RuntimeStatus> = { codex: blankRuntime(), claude: blankRuntime(), antigravity: blankRuntime() };
+  runtimes = Object.fromEntries(AGENTS.map(id => [id, blankRuntime()])) as Record<AgentId, RuntimeStatus>;
   runtime = this.runtimes.codex;
   agents: Record<AgentId, AgentRuntime>;
   requests = new Map<string, PendingRequest & { rpcId: string | number; agent: AgentId }>();
   private active = new Map<string, Run>();
+  // Async tools must never answer a request from an earlier connection.
+  private connectionEpochs = new Map<AgentId, number>();
   private loaded = new Set<string>();
   private preparing = new Set<string>();
   private preparingNotes = new Set<string>();
@@ -94,6 +119,8 @@ export class Workspace extends EventEmitter {
   private messages = new Map<string, Promise<{ message: string; agent: AgentId }>>();
   private titles = new Map<string, Promise<Task | null>>();
   private helperStops = new Set<() => void>();
+  // Set when Codex refuses the view_pdf tool, so later threads start without it.
+  private noViewPdf = false;
   private projectChanges = new Set<string>();
   private projectRequests = new Map<string, number>();
   importsBusy = () => false;
@@ -105,7 +132,9 @@ export class Workspace extends EventEmitter {
   constructor(public store: Store, public codex: AgentRuntime = new Codex(), private concurrency = 2, private connectReview = reviewClient, others: Partial<Record<AgentId, AgentRuntime>> = {}) {
     super();
     this.attachments = new Attachments(store);
-    this.agents = { codex, claude: others.claude || new ClaudeAgent(), antigravity: others.antigravity || new AntigravityAgent() };
+    this.agents = { codex, claude: others.claude || new ClaudeAgent(), cursor: others.cursor || new CursorAgent(), antigravity: others.antigravity || new AntigravityAgent(),
+      kimi: others.kimi || new AcpAgent(ACP_PROFILES.kimi), glm: others.glm || new GlmAgent(), deepseek: others.deepseek || new AcpAgent(ACP_PROFILES.deepseek),
+      qwen: others.qwen || new AcpAgent(ACP_PROFILES.qwen), opencode: others.opencode || new AcpAgent(ACP_PROFILES.opencode) };
     store.on('change', () => this.emit('change'));
     for (const id of AGENTS) {
       const agent = this.agents[id];
@@ -116,6 +145,7 @@ export class Workspace extends EventEmitter {
   }
   private agentOf(task: Task): AgentId { return task.agent && AGENTS.includes(task.agent) ? task.agent : 'codex'; }
   private disconnected(id: AgentId, e: unknown) {
+    this.connectionEpochs.set(id, (this.connectionEpochs.get(id) || 0) + 1);
     this.runtimes[id].connected = false; this.runtimes[id].error = errorText(e);
     for (const [key, request] of this.requests) if (request.agent === id) this.requests.delete(key);
     for (const [taskId, run] of this.active) {
@@ -137,6 +167,10 @@ export class Workspace extends EventEmitter {
   }
   private async connectAgent(id: AgentId) {
     const agent = this.agents[id], runtime = this.runtimes[id], name = AGENT_NAMES[id];
+    // An agent that is not on this host is neither started nor offered;
+    // Reconnect looks again. A running agent stays connected.
+    runtime.installed = agent.ready || !agent.detect || agent.detect();
+    if (!runtime.installed) { Object.assign(runtime, blankRuntime(), { installed: false }); return; }
     try {
       await agent.start();
       const account = await agent.request('account/read', { refreshToken: false });
@@ -236,12 +270,14 @@ export class Workspace extends EventEmitter {
   }
   // A task combines the author's words, an optional skill and selected PDF notes.
   annotationSending(id: string) { return this.preparingNotes.has(id); }
-  async createTask(input: { projectId: string; title: string; instructions: string; skill?: string; annotations?: string[]; groupInstructions?: GroupInstructions; attachments?: string[]; agent?: AgentId; model?: string; effort?: string; serviceTier?: string; id: string; author?: Author }) {
+  async createTask(input: { reviewInput?: ReviewSnapshot; prepareReview?: (worktree: string) => Promise<ReviewSnapshot>; projectId: string; title: string; instructions: string; skill?: string; annotations?: string[]; groupInstructions?: GroupInstructions; attachments?: string[]; agent?: AgentId; model?: string; effort?: string; serviceTier?: string; id: string; author?: Author }) {
     if (!/^[\w-]{16,64}$/.test(input.id)) throw new Error('Invalid task ID.');
     if (this.store.taskDeleted(input.id)) throw new Error('This task was deleted. Create a new task instead.');
     // A retried request returns its task; an ID from another paper is refused.
     const existing = this.store.tasks().find(t => t.id === input.id);
-    if (existing) { if (existing.projectId !== input.projectId) throw new Error('Invalid task ID.'); return existing; }
+    if (existing) { if (existing.projectId !== input.projectId || (existing.mode === 'review') !== Boolean(input.reviewInput)) throw new Error('Invalid task ID.'); return existing; }
+    if (input.reviewInput && !REVIEW_AGENTS.includes(input.agent || 'codex')) throw new Error('Choose Codex, Claude or GLM for AI review.');
+    if (input.reviewInput && (input.annotations?.length || input.attachments?.length)) throw new Error('AI review uses the manuscript PDF. Start a separate editing task to send notes or attachments.');
     if (input.serviceTier !== undefined) {
       if (input.agent && input.agent !== 'codex') throw new Error('Service tiers are only available for Codex.');
       const models = this.runtimes.codex.models;
@@ -254,9 +290,10 @@ export class Workspace extends EventEmitter {
     let releaseAttachments = () => {};
     try {
       const project = this.store.project(input.projectId), skill = input.skill ? findSkill(project.path, input.skill) : undefined;
+      if (skill?.output === 'annotations' && !input.reviewInput) throw new Error('Start a new task to run the AI review skill on the current PDF.');
       const files = this.attachments.resolve(project.id, input.attachments || [], input.author?.id || 'owner', input.id);
       releaseAttachments = this.attachments.reserve(project.id, input.attachments || [], input.author?.id || 'owner', input.id);
-      const available = new Map(this.store.annotations(project.id).filter(note => !note.taskId).map(note => [note.id, note]));
+      const available = new Map(this.store.annotations(project.id).filter(note => !note.taskId && !isTaskReviewNote(note)).map(note => [note.id, note]));
       notes = [...new Set(input.annotations || [])].map(id => {
         const note = available.get(id);
         if (!note) throw new Error('A selected PDF note is no longer available. Refresh the manuscript and try again.');
@@ -268,16 +305,20 @@ export class Workspace extends EventEmitter {
       if (Object.keys(groupInstructions).some(group => !selectedGroups.has(group as keyof GroupInstructions))) throw new Error('Group instructions must refer to selected PDF notes.');
       if (groupsWithoutInstructions(notes, groupInstructions).length && !input.instructions.trim() && !skill) throw new Error('Describe what to do with each selected color group.');
       claimed = notes.map(note => note.id); claimed.forEach(id => this.preparingNotes.add(id));
-      if (!skill && !notes.length && !files.length && !input.instructions.trim()) throw new Error('Describe the revision, choose a skill, or add a PDF note.');
+      if (!input.reviewInput && !skill && !notes.length && !files.length && !input.instructions.trim()) throw new Error('Describe the revision, choose a skill, or add a PDF note.');
       const instructions = notes.length ? notesInstructions(notes, input.instructions, groupInstructions) : input.instructions;
       const client = await this.connectReview(project.path);
       const name = 'p-' + input.id.toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 48);
       const info = await client.post('/api/tasks', { name, title: input.title, deferred: true });
-      const task: Task = { id: input.id, projectId: project.id, name, title: input.title, titleSource: 'prompt', instructions: skill ? skillPrompt(skill, instructions) : instructions,
+      const reviewInput = input.reviewInput && (input.prepareReview ? await input.prepareReview(info.worktree) : input.reviewInput);
+      const task: Task = { ...(reviewInput ? { mode: 'review' as const, aiReview: { key: reviewInput.key } } : {}), id: input.id, projectId: project.id, name, title: input.title, titleSource: 'prompt', instructions: skill ? skillPrompt(skill, instructions) : instructions,
         worktree: info.worktree, deferred: info.deferred === true, threadId: null, turnId: null, agent: input.agent || 'codex', model: input.model || null, effort: input.effort || null, ...(input.serviceTier ? { serviceTier: input.serviceTier } : {}), status: 'idle',
         createdAt: Date.now(), updatedAt: Date.now(), feedbackCursor: 0, error: null, review: null };
-      this.store.saveTask(task);
-      await this.enqueue(task.id, input.instructions, 'initial-' + task.id, false, { skill, notes, groupInstructions, attachments: files.map(file => file.id), author: input.author });
+      this.store.transaction(() => {
+        this.store.saveTask(task);
+        if (reviewInput) this.store.saveReviewInput(task.id, reviewInput);
+      });
+      await this.enqueue(task.id, input.instructions || (input.reviewInput && !skill ? 'Review this manuscript and suggest improvements.' : ''), 'initial-' + task.id, false, { skill, notes, groupInstructions, attachments: files.map(file => file.id), author: input.author });
       // Naming is independent of the editing turn. An unavailable helper must
       // not fail creation or prevent the queued task from running.
       try { this.requestTaskTitle(task.id); } catch { /* Keep the prompt-derived title. */ }
@@ -290,6 +331,8 @@ export class Workspace extends EventEmitter {
   async enqueue(taskId: string, text: string, requestKey: string, includeFeedback = true, options: { attachments?: string[]; skill?: SkillFile; notes?: Annotation[]; groupInstructions?: GroupInstructions; reviewNotes?: NoteSummary[]; feedback?: boolean; build?: BuildFailure; author?: Author } = {}) {
     const task = this.store.task(taskId);
     if (task.status === 'deleting') throw new Error('This task is being deleted.');
+    if (task.mode === 'review' && ((options.skill && options.skill.output !== 'annotations') || options.notes?.length || options.reviewNotes?.length || options.attachments?.length || options.feedback || options.build)) throw new Error('AI review accepts review instructions only. Start an editing task to send notes, skills or attachments.');
+    if (task.mode !== 'review' && options.skill?.output === 'annotations') throw new Error('Start a new task to run the AI review skill on the current PDF.');
     const existing = this.store.runByKey(requestKey);
     if (existing) { if (existing.taskId !== taskId) throw new Error('This request ID is already in use by another task.'); return existing; }
     if (task.status === 'uncertain') throw new Error('Check the task status before sending more instructions.');
@@ -301,6 +344,7 @@ export class Workspace extends EventEmitter {
     const instructions = options.notes?.length ? notesInstructions(options.notes, text, options.groupInstructions) : options.reviewNotes?.length ? reviewNotesInstructions(options.reviewNotes, text) : text.trim();
     let prompt = options.build ? buildFixPrompt(options.build) : options.feedback ? reviewInstructions : options.skill ? skillPrompt(options.skill, instructions) : instructions, cursor = task.feedbackCursor;
     let summary: FeedbackSummary | undefined;
+    if (task.mode === 'review') includeFeedback = false;
     if (includeFeedback) {
       const client = await this.connectReview(this.store.project(task.projectId).path);
       const feedback = await client.get(`${taskRoute(task.name)}/feedback?after=${task.feedbackCursor}`);
@@ -310,8 +354,9 @@ export class Workspace extends EventEmitter {
       if (task.error) prompt += '\n\nLatest task/review error:\n' + task.error + '\nThe latest accepted manuscript is at ' + this.store.project(task.projectId).path + '. You may read it to understand accepted changes, but must only edit your isolated task worktree. Prepare a revised proposal for another review; never write to or accept changes in the manuscript checkout.';
     }
     if (files.length) prompt = (prompt || 'The user attached reference material without an instruction. Briefly identify the material and ask what they would like to do with it. Do not change the manuscript yet.') + this.attachments.prompt(files);
+    if (task.mode === 'review') prompt = reviewPrompt(prompt, this.store.reviewInput(taskId));
     const run: Run = { id: randomUUID(), taskId, requestKey, prompt, ...(files.length ? { attachments: files } : {}), feedbackCursor: cursor, status: 'queued', createdAt: Date.now(), finishedAt: null, reviewRound: 0 };
-    const meta: MessageMeta = { ...(options.skill ? { skill: { id: options.skill.id, name: options.skill.name } } : {}), ...(options.notes?.length ? { notes: summarizeNotes(options.notes) } : options.reviewNotes?.length ? { notes: options.reviewNotes } : {}), ...(summary ? { feedback: summary } : {}), ...(options.feedback ? { sendsFeedback: true } : {}), ...(options.build ? { build: options.build } : {}), ...(options.author ? { author: options.author } : {}) };
+    const meta: MessageMeta = { ...(options.skill ? { skill: { id: options.skill.id, name: options.skill.name, ...(options.skill.icon ? { icon: options.skill.icon } : {}) } } : {}), ...(options.notes?.length ? { notes: summarizeNotes(options.notes) } : options.reviewNotes?.length ? { notes: options.reviewNotes } : {}), ...(summary ? { feedback: summary } : {}), ...(options.feedback ? { sendsFeedback: true } : {}), ...(options.build ? { build: options.build } : {}), ...(options.author ? { author: options.author } : {}) };
     if (options.groupInstructions && Object.keys(options.groupInstructions).length) meta.groupInstructions = options.groupInstructions;
     const saved = this.store.transaction(() => {
       // Feedback loading yields to other requests. Recheck identity, queue, and
@@ -334,6 +379,8 @@ export class Workspace extends EventEmitter {
       this.store.saveRun(run);
       for (const note of options.notes || []) this.store.saveAnnotation({ ...note, taskId });
       if (!BUSY.has(current.status)) this.store.updateTask(taskId, { status: 'queued', error: null });
+      // Writing to an archived task brings it back to the task list.
+      if (current.archivedAt && !options.build) this.store.updateTask(taskId, { archivedAt: null });
       this.store.saveItem({ id: run.id, taskId, type: 'user', text: options.feedback || options.build ? '' : text.trim(), createdAt: run.createdAt, ...(Object.keys(meta).length ? { meta } : {}) });
       return run;
     });
@@ -365,14 +412,16 @@ export class Workspace extends EventEmitter {
       return files.some(file => file === '' || file === '.') ? [] : files;
     } catch { return []; }
   }
-  private instructions(task: Task, scope: string[] = []) {
+  private instructions(task: Task, scope: string[] = [], viewPdf = false) {
+    if (task.mode === 'review') return aiReviewInstructions + '\n\nOriginal review skill and request:\n' + task.instructions;
     return `You are ${this.agentOf(task) === 'codex' ? 'the official Codex agent' : AGENT_NAMES[this.agentOf(task)]} running inside Papilot, a paper editing and review workspace.
 Your task is already created. Your editable working directory is ${task.worktree}.
 Original task: ${task.instructions}
 Only edit this isolated task worktree. Never edit the manuscript checkout, other task worktrees, or Papilot's own source/state. Never commit, push, stash, or accept/reject/undo review decisions.
 ${scope.length ? `The review covers only ${scope.join(', ')} in this worktree, and an edit to any other file stops the PDF build. Leave other files unchanged even when project instructions ask for a matching update; mention that update in your summary instead.\n` : ''}Papilot owns the LaTeX review lifecycle: it compiles and publishes automatically AFTER your turn finishes, and delivers review feedback in a new turn. Do not create another review task, invoke publish, or wait on feedback --wait. This application workflow replaces the standalone latex-review skill's publish-and-wait loop. End your turn after completing the requested edits, with a concise summary for the author of what you changed and why; do not describe Papilot's review workflow.
 Preserve meaning and mathematical correctness. Read relevant project instructions. Treat reviewer comments as instructions tied to their round, file and changes. Rejected edits must not be reintroduced unless explicitly requested. If there is a conflict with accepted text, explain it and propose a revision for a new review round; never overwrite the accepted manuscript.
-${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to you here and any attempt is refused, which ends your turn: read, search and edit files in the task worktree with your file tools only.' : 'You may run tools in the task worktree to inspect and validate your changes.'} If a decision requires the user, ask through the available user-input tool or explain it in your final response. Use English for your progress updates, questions, and final summaries unless the user explicitly requests another language. Preserve the manuscript language unless asked to translate it.`;
+Never invent a bibliography entry or any of its details. Add a .bib entry only for a work you can identify, take its authors, title, year and venue from the published record, and include its doi or arXiv eprint when it has one. Papilot looks up every added or changed entry in Crossref, DBLP and arXiv and shows the author any it cannot confirm. Name the entries you added or changed in your summary.
+${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to you here and any attempt is refused, which ends your turn: read, search and edit files in the task worktree with your file tools only.' : 'You may run tools in the task worktree to inspect and validate your changes.'} ${viewPdf ? `When the look of the pages matters, such as line breaks, spacing, figures, tables or displayed formulas, use the ${VIEW_PDF} tool and open the pages it draws with your image viewer to see them as the author does. It compiles the paper, so do not call it for wording alone. ` : ''}If a decision requires the user, ask through the available user-input tool or explain it in your final response. Use English for your progress updates, questions, and final summaries unless the user explicitly requests another language. Preserve the manuscript language unless asked to translate it.`;
   }
   private async startRun(run: Run) {
     let task = this.store.task(run.taskId);
@@ -384,12 +433,23 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
     this.store.saveRun({ ...run, status: 'running' });
     this.store.updateTask(task.id, { status: 'running', turnId: null, error: null });
     if (!task.threadId || !this.loaded.has(task.threadId)) {
-      const options = { cwd: task.worktree, approvalPolicy: 'on-request', sandbox: 'workspace-write', developerInstructions: this.instructions(task, await this.reviewScope(task)), ...(task.model ? { model: task.model } : {}) };
-      const result = task.threadId
-        ? await agent.request('thread/resume', { ...options, threadId: task.threadId, excludeTurns: true })
-        : await agent.request('thread/start', options);
+      // Codex threads get the view_pdf tool when they start, and keep it when resumed.
+      const scope = task.mode === 'review' ? [] : await this.reviewScope(task), codex = this.agentOf(task) === 'codex';
+      let viewPdf = task.mode !== 'review' && codex && (task.threadId ? Boolean(task.viewPdf) : !this.noViewPdf);
+      const options = (tool: boolean) => ({ cwd: task.worktree, approvalPolicy: task.mode === 'review' ? 'never' : 'on-request', sandbox: task.mode === 'review' ? 'read-only' : 'workspace-write', developerInstructions: this.instructions(task, scope, tool), ...(task.model ? { model: task.model } : {}) });
+      let result;
+      if (task.threadId) result = await agent.request('thread/resume', { ...options(viewPdf), threadId: task.threadId, excludeTurns: true });
+      else {
+        try { result = await agent.request('thread/start', viewPdf ? { ...options(true), dynamicTools: [VIEW_PDF_TOOL] } : options(false)); }
+        catch (error) {
+          // A Codex without the experimental tool API starts its threads without it.
+          if (!viewPdf || !(error instanceof RpcResponseError) || !VIEW_PDF_UNSUPPORTED.test(error.message)) throw error;
+          this.noViewPdf = true; viewPdf = false;
+          result = await agent.request('thread/start', options(false));
+        }
+      }
       if (this.active.get(task.id)?.id !== run.id) return;
-      task = this.store.updateTask(task.id, { threadId: result.thread.id, model: result.model || task.model });
+      task = this.store.updateTask(task.id, { threadId: result.thread.id, model: result.model || task.model, ...(task.threadId ? {} : { viewPdf }) });
       this.loaded.add(result.thread.id);
     }
     this.store.updateTask(task.id, { pendingRunId: run.id });
@@ -453,7 +513,7 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
     if (!task || task.status === 'deleting') return;
     const eventTurn = p.turnId || p.turn?.id;
     if (eventTurn && task.turnId && eventTurn !== task.turnId) return;
-    if (method === 'item/agentMessage/delta') this.appendDelta(task, p, 'assistant');
+    if (method === 'item/agentMessage/delta') { if (task.mode !== 'review') this.appendDelta(task, p, 'assistant'); }
     else if (method === 'item/commandExecution/outputDelta') this.appendDelta(task, p, 'command');
     else if ((method === 'item/started' || method === 'item/completed') && p.item) {
       const item = p.item, id = `${task.id}:${p.turnId}:${item.id}`;
@@ -461,11 +521,16 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
       this.flush();
       const previous = this.store.items(task.id).find(i => i.id === id);
       const entry: TimelineItem = { id, taskId: task.id, createdAt: previous?.createdAt || Date.now(), type: item.type, text: item.text || item.command || '', status: item.status || (method === 'item/completed' ? 'completed' : 'inProgress') };
-      if (item.type === 'agentMessage') entry.type = 'assistant';
+      if (item.type === 'agentMessage') entry.type = task.mode === 'review' ? 'reviewOutput' : 'assistant';
       if (item.type === 'commandExecution') { entry.type = 'command'; entry.detail = String(item.aggregatedOutput || previous?.detail || '').slice(-40000); }
       if (item.type === 'fileChange') { entry.type = 'files'; entry.text = (item.changes || []).map((change: any) => change.path).join('\n'); }
       if (item.type === 'mcpToolCall') { entry.type = 'tool'; entry.text = `${item.server} / ${item.tool}`; }
       if (item.type === 'toolCall') entry.type = 'tool';
+      if (item.type === 'dynamicToolCall') {
+        if (item.tool !== VIEW_PDF) { entry.type = 'tool'; entry.text = item.tool || ''; }
+        else { entry.type = 'pdf'; entry.text = viewedPlaces(item.arguments); }
+        if (item.success === false) entry.status = 'failed';
+      }
       if (entry.text || entry.detail) this.store.saveItem(entry);
     } else if (method === 'serverRequest/resolved') {
       const buffered = this.earlyRequests.get(task.id);
@@ -491,7 +556,10 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
       this.store.saveRun({ ...run, status, finishedAt: Date.now() });
       this.store.updateTask(task.id, { turnId: null, pendingRunId: null, status: status === 'completed' ? 'building' : status, error: p.turn.error?.message || null });
       this.schedule();
-      if (status === 'completed') await this.publish(task.id, run);
+      if (status === 'completed') {
+        if (task.mode === 'review') this.finishAiReview(task, run, eventTurn);
+        else await this.publish(task.id, run);
+      }
     } else if (method === 'error' && !p.willRetry) {
       if (!this.active.has(task.id) || (eventTurn && !task.turnId)) return;
       this.store.updateTask(task.id, { error: p.error?.message || `${AGENT_NAMES[agent]} encountered an error.` });
@@ -499,7 +567,7 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
   }
   private serverRequest(message: any, agent: AgentId = 'codex') {
     const task = this.store.tasks().find(t => t.threadId === message.params?.threadId), runtime = this.agents[agent];
-    const allowed = ['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'item/tool/requestUserInput'];
+    const allowed = ['item/commandExecution/requestApproval', 'item/fileChange/requestApproval', 'item/permissions/requestApproval', 'item/tool/requestUserInput', 'item/tool/call'];
     if (!task || this.agentOf(task) !== agent || !this.active.has(task.id) || !allowed.includes(message.method)) { runtime.reject(message.id, 'This request is not supported or its turn is no longer active.'); return; }
     if (message.params?.turnId && task.turnId && message.params.turnId !== task.turnId) { runtime.reject(message.id, 'This turn is no longer active.'); return; }
     if (!task.turnId && message.params?.turnId) {
@@ -508,10 +576,50 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
       else runtime.reject(message.id, 'Too many pending requests.');
       return;
     }
+    if (task.mode === 'review') { runtime.reject(message.id, 'AI review is read-only and cannot request tools or additional permissions.'); return; }
+    // Papilot answers its own tools; the author is not asked.
+    if (message.method === 'item/tool/call') {
+      void this.toolCall(task, message, runtime).catch(error => console.error(`${AGENT_NAMES[agent]} tool:`, errorText(error)));
+      return;
+    }
     const id = randomUUID();
     this.requests.set(id, { id, taskId: task.id, rpcId: message.id, agent, method: message.method, params: message.params, createdAt: Date.now() });
     this.store.updateTask(task.id, { status: 'waiting_input' });
   }
+  // The agent looks at typeset pages: the review engine compiles the task
+  // worktree and draws them as files, which the agent opens with its own
+  // image viewer. Returning the images themselves would put them in front of
+  // Codex's code mode as base64 text.
+  private async toolCall(task: Task, message: any, runtime: AgentRuntime) {
+    const { tool, arguments: args } = message.params || {};
+    const agent = this.agentOf(task), run = this.active.get(task.id), epoch = this.connectionEpochs.get(agent);
+    const current = () => !this.closing && runtime.ready && this.agents[agent] === runtime
+      && this.connectionEpochs.get(agent) === epoch && run && this.active.get(task.id)?.id === run.id
+      && this.store.task(task.id).turnId === task.turnId;
+    const reply = (success: boolean, text: string) => {
+      if (!current()) return;
+      // A failed transport cannot receive an error reply either. Do not let
+      // it escape this detached async call or retry it against a new child.
+      try { runtime.respond(message.id, { success, contentItems: [{ type: 'inputText', text }] }); }
+      catch (error) { console.error(`${AGENT_NAMES[agent]} tool reply:`, errorText(error)); }
+    };
+    if (tool !== VIEW_PDF) { reply(false, `Papilot has no tool named ${tool}.`); return; }
+    const strings = (value: unknown) => Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string').slice(0, 4) : [];
+    try {
+      const client = await this.connectReview(this.store.project(task.projectId).path);
+      if (!current()) return;
+      const shown = await client.post<{ pages: { index: number; label: string | null; shows: string[]; file: string }[]; missing: string[]; targets: string[]; error?: string; details?: string[] }>(
+        `${taskRoute(task.name)}/view`, { locations: strings(args?.locations), pages: strings(args?.pages), ...(args?.accepted === true ? { accepted: true } : {}) }, 30 * 60000);
+      if (shown.error) { reply(false, [shown.error, ...(shown.details || [])].join('\n')); return; }
+      const compiled = shown.targets[0] === 'full' ? 'the whole paper' : `only ${shown.targets.join(', ')}, so page positions differ from the full PDF while printed page numbers match`;
+      reply(true, [
+        `${args?.accepted === true ? 'The accepted text' : 'Your worktree'} was compiled (${compiled}).`,
+        ...shown.pages.map(page => `${page.label ? `Page ${page.label}` : `PDF page ${page.index} (printed page number unavailable)`} shows ${page.shows.join(', ')}: ${page.file}`),
+        ...shown.missing,
+        ...(shown.pages.length ? ['Open the page files you need with your image viewer (view_image).'] : []),
+      ].join('\n'));
+    } catch (error) { reply(false, 'Papilot could not show the pages: ' + errorText(error)); }
+  }
   answer(id: string, input: { decision?: string; answers?: Record<string, string> }) {
     const request = this.requests.get(id); if (!request) throw new Error('This request has ended or the connection has restarted.');
     if (this.store.task(request.taskId).status === 'deleting') throw new Error('This task is being deleted.');
@@ -520,6 +628,8 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
       const questions = request.params.questions || [];
       response = { answers: Object.fromEntries(questions.map((q: any) => {
         const answer = input.answers?.[q.id]?.trim(); if (!answer) throw new Error('Answer every question before submitting.');
+        // A question without an "Other" choice only takes one of its options.
+        if (q.isOther === false && q.options?.length && !q.options.some((option: any) => option.label === answer)) throw new Error('Choose one of the offered answers.');
         return [q.id, { answers: [answer] }];
       })) };
     } else {
@@ -561,6 +671,10 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
     this.earlyCompletions.delete(taskId);
     this.active.set(taskId, run);
     this.store.updateTask(taskId, { turnId: turn.id, pendingRunId: null, error: null, feedbackCursor: Math.max(task.feedbackCursor, run.feedbackCursor || 0) });
+    // Recover the structured review reply when the completion notification was lost.
+    if (task.mode === 'review' && turn.status === 'completed') for (const item of turn.items || []) {
+      if (item.type === 'agentMessage') await this.notification({ method: 'item/completed', params: { threadId: task.threadId, turnId: turn.id, item } }, this.agentOf(task));
+    }
     if (completion) {
       await this.notification(completion, this.agentOf(task));
     } else if (turn.status === 'inProgress' && thread.status?.type !== 'notLoaded') {
@@ -593,6 +707,7 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
   async reviewWrite<T>(taskId: string, writesFiles: boolean, operation: () => Promise<T>, pending?: Omit<PendingReview, 'previousStatus'>): Promise<T> {
     const task = this.store.task(taskId);
     if (task.status === 'deleting') throw new Error('This task is being deleted.');
+    if (task.mode === 'review') throw new Error('AI review uses manuscript PDF notes, not change decisions.');
     if (!writesFiles) {
       this.commentWrites.set(taskId, (this.commentWrites.get(taskId) || 0) + 1);
       try { return await operation(); }
@@ -621,6 +736,7 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
   // edits break the build, the agent gets the error in a new turn, once.
   publish(taskId: string, after?: Run): Promise<void> {
     const task = this.store.task(taskId), automatic = Boolean(after);
+    if (task.mode === 'review') throw new Error('AI review creates PDF notes only. It cannot publish manuscript changes.');
     if (task.status === 'deleting') throw new Error('This task is being deleted.');
     if (this.active.has(taskId)) throw new Error('Pause Codex before building a review.');
     if (this.reviewWrites.has(taskId)) throw new Error('Wait for the current review action before building a review.');
@@ -661,10 +777,33 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
       await this.refresh(taskId);
     } catch (e) { this.store.updateTask(taskId, { status: 'failed', error: errorText(e) }); }
   }
+  private finishAiReview(task: Task, run: Run, turnId: string) {
+    try {
+      const snapshot = this.store.reviewInput(task.id);
+      const reply = this.store.items(task.id).filter(item => item.type === 'reviewOutput' && item.id.startsWith(`${task.id}:${turnId}:`)).at(-1);
+      const result = parseAiReview(reply?.text || '', snapshot);
+      this.store.transaction(() => {
+        result.notes.forEach((note, index) => {
+          const id = `${run.id}-${index}`;
+          // Deterministic IDs make completion replay safe, including deleted/sent notes.
+          try { this.store.annotation(task.projectId, id); return; } catch { /* New finding. */ }
+          this.store.saveAnnotation({ ...note, id, projectId: task.projectId, key: snapshot.key, source: null, createdAt: Date.now(), aiReview: { taskId: task.id, agent: this.agentOf(task) } });
+        });
+        this.store.saveRun({ ...run, status: 'completed', finishedAt: Date.now(), reviewRound: null });
+        if (reply) this.store.saveItem({ ...reply, type: 'assistant', text: result.summary });
+        const review = this.store.task(task.id).aiReview;
+        this.store.updateTask(task.id, { status: this.store.runs().some(r => r.taskId === task.id && r.status === 'queued') ? 'queued' : 'reviewing', error: null, aiReview: { ...review, key: snapshot.key, notes: (review?.notes || 0) + result.notes.length }, review: { state: 'done', round: null, counts: {}, unsent: 0, comments: 0, files: [] } });
+      });
+    } catch (error) {
+      this.store.updateTask(task.id, { status: 'failed', error: errorText(error) });
+    }
+    this.schedule();
+  }
   async refresh(taskId: string) {
     let release: (() => void) | undefined;
     try {
       const task = this.store.task(taskId);
+      if (task.mode === 'review') return;
       release = this.enterProjectRequest(task.projectId);
       if (task.status === 'deleting') return;
       const project = this.store.project(task.projectId), client = await this.connectReview(project.path);
@@ -693,7 +832,7 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
   private helper(choice: { agent?: AgentId; model?: string }, task: string, light = false) {
     const usable = (id: AgentId) => this.agents[id].ready && this.runtimes[id].authenticated;
     const id = choice.agent && usable(choice.agent) ? choice.agent : AGENTS.find(usable);
-    if (!id) throw new Error(`Sign in to Codex, Claude or Antigravity to ${task}.`);
+    if (!id) throw new Error(`Sign in to an agent, such as Codex, to ${task}.`);
     const models = this.runtimes[id].models;
     return { id, model: (light ? lightModel(models) : undefined) || models.find(item => item.id === choice.model) || models.find(item => item.isDefault) };
   }
@@ -707,6 +846,14 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
   // reply is returned and no chat shows it.
   private async oneOff(id: AgentId, options: { cwd: string; sandbox: 'read-only' | 'workspace-write'; instructions: string; prompt: string; model?: AgentModel; effort?: string | null; timeout: number; what: string }) {
     if (this.closing) throw new Error('The server is shutting down.');
+    // A read-only helper (a title, a commit message) has everything in its
+    // prompt. It runs in an empty folder, so an agent that does not enforce a
+    // read-only sandbox (Claude, Cursor, the ACP agents) cannot change the paper.
+    const scratch = options.sandbox === 'read-only' ? fs.mkdtempSync(path.join(os.tmpdir(), 'papilot-helper-')) : null;
+    try { return await this.helperTurn(id, { ...options, cwd: scratch || options.cwd }); }
+    finally { if (scratch) fs.rmSync(scratch, { recursive: true, force: true }); }
+  }
+  private async helperTurn(id: AgentId, options: { cwd: string; sandbox: 'read-only' | 'workspace-write'; instructions: string; prompt: string; model?: AgentModel; effort?: string | null; timeout: number; what: string }) {
     const agent = this.agents[id], name = AGENT_NAMES[id];
     const thread = await agent.request('thread/start', { cwd: options.cwd, approvalPolicy: 'never', sandbox: options.sandbox, ephemeral: true, developerInstructions: options.instructions, ...(options.model ? { model: options.model.id } : {}) }, options.timeout);
     if (this.closing) throw new Error('The server is shutting down.');
@@ -821,6 +968,7 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
   }
   async deliverTask(taskId: string, mode: 'workspace' | 'branch', message = '') {
     const task = this.store.task(taskId), project = this.store.project(task.projectId);
+    if (task.mode === 'review') throw new Error('AI review has no manuscript changes to deliver.');
     if (!task.deferred) throw new Error('This task already applies accepted changes to the working directory.');
     if (task.status !== 'reviewing' || this.active.has(taskId) || this.publishing.has(taskId) || task.pendingReview || this.store.runs().some(run => run.taskId === taskId && run.status === 'queued'))
       throw new Error('Wait for the task and review actions to finish before choosing a destination.');
@@ -872,11 +1020,15 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
       const paths = (await gitStatus(project.path)).files.filter(file => files.includes(file.path)).map(file => file.path);
       if (!paths.length) throw new Error('This task has no accepted changes left to commit.');
       const hash = await gitCommit(project.path, message, paths);
-      this.store.updateTask(taskId, { committed: { hash, accepted: accepted!, at: Date.now() } });
-      void this.refresh(taskId);
+      const committed = { hash, accepted: accepted!, at: Date.now() };
+      this.store.updateTask(taskId, { committed });
       // The commit stands even when the push fails; the author can push again.
       let pushError: string | undefined;
-      if (push) try { await gitRemote(project.path, 'push'); } catch (error) { pushError = errorText(error); }
+      if (push) try {
+        await gitRemote(project.path, 'push');
+        this.store.updateTask(taskId, { committed: { ...committed, pushed: true } });
+      } catch (error) { pushError = errorText(error); }
+      await this.refresh(taskId);
       return { commit: hash, git: await gitStatus(project.path), ...(pushError ? { pushError } : {}) };
     });
   }
@@ -893,11 +1045,13 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
     if (task.status === 'deleting') throw new Error('This task is being deleted.');
     return this.store.updateTask(taskId, { title, titleSource: 'manual', titleRevision: (task.titleRevision || 0) + 1, titleGeneration: null });
   }
-  archiveTask(taskId: string, archived: boolean) {
+  // Older tabs send finished=true when navigating away. Ignore those requests;
+  // only an explicit archive action should change the task list.
+  archiveTask(taskId: string, archived: boolean, finished = false) {
     if (typeof archived !== 'boolean') throw new Error('Choose whether to archive or restore the task.');
     const task = this.store.task(taskId);
     if (task.status === 'deleting') throw new Error('This task is being deleted.');
-    if (Boolean(task.archivedAt) === archived) return task;
+    if (Boolean(task.archivedAt) === archived || (archived && finished)) return task;
     // Archiving only organizes the list; the conversation, review and any run remain intact.
     return this.store.updateTask(taskId, { archivedAt: archived ? Date.now() : null });
   }