papergod 0.1.0

package/src/server/agent-errors.js

@@ -0,0 +1,105 @@
+const SECRET_PATTERNS = [
+  /(authorization\s*:\s*(?:bearer\s+)?)[^\s,;]+/gi,
+  /(["']?(?:api[_-]?key|access[_-]?token|refresh[_-]?token|oauth[_-]?token|password)["']?\s*[=:]\s*["']?)[^"'\s,;]+/gi,
+  /\b(sk-[a-zA-Z0-9_-]{12,})\b/g,
+];
+
+export class AgentError extends Error {
+  constructor(message, code, options = {}) {
+    super(message, options.cause ? { cause: options.cause } : undefined);
+    this.name = 'AgentError';
+    this.code = code;
+    if (options.provider) this.provider = options.provider;
+    if (options.model) this.model = options.model;
+    if (Number.isFinite(options.retryAfterMs)) this.retryAfterMs = options.retryAfterMs;
+    if (options.diagnostic) this.diagnostic = redactAgentDiagnostic(options.diagnostic);
+    this.retryable = options.retryable === true;
+  }
+}
+
+export function redactAgentDiagnostic(value, limit = 4000) {
+  let text = String(value || '').replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+  for (const pattern of SECRET_PATTERNS) text = text.replace(pattern, (_match, prefix) => `${prefix || ''}[REDACTED]`);
+  return text.slice(-limit);
+}
+
+function retryAfterFrom(text) {
+  const match = String(text || '').match(/retry[- ]?after\s*(?:[:=]\s*)?(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|seconds?)?/i);
+  if (!match) return undefined;
+  const amount = Number(match[1]);
+  return /^m(?!s)/i.test(match[2] || '') ? amount * 60_000 : /^ms|millisecond/i.test(match[2] || '') ? amount : amount * 1000;
+}
+
+export function classifyAgentDiagnostic(value, { provider = '', model = '', cause } = {}) {
+  const diagnostic = redactAgentDiagnostic(value);
+  const lower = diagnostic.toLowerCase();
+  const make = (message, code, retryable = false) => new AgentError(message, code, {
+    provider, model, cause, diagnostic, retryable, retryAfterMs: retryAfterFrom(diagnostic),
+  });
+  if (/content[_ -]?filter|finish[_ -]?reason["'\s:=]+content_filter|reason["'\s:=]+content_filter/.test(lower)) {
+    return make('The model output was interrupted by the provider content filter. No partial result was applied.', 'AGENT_CONTENT_FILTERED');
+  }
+  if (/\brefusal\b|\brefused\b|safety refusal|response was blocked/.test(lower)) {
+    return make('The model refused this request. No partial result was applied.', 'AGENT_REFUSED');
+  }
+  if (/max[_ -]?tokens|finish[_ -]?reason["'\s:=]+length|incomplete.*(?:length|token)|output.*truncat/.test(lower)) {
+    return make('The model output ended before the structured result was complete.', 'AGENT_OUTPUT_TRUNCATED', true);
+  }
+  if (/invalid_json_schema|unsupported.*(?:schema|flag)|unknown (?:argument|option)|unrecognized (?:argument|option)/.test(lower)) {
+    return make('The installed Agent CLI is incompatible with Papergod’s required structured-output protocol.', 'AGENT_CLI_INCOMPATIBLE');
+  }
+  if (/rate.?limit|too many requests|\b429\b|quota exceeded|insufficient quota/.test(lower)) {
+    return make('The Agent provider rate limit or quota was reached.', 'AGENT_RATE_LIMITED', true);
+  }
+  if (/unauthorized|forbidden|sign.?in required|log.?in required|authentication failed|\b401\b|\b403\b/.test(lower)) {
+    return make('The Agent CLI is installed but its model provider is not authenticated.', 'AGENT_AUTH_REQUIRED');
+  }
+  if (/model.*(?:not found|unavailable)|unknown model|\b404\b.*model/.test(lower)) {
+    return make('The configured Agent model is unavailable.', 'AGENT_MODEL_NOT_FOUND');
+  }
+  if (/timed? out|timeout/.test(lower)) return make('The Agent did not respond before the timeout.', 'AGENT_TIMEOUT', true);
+  if (/econnreset|econnrefused|enotfound|network|socket|transport|connection (?:closed|failed)/.test(lower)) {
+    return make('The Agent provider connection failed.', 'AGENT_TRANSPORT_ERROR', true);
+  }
+  return null;
+}
+
+export function normalizeAgentError(error, context = {}) {
+  if (error instanceof AgentError) return error;
+  const diagnostic = [error?.message, error?.stderr, error?.stdout, error?.diagnostic].filter(Boolean).join('\n');
+  const classified = classifyAgentDiagnostic(diagnostic, { ...context, cause: error });
+  if (classified) return classified;
+  if (error?.code === 'AGENT_CANCELLED' || error?.code === 'AGENT_TIMEOUT' || error?.code === 'AGENT_OUTPUT_LIMIT') return error;
+  return new AgentError(error?.message || 'Agent execution failed', error?.code || 'AGENT_PROCESS_FAILED', {
+    ...context, cause: error, diagnostic,
+  });
+}
+
+export function agentFailureAudit(error, limit = 4000) {
+  return redactAgentDiagnostic(JSON.stringify({
+    code: error?.code || 'AGENT_PROCESS_FAILED',
+    message: error?.message || 'Agent execution failed',
+    diagnostic: error?.diagnostic || '',
+    attempts: Array.isArray(error?.attempts) ? error.attempts : [],
+  }), limit);
+}
+
+export function incompleteJsonKind(value) {
+  const text = String(value || '').trim();
+  if (!text) return 'empty';
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (const character of text) {
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (character === '\\') escaped = true;
+      else if (character === '"') inString = false;
+      continue;
+    }
+    if (character === '"') inString = true;
+    else if (character === '{' || character === '[') depth += 1;
+    else if (character === '}' || character === ']') depth -= 1;
+  }
+  return inString || depth > 0 ? 'truncated' : 'malformed';
+}

package/src/server/agent-runtime.js

@@ -0,0 +1,81 @@
+const DEFAULT_TRANSIENT_COOLDOWN_MS = 60_000;
+const DEFAULT_RATE_COOLDOWN_MS = 5 * 60_000;
+const health = new Map();
+
+export function agentMemberKey(provider, model = '') {
+  return `${provider}/${model || 'default'}`;
+}
+
+export function agentHealthStatus(provider, model = '', now = Date.now()) {
+  const key = agentMemberKey(provider, model);
+  const record = health.get(key);
+  if (!record) return { available: true, key };
+  if (record.unavailableUntil <= now) {
+    health.delete(key);
+    return { available: true, key };
+  }
+  return { available: false, key, ...record, retryAfterMs: record.unavailableUntil - now };
+}
+
+export function markAgentUnavailable(provider, model, error, now = Date.now()) {
+  const code = error?.code || 'AGENT_PROCESS_FAILED';
+  let cooldownMs;
+  if (code === 'AGENT_RATE_LIMITED') cooldownMs = error.retryAfterMs || DEFAULT_RATE_COOLDOWN_MS;
+  else if (['AGENT_TIMEOUT', 'AGENT_TRANSPORT_ERROR', 'AGENT_EMPTY_RESPONSE', 'AGENT_MODEL_NOT_FOUND'].includes(code)) cooldownMs = error.retryAfterMs || DEFAULT_TRANSIENT_COOLDOWN_MS;
+  else return null;
+  const key = agentMemberKey(provider, model);
+  const unavailableUntil = now + cooldownMs;
+  const existing = health.get(key);
+  if (!existing || existing.unavailableUntil < unavailableUntil) health.set(key, { unavailableUntil, reason: code });
+  return agentHealthStatus(provider, model, now);
+}
+
+export function clearAgentHealth(provider, model) {
+  if (model !== undefined) return health.delete(agentMemberKey(provider, model));
+  for (const key of [...health.keys()]) if (key.startsWith(`${provider}/`)) health.delete(key);
+  return true;
+}
+
+export function resetAgentHealthForTests() {
+  health.clear();
+}
+
+export function parseCliVersion(value) {
+  const match = String(value || '').match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? { raw: match[0], major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) } : null;
+}
+
+export function versionAtLeast(actual, required) {
+  const left = parseCliVersion(actual);
+  const right = parseCliVersion(required);
+  if (!left || !right) return false;
+  const leftParts = [left.major, left.minor, left.patch];
+  const rightParts = [right.major, right.minor, right.patch];
+  for (let index = 0; index < leftParts.length; index += 1) {
+    if (leftParts[index] > rightParts[index]) return true;
+    if (leftParts[index] < rightParts[index]) return false;
+  }
+  return true;
+}
+
+export function inspectCliCapabilities(provider, versionText, helpText = '') {
+  const help = String(helpText || '');
+  const requiredFlags = provider === 'codex' ? ['--output-schema', '--output-last-message', '--ephemeral']
+    : provider === 'claude-code' ? ['--json-schema', '--output-format', '--no-session-persistence']
+      : provider === 'opencode' ? ['--format', '--pure', '--variant']
+        : ['--mode', '--no-session', '--thinking'];
+  const missing = requiredFlags.filter((flag) => !help.includes(flag));
+  const capabilities = {
+    structuredOutput: provider === 'codex' ? help.includes('--output-schema') : provider === 'claude-code' ? help.includes('--json-schema') : help.includes('--format') || help.includes('--mode'),
+    eventStream: provider === 'codex' ? help.includes('--json') : provider !== 'claude-code' || /stream-json/.test(help),
+    reasoningEffort: provider === 'codex' ? help.includes('--config') : provider === 'claude-code' ? help.includes('--effort') : provider === 'opencode' ? help.includes('--variant') : help.includes('--thinking'),
+    ephemeralSession: provider === 'codex' ? help.includes('--ephemeral') : provider === 'claude-code' ? help.includes('--no-session-persistence') : provider === 'opencode' ? help.includes('--pure') : help.includes('--no-session'),
+  };
+  return {
+    installed: true,
+    compatible: missing.length === 0,
+    version: parseCliVersion(versionText)?.raw || String(versionText || '').trim() || null,
+    capabilities,
+    warnings: missing.length ? [`Installed CLI is missing required flags: ${missing.join(', ')}`] : [],
+  };
+}

package/src/server/agent.js

@@ -0,0 +1,173 @@
+let nextId = 1;
+const suggestionStore = new Map();
+
+function resetStore() {
+  suggestionStore.clear();
+  nextId = 1;
+}
+
+export function composeMockSuggestions(content, prompt) {
+  const results = [];
+  let nextId = 1;
+
+  const patterns = [
+    {
+      regex: /very\s+(\w+)/gi,
+      category: 'style',
+      makeDesc: (m) => `Replace "${m}" with a more precise word`,
+      makeSuggestion: (m, adj) => {
+        const upgrades = { important: 'crucial', good: 'excellent', useful: 'invaluable', rapidly: 'rapidly', big: 'substantial', hard: 'difficult' };
+        const better = upgrades[adj.toLowerCase()];
+        return better && better !== adj.toLowerCase() ? better : `remarkably ${adj}`;
+      },
+    },
+    {
+      regex: /It was (found|shown|demonstrated|observed) that\s+(the\s+)?/gi,
+      category: 'grammar',
+      makeDesc: () => 'Consider using active voice instead of passive',
+      makeSuggestion: (m, _verb, _the) => '',
+      transform: (content, match) => {
+        const passive = match[0];
+        const rest = content.slice(match.index + match[0].length);
+        const sentenceEnd = rest.search(/[.!]/);
+        const fragment = sentenceEnd > 0 ? rest.slice(0, sentenceEnd) : rest.split('\n')[0];
+        return { original: passive + fragment, suggested: fragment.charAt(0).toUpperCase() + fragment.slice(1) };
+      },
+    },
+    {
+      regex: /In conclusion,?\s*.+?\./gi,
+      category: 'structure',
+      makeDesc: () => 'The conclusion is too brief; consider expanding it',
+      makeSuggestion: (m) => m,
+      transform: (_content, match) => {
+        const original = match[0];
+        const suggested = original.includes('very useful')
+          ? 'In conclusion, artificial intelligence has demonstrated significant utility across diverse domains, from healthcare to scientific research. As the field continues to advance, we anticipate even broader applications and deeper integration into everyday problem-solving.'
+          : original.replace(/In conclusion,?\s*/i, 'In summary, the findings demonstrate that ');
+        return { original, suggested };
+      },
+    },
+  ];
+
+  for (const pat of patterns) {
+    const regex = new RegExp(pat.regex.source, pat.regex.flags);
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      const id = `sug_${nextId++}`;
+      let original, suggested;
+
+      if (pat.transform) {
+        const result = pat.transform(content, match);
+        original = result.original;
+        suggested = result.suggested;
+      } else {
+        original = match[0];
+        suggested = pat.makeSuggestion(match[0], match[1]);
+      }
+
+      if (!original || !suggested || original === suggested) continue;
+
+      results.push({ id, category: pat.category, description: pat.makeDesc(match[0]), originalText: original, suggestedText: suggested });
+    }
+  }
+
+  if (results.length === 0 && content.trim().length > 0) {
+    const id = `sug_${nextId++}`;
+    const original = content.split('\n').find((l) => l.trim().length > 20) || content.split('\n')[0];
+    const suggested = original
+      .replace(/\bcan be\b/gi, 'is')
+      .replace(/\bhave been\b/gi, 'were')
+      .replace(/\bis being\b/gi, 'is');
+    if (original !== suggested) results.push({
+      id, category: 'style', description: 'Consider refining the academic tone of this document',
+      originalText: original, suggestedText: suggested,
+    });
+  }
+
+  return results;
+}
+
+export function generateSuggestions(content, prompt) {
+  resetStore();
+  const results = composeMockSuggestions(content, prompt);
+  for (const item of results) suggestionStore.set(item.id, item);
+  return results;
+}
+
+export function registerSuggestions(items) {
+  resetStore();
+  return items.map((item) => {
+    const suggestion = {
+      id: `sug_${nextId++}`,
+      category: item.category,
+      description: item.description,
+      originalText: item.originalText,
+      suggestedText: item.suggestedText,
+      reason: item.reason || '',
+      taskId: item.taskId || '',
+      nodeId: item.nodeId || '',
+      usedTemplateIds: Array.isArray(item.usedTemplateIds) ? item.usedTemplateIds : [],
+      usedCitekeys: Array.isArray(item.usedCitekeys) ? item.usedCitekeys : [],
+      targetAnchor: item.targetAnchor || null,
+    };
+    suggestionStore.set(suggestion.id, suggestion);
+    return suggestion;
+  });
+}
+
+export function attachSuggestionContext(items, { file = '', nodeId = '', nodeStart = 0, selectedContent = '' } = {}) {
+  for (const item of items) {
+    const suggestion = suggestionStore.get(item.id);
+    if (!suggestion) continue;
+    if (suggestion.targetAnchor?.sourceRange) {
+      suggestion.file = suggestion.targetAnchor.file || file;
+      suggestion.nodeId = suggestion.targetAnchor.nodeId || suggestion.nodeId || nodeId;
+      suggestion.sourceRange = { start: suggestion.targetAnchor.sourceRange.start, end: suggestion.targetAnchor.sourceRange.end };
+    } else {
+      const matches = [];
+      let offset = selectedContent.indexOf(suggestion.originalText);
+      while (offset !== -1) {
+        matches.push(offset);
+        offset = selectedContent.indexOf(suggestion.originalText, offset + Math.max(1, suggestion.originalText.length));
+      }
+      if (matches.length !== 1) continue;
+      suggestion.file = file;
+      suggestion.nodeId = nodeId;
+      suggestion.sourceRange = {
+        start: nodeStart + matches[0],
+        end: nodeStart + matches[0] + suggestion.originalText.length,
+      };
+    }
+    Object.assign(item, {
+      nodeId: suggestion.nodeId,
+      sourceRange: suggestion.sourceRange,
+    });
+  }
+  return items;
+}
+
+export function getSuggestion(id) {
+  return suggestionStore.get(id) || null;
+}
+
+export function removeSuggestion(id) {
+  return suggestionStore.delete(id);
+}
+
+export function applySuggestionToContent(content, suggestionId, file = '') {
+  const sug = suggestionStore.get(suggestionId);
+  if (!sug) return { content, error: 'Suggestion not found' };
+  if (sug.file && file && sug.file !== file) return { content, error: 'Suggestion belongs to a different file' };
+  let idx = -1;
+  if (sug.sourceRange) {
+    const actual = content.slice(sug.sourceRange.start, sug.sourceRange.end);
+    if (actual !== sug.originalText) return { content, error: 'Source text changed; generate a new suggestion' };
+    idx = sug.sourceRange.start;
+  } else {
+    idx = content.indexOf(sug.originalText);
+  }
+  if (idx === -1) return { content, error: 'Original text not found in document' };
+  const newContent = content.slice(0, idx) + sug.suggestedText + content.slice(idx + sug.originalText.length);
+  suggestionStore.delete(suggestionId);
+  return { content: newContent, error: null };
+}

package/src/server/app-version.js

@@ -0,0 +1,86 @@
+import { readFile } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const PACKAGE_FILE = resolve(PROJECT_ROOT, 'package.json');
+const RELEASES_URL = 'https://api.github.com/repos/LiuShengyu-Tech/papergod/releases/latest';
+const CACHE_TTL = 30 * 60 * 1000;
+
+let cachedRelease = null;
+let cachedAt = 0;
+let cacheResolved = false;
+
+export function compareVersions(left, right) {
+  const parse = (value) => String(value || '').replace(/^v/i, '').split('-')[0].split('.').map((part) => Number.parseInt(part, 10) || 0);
+  const a = parse(left);
+  const b = parse(right);
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    if ((a[index] || 0) !== (b[index] || 0)) return (a[index] || 0) > (b[index] || 0) ? 1 : -1;
+  }
+  return 0;
+}
+
+export function parseReleaseNotes(body = '') {
+  const sections = { highlights: [], fixes: [] };
+  let target = sections.highlights;
+  for (const rawLine of String(body).split('\n')) {
+    const line = rawLine.trim();
+    if (/^#{1,6}\s*(bug fixes?|fixes?|修复|问题修复)/i.test(line)) { target = sections.fixes; continue; }
+    if (/^#{1,6}\s*(what'?s new|features?|improvements?|新增|更新|改进)/i.test(line)) { target = sections.highlights; continue; }
+    const match = line.match(/^[-*]\s+(.+)/);
+    if (match) target.push(match[1].replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1').replace(/`([^`]+)`/g, '$1'));
+  }
+  return sections;
+}
+
+async function fetchLatestRelease(fetchImpl = globalThis.fetch) {
+  if (cacheResolved && Date.now() - cachedAt < CACHE_TTL) return cachedRelease;
+  if (typeof fetchImpl !== 'function') return null;
+  const response = await fetchImpl(RELEASES_URL, {
+    headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'papergod-update-check' },
+    signal: AbortSignal.timeout(3000),
+  });
+  if (response.status === 404) {
+    cachedRelease = null;
+    cachedAt = Date.now();
+    cacheResolved = true;
+    return null;
+  }
+  if (!response.ok) throw new Error(`Release check failed (${response.status})`);
+  const release = await response.json();
+  cachedRelease = release;
+  cachedAt = Date.now();
+  cacheResolved = true;
+  return release;
+}
+
+export async function getAppVersionInfo({ fetchImpl = globalThis.fetch } = {}) {
+  const packageData = JSON.parse(await readFile(PACKAGE_FILE, 'utf-8'));
+  const currentVersion = packageData.version;
+  try {
+    const release = await fetchLatestRelease(fetchImpl);
+    if (!release) return { currentVersion, latestVersion: currentVersion, updateAvailable: false, checked: true };
+    const latestVersion = String(release.tag_name || release.name || currentVersion).replace(/^v/i, '');
+    const notes = parseReleaseNotes(release.body);
+    return {
+      currentVersion,
+      latestVersion,
+      updateAvailable: compareVersions(latestVersion, currentVersion) > 0,
+      checked: true,
+      publishedAt: release.published_at || null,
+      releaseUrl: release.html_url || packageData.homepage || null,
+      title: release.name || `Papergod ${latestVersion}`,
+      highlights: notes.highlights,
+      fixes: notes.fixes,
+    };
+  } catch {
+    return { currentVersion, latestVersion: currentVersion, updateAvailable: false, checked: false };
+  }
+}
+
+export function resetVersionCacheForTests() {
+  cachedRelease = null;
+  cachedAt = 0;
+  cacheResolved = false;
+}

package/src/server/change-history.js

@@ -0,0 +1,114 @@
+import { createHash } from 'crypto';
+import { readFile } from 'fs/promises';
+import { loadProject } from './project-store.js';
+import { sanitizePath } from './security.js';
+
+function hash(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function timestampOf(revision) {
+  return revision.rolledBackAt || revision.appliedAt || revision.updatedAt || revision.createdAt || '';
+}
+
+function appliedRanges(changes) {
+  const executable = changes.filter((change) => Number.isInteger(change.target?.start) && typeof change.before === 'string' && typeof change.after === 'string');
+  return executable.map((change) => {
+    const shift = executable
+      .filter((other) => other.target.start < change.target.start)
+      .reduce((total, other) => total + other.after.length - other.before.length, 0);
+    const currentStart = change.target.start + shift;
+    return { ...change, currentStart, currentEnd: currentStart + change.after.length };
+  });
+}
+
+async function historicalRevisionSource(workspaceRoot, revision, document) {
+  if (!revision?.recoveryPoint) {
+    const error = new Error('Historical source is unavailable'); error.status = 404; throw error;
+  }
+  const recovery = sanitizePath(revision.recoveryPoint.path, workspaceRoot);
+  if (!recovery || !revision.recoveryPoint.path.startsWith('.papergod/recovery/')) {
+    const error = new Error('Invalid recovery point'); error.status = 403; throw error;
+  }
+  const original = await readFile(recovery, 'utf-8');
+  if (hash(original) !== revision.recoveryPoint.sourceHash) {
+    const error = new Error('Recovery point checksum failed'); error.status = 409; throw error;
+  }
+  const changes = (revision.changes || [])
+    .filter((change) => ['applied', 'reverted'].includes(change.status) && Number.isInteger(change.target?.start) && Number.isInteger(change.target?.end))
+    .sort((left, right) => right.target.start - left.target.start);
+  let source = original;
+  for (const change of changes) {
+    if (source.slice(change.target.start, change.target.end) !== change.before) {
+      const error = new Error(`Historical change ${change.id} does not match its recovery point`); error.status = 409; throw error;
+    }
+    source = source.slice(0, change.target.start) + change.after + source.slice(change.target.end);
+  }
+  if (hash(source) !== revision.recoveryPoint.appliedHash) {
+    const error = new Error('Historical version checksum failed'); error.status = 409; throw error;
+  }
+  return { revision, document, source };
+}
+
+export async function getRecentChangeHistory(workspaceRoot, documentId, limit = 5) {
+  const project = await loadProject(workspaceRoot);
+  const document = project.documents.find((item) => item.id === documentId);
+  if (!document) {
+    const error = new Error('Document not found'); error.status = 404; throw error;
+  }
+  const safe = sanitizePath(document.file, workspaceRoot);
+  if (!safe) {
+    const error = new Error('Access denied'); error.status = 403; throw error;
+  }
+  const currentHash = hash(await readFile(safe, 'utf-8'));
+  const revisions = project.revisions
+    .filter((item) => item.documentId === documentId && item.recoveryPoint && ['applied', 'rolled-back'].includes(item.status))
+    .sort((left, right) => timestampOf(right).localeCompare(timestampOf(left)))
+    .slice(0, Math.max(1, Math.min(5, Number(limit) || 5)));
+  return Promise.all(revisions.map(async (revision, index) => {
+    const matchesCurrent = revision.status === 'applied' && revision.recoveryPoint.appliedHash === currentHash;
+    const changes = appliedRanges((revision.changes || []).filter((change) => ['applied', 'reverted'].includes(change.status)));
+    const { source } = await historicalRevisionSource(workspaceRoot, revision, document);
+    return {
+      id: revision.id, documentId: revision.documentId, file: revision.file || document.file,
+      title: revision.title, summary: revision.summary, origin: revision.origin || 'revision', status: revision.status,
+      createdAt: revision.createdAt, appliedAt: revision.appliedAt || '', rolledBackAt: revision.rolledBackAt || '',
+      changeCount: changes.length, isLatest: index === 0, matchesCurrent,
+      canRollback: matchesCurrent, canRestore: !matchesCurrent, previewAvailable: true,
+      changes: changes.map((change) => ({
+        id: change.id, before: change.before, after: change.after, reason: change.reason || '', target: change.target,
+        currentStart: matchesCurrent ? change.currentStart : null, currentEnd: matchesCurrent ? change.currentEnd : null,
+        type: change.before === '' ? 'added' : change.after === '' ? 'deleted' : 'modified',
+        contextBefore: source.slice(Math.max(0, change.currentStart - 240), change.currentStart),
+        contextAfter: source.slice(change.currentEnd, Math.min(source.length, change.currentEnd + 240)),
+      })),
+    };
+  }));
+}
+
+export async function getHistoricalRevisionSource(workspaceRoot, revisionId) {
+  const project = await loadProject(workspaceRoot);
+  const revision = project.revisions.find((item) => item.id === revisionId);
+  if (!revision) {
+    const error = new Error('Change history entry not found'); error.status = 404; throw error;
+  }
+  const document = project.documents.find((item) => item.id === revision.documentId);
+  if (!document) {
+    const error = new Error('Document not found'); error.status = 404; throw error;
+  }
+  return historicalRevisionSource(workspaceRoot, revision, document);
+}
+
+export async function getChangeHistoryEntry(workspaceRoot, revisionId) {
+  const project = await loadProject(workspaceRoot);
+  const revision = project.revisions.find((item) => item.id === revisionId);
+  if (!revision) {
+    const error = new Error('Change history entry not found'); error.status = 404; throw error;
+  }
+  const history = await getRecentChangeHistory(workspaceRoot, revision.documentId, 5);
+  const entry = history.find((item) => item.id === revisionId);
+  if (!entry) {
+    const error = new Error('Change history entry is outside the recent history window'); error.status = 404; throw error;
+  }
+  return entry;
+}