@seqyuan/annodex 0.1.11 → 0.1.12

package/lib/report-store.ts

@@ -0,0 +1,597 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import type { AgentMessage, SessionContext } from "@/lib/types";
+
+// ---- Local getConfigDir (annodex config) ----
+function getAgentDir(): string {
+  const homeDir = process.env.HOME ?? process.env.USERPROFILE ?? "/tmp";
+  return join(homeDir, ".config", "annodex");
+}
+
+export interface AnalysisReportSource {
+  type: "session" | "file";
+  id?: string;
+  path?: string;
+  label: string;
+}
+
+export interface AnalysisReportChange {
+  id: string;
+  timestamp: string;
+  title: string;
+  detail: string;
+}
+
+export interface AnalysisReportSection {
+  id: string;
+  title: string;
+  markdown: string;
+  status: "draft" | "verified" | "outdated" | "needs_review";
+  updatedAt: string | null;
+  sources: AnalysisReportSource[];
+}
+
+export interface AnalysisReport {
+  schemaVersion: 1;
+  sessionId: string;
+  cwd: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  markdown: string;
+  sections: AnalysisReportSection[];
+  sources: AnalysisReportSource[];
+  changes: AnalysisReportChange[];
+  appliedUpdateKeys?: string[];
+}
+
+export interface AnalysisReportUpdate {
+  topic?: string;
+  section?: string;
+  action?: "append" | "replace";
+  status?: AnalysisReportSection["status"];
+  markdown?: string;
+  sources?: Array<string | AnalysisReportSource>;
+  invalidates?: string[];
+  note?: string;
+}
+
+const SECTION_DEFS = [
+  { id: "objective", title: "Objective" },
+  { id: "input_data", title: "Input Data" },
+  { id: "methods", title: "Methods" },
+  { id: "quality_control", title: "Quality Control" },
+  { id: "results", title: "Results" },
+  { id: "interpretation", title: "Biological Interpretation" },
+  { id: "outputs", title: "Output Files" },
+  { id: "reproducibility", title: "Reproducibility" },
+] as const;
+
+const FILE_PATH_RE = /(?:^|[\s(["'`])((?:\.{1,2}\/|\/|~\/)?[A-Za-z0-9_.@+\-/\\]+?\.(?:csv|tsv|txt|xlsx|xls|pdf|png|jpg|jpeg|svg|html|htm|r|R|py|ipynb|qmd|md|rds|h5ad|loom|mtx|tsv\.gz|csv\.gz))(?:$|[\s)\]"'`,;:])/g;
+const OUTPUT_DIR_RE = /(?:^|[\s(["'`])((?:\.{1,2}\/|\/|~\/)?[A-Za-z0-9_.@+\-/\\]+\/)(?=\s*(?:[:：-]|[0-9]+|含|共|files?|个文件|PDFs?|PNGs?|CSVs?|TSVs?|输出|output|results?))/gim;
+const METHOD_RE = /\b(seurat|scanpy|single[- ]cell|scrna|qc|quality control|normalize|normalization|pca|umap|tsne|cluster|clustering|resolution|marker|differential expression|deg|go enrichment|kegg|reactome|pathway|cell type|annotation|doublet|batch|integration|harmony|scvi)\b/i;
+const RESULT_RE = /\b(result|found|identified|showed|observed|enriched|upregulated|downregulated|marker|cluster|cell type|figure|plot|table|significant|p\s*[<>=]|fdr|padj|logfc|auc)\b/i;
+const INTERPRET_RE = /\b(suggest|indicate|imply|consistent with|biological|interpret|likely|may reflect|supports|driven by|associated with)\b/i;
+const QC_RE = /\b(qc|quality control|filter|filtered|mitochondrial|percent\.mt|nfeature|ncount|doublet|ambient|low[- ]quality)\b/i;
+const BIO_ANALYSIS_RE = /\b(seurat|scanpy|single[- ]cell|scrna|sc[- ]rna|rna[- ]seq|transcriptom|gene|genes|marker|cell type|cluster|clustering|umap|tsne|pca|qc|mitochondrial|percent\.mt|nfeature|ncount|deg|differential expression|go enrichment|kegg|reactome|pathway|gsea|volcano|heatmap|h5ad|rds|loom|mtx|fastq|bam|vcf|counts?|expression|annotation|doublet|batch|integration|harmony|scvi)\b|生信|单细胞|转录组|基因|表达矩阵|差异表达|富集|通路|聚类|细胞类型|细胞注释|质控|线粒体|标记基因|火山图|热图/i;
+const EMPTY_SECTION_MARKDOWN = new Set([
+  "_No curated content yet._",
+  "_No analysis objective detected yet._",
+  "_No input data paths detected yet._",
+  "_No output files detected yet._",
+  "_No reproducibility notes detected yet._",
+]);
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function encodePathSegment(value: string): string {
+  return Buffer.from(value).toString("base64url");
+}
+
+export function getReportPath(sessionId: string): string {
+  return join(getAgentDir(), "reports", `${encodePathSegment(sessionId)}.json`);
+}
+
+function makeEmptySection(id: string, title: string): AnalysisReportSection {
+  return { id, title, markdown: "", status: "draft", updatedAt: null, sources: [] };
+}
+
+function normalizeEmptyMarkdown(value: string): string {
+  const trimmed = value.trim();
+  return EMPTY_SECTION_MARKDOWN.has(trimmed) ? "" : trimmed;
+}
+
+function hasReportSectionContent(sections: AnalysisReportSection[]): boolean {
+  return sections.some((section) => normalizeEmptyMarkdown(section.markdown).length > 0);
+}
+
+export function createEmptyReport(sessionId: string, cwd: string, title?: string): AnalysisReport {
+  const timestamp = nowIso();
+  const sections = SECTION_DEFS.map((section) => makeEmptySection(section.id, section.title));
+  return {
+    schemaVersion: 1,
+    sessionId,
+    cwd,
+    title: title || "Analysis Report",
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    markdown: "",
+    sections,
+    sources: [],
+    changes: [],
+    appliedUpdateKeys: [],
+  };
+}
+
+export function readReport(sessionId: string, cwd = "", title?: string): AnalysisReport {
+  const filePath = getReportPath(sessionId);
+  if (!existsSync(filePath)) return createEmptyReport(sessionId, cwd, title);
+
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, "utf8")) as Partial<AnalysisReport>;
+    const fallback = createEmptyReport(sessionId, cwd, title);
+    const existingSections = Array.isArray(parsed.sections) ? parsed.sections : [];
+    const sections = SECTION_DEFS.map((def) => {
+      const existing = existingSections.find((section) => section?.id === def.id);
+      const markdown = normalizeEmptyMarkdown(typeof existing?.markdown === "string" ? existing.markdown : "");
+      return {
+        ...makeEmptySection(def.id, def.title),
+        ...(existing && typeof existing === "object" ? existing : {}),
+        id: def.id,
+        title: def.title,
+        markdown,
+        status: markdown ? (existing?.status ?? "draft") : "draft",
+        updatedAt: markdown ? (existing?.updatedAt ?? null) : null,
+        sources: markdown && Array.isArray(existing?.sources) ? existing.sources : [],
+      };
+    });
+    const reportTitle = typeof parsed.title === "string" && parsed.title.trim() ? parsed.title : fallback.title;
+    return {
+      ...fallback,
+      ...parsed,
+      schemaVersion: 1,
+      sessionId,
+      cwd: typeof parsed.cwd === "string" ? parsed.cwd : cwd,
+      title: reportTitle,
+      createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : fallback.createdAt,
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : fallback.updatedAt,
+      sections,
+      markdown: renderReportMarkdown(reportTitle, sections),
+      sources: hasReportSectionContent(sections) && Array.isArray(parsed.sources) ? parsed.sources : [],
+      changes: hasReportSectionContent(sections) && Array.isArray(parsed.changes) ? parsed.changes : [],
+      appliedUpdateKeys: Array.isArray(parsed.appliedUpdateKeys)
+        ? parsed.appliedUpdateKeys.filter((key): key is string => typeof key === "string")
+        : [],
+    };
+  } catch {
+    return createEmptyReport(sessionId, cwd, title);
+  }
+}
+
+function stableHash(value: string): string {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+export function writeReport(report: AnalysisReport): AnalysisReport {
+  const timestamp = nowIso();
+  const next = {
+    ...report,
+    updatedAt: timestamp,
+    markdown: renderReportMarkdown(report.title, report.sections),
+  };
+  const filePath = getReportPath(report.sessionId);
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp`;
+  writeFileSync(tempPath, JSON.stringify(next, null, 2), "utf8");
+  renameSync(tempPath, filePath);
+  return next;
+}
+
+function cleanText(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function escapeMarkdown(value: string): string {
+  return value.replace(/\|/g, "\\|");
+}
+
+function outputKind(filePath: string): string {
+  const lower = filePath.toLowerCase();
+  if (/\.(png|jpe?g|svg)$/.test(lower)) return "Representative image/figure.";
+  if (/\.pdf$/.test(lower)) return "PDF figure or report.";
+  if (/\.(csv|tsv|csv\.gz|tsv\.gz|xlsx?|mtx)$/.test(lower)) return "Result table or matrix.";
+  if (/\.(r|py|ipynb|qmd|md)$/.test(lower)) return "Analysis script or document.";
+  if (/\.(rds|h5ad|loom)$/.test(lower)) return "Analysis object or dataset.";
+  if (/\.(html?|svg)$/.test(lower)) return "Browser-renderable output.";
+  return "Detected from session output.";
+}
+
+function isReportPreviewImage(filePath: string): boolean {
+  return /\.(png|jpe?g|svg)$/i.test(filePath);
+}
+
+function markdownImagePath(filePath: string): string {
+  return filePath.replace(/\\/g, "/").replace(/([()\s])/g, "\\$1");
+}
+
+function outputLabel(filePath: string): string {
+  return filePath.split(/[\\/]/).filter(Boolean).pop() ?? filePath;
+}
+
+function normalizeTopic(value?: string): string {
+  return cleanText(value ?? "").slice(0, 120);
+}
+
+function withTopicPrefix(markdown: string, topic?: string): string {
+  const trimmed = markdown.trim();
+  if (!trimmed) return "";
+  const normalizedTopic = normalizeTopic(topic);
+  if (!normalizedTopic) return trimmed;
+  const topicHeading = `### ${normalizedTopic}`;
+  if (trimmed === topicHeading || trimmed.startsWith(`${topicHeading}\n`)) return trimmed;
+  return `${topicHeading}\n\n${trimmed}`;
+}
+
+function messageText(message: AgentMessage): string {
+  const content = message.content;
+  if (typeof content === "string") return cleanText(content);
+  if (!Array.isArray(content)) return "";
+  return cleanText(content
+    .map((block) => {
+      if (block.type === "text") return block.text;
+      if (block.type === "toolCall") return `${block.toolName} ${JSON.stringify(block.input)}`;
+      return "";
+    })
+    .join(" "));
+}
+
+function firstUserText(context: SessionContext): string {
+  const first = context.messages.find((message) => message.role === "user");
+  return first ? messageText(first).slice(0, 900) : "";
+}
+
+function firstAnalysisUserText(context: SessionContext): string {
+  const first = context.messages.find((message) => message.role === "user" && BIO_ANALYSIS_RE.test(messageText(message)));
+  return first ? messageText(first).slice(0, 900) : "";
+}
+
+function sessionHasBioAnalysisContent(context: SessionContext): boolean {
+  return context.messages.some((message) => BIO_ANALYSIS_RE.test(messageText(message)));
+}
+
+function uniquePush(values: string[], value: string, max: number): void {
+  const cleaned = cleanText(value);
+  if (!cleaned || values.includes(cleaned)) return;
+  values.push(cleaned);
+  if (values.length > max) values.length = max;
+}
+
+function extractOutputFiles(context: SessionContext): string[] {
+  const files: string[] = [];
+  for (const message of context.messages) {
+    const text = messageText(message);
+    if (!text) continue;
+    for (const match of text.matchAll(FILE_PATH_RE)) {
+      const filePath = match[1]?.replace(/[.,;:)]+$/, "");
+      if (filePath) uniquePush(files, filePath, 30);
+    }
+    for (const match of text.matchAll(OUTPUT_DIR_RE)) {
+      const dirPath = match[1]?.replace(/[.,;:)]+$/, "");
+      if (dirPath) uniquePush(files, dirPath, 30);
+    }
+  }
+  return files;
+}
+
+function collectSessionSignals(context: SessionContext): {
+  methods: string[];
+  qc: string[];
+  results: string[];
+  interpretation: string[];
+  reproducibility: string[];
+} {
+  const methods: string[] = [];
+  const qc: string[] = [];
+  const results: string[] = [];
+  const interpretation: string[] = [];
+  const reproducibility: string[] = [];
+
+  for (const message of context.messages) {
+    const text = messageText(message);
+    if (!text || text.length < 12) continue;
+    const trimmed = text.length > 500 ? `${text.slice(0, 500).trim()}...` : text;
+
+    if (message.role === "assistant") {
+      if (QC_RE.test(trimmed)) uniquePush(qc, trimmed, 8);
+      if (METHOD_RE.test(trimmed)) uniquePush(methods, trimmed, 10);
+      if (RESULT_RE.test(trimmed)) uniquePush(results, trimmed, 12);
+      if (INTERPRET_RE.test(trimmed)) uniquePush(interpretation, trimmed, 8);
+    }
+
+    if (message.role === "toolResult" && /saved|wrote|created|exported|generated|output|success/i.test(trimmed)) {
+      uniquePush(reproducibility, trimmed, 8);
+    }
+  }
+
+  return { methods, qc, results, interpretation, reproducibility };
+}
+
+function bullets(items: string[], empty = "_No curated content yet._"): string {
+  if (items.length === 0) return empty;
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+function outputTable(files: string[]): string {
+  if (files.length === 0) return "";
+  return [
+    "| File or Directory | Notes |",
+    "| --- | --- |",
+    ...files.map((file) => `| \`${escapeMarkdown(file)}\` | ${outputKind(file)} |`),
+  ].join("\n");
+}
+
+function representativeFigures(files: string[], maxFigures = 4): string {
+  const figures = files.filter(isReportPreviewImage).slice(0, maxFigures);
+  if (figures.length === 0) return "";
+  return [
+    "#### Representative Figures",
+    "",
+    ...figures.flatMap((file) => {
+      const label = outputLabel(file);
+      return [
+        `![${label}](${markdownImagePath(file)})`,
+        "",
+        `_Figure: ${label}. Representative visual output detected from this analysis topic._`,
+        "",
+      ];
+    }),
+  ].join("\n").trim();
+}
+
+function combineMarkdown(parts: string[]): string {
+  return parts.map((part) => part.trim()).filter(Boolean).join("\n\n");
+}
+
+function updateSection(
+  report: AnalysisReport,
+  id: string,
+  markdown: string,
+  status: AnalysisReportSection["status"] = "draft",
+  sources: AnalysisReportSource[] = []
+): void {
+  const section = report.sections.find((item) => item.id === id);
+  if (!section) return;
+  section.markdown = markdown.trim();
+  section.status = status;
+  section.updatedAt = nowIso();
+  section.sources = sources;
+}
+
+function normalizeSectionId(section?: string): string | null {
+  if (!section) return null;
+  const normalized = section.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  if (SECTION_DEFS.some((def) => def.id === normalized)) return normalized;
+  if (normalized.includes("objective") || normalized.includes("goal")) return "objective";
+  if (normalized.includes("input") || normalized.includes("sample") || normalized.includes("data")) return "input_data";
+  if (normalized.includes("method") || normalized.includes("parameter") || normalized.includes("workflow")) return "methods";
+  if (normalized.includes("qc") || normalized.includes("quality") || normalized.includes("filter")) return "quality_control";
+  if (normalized.includes("result") || normalized.includes("marker") || normalized.includes("deg") || normalized.includes("enrichment")) return "results";
+  if (normalized.includes("interpret") || normalized.includes("biology") || normalized.includes("biological")) return "interpretation";
+  if (normalized.includes("output") || normalized.includes("file") || normalized.includes("figure")) return "outputs";
+  if (normalized.includes("reproduc")) return "reproducibility";
+  return null;
+}
+
+function normalizeSources(sources: AnalysisReportUpdate["sources"]): AnalysisReportSource[] {
+  if (!Array.isArray(sources)) return [];
+  const normalized: AnalysisReportSource[] = [];
+  for (const source of sources) {
+    if (typeof source === "string") {
+      normalized.push({ type: "file", path: source, label: source });
+    } else if (source && typeof source === "object" && typeof source.label === "string") {
+      normalized.push({
+        type: source.type === "session" ? "session" : "file",
+        id: typeof source.id === "string" ? source.id : undefined,
+        path: typeof source.path === "string" ? source.path : undefined,
+        label: source.label,
+      });
+    }
+  }
+  return normalized;
+}
+
+export function applyReportUpdate(report: AnalysisReport, update: AnalysisReportUpdate, updateKey?: string): AnalysisReport {
+  const sectionId = normalizeSectionId(update.section);
+  const markdown = typeof update.markdown === "string" ? withTopicPrefix(update.markdown, update.topic) : "";
+  if (!sectionId || !markdown) return report;
+  const dedupeKey = updateKey ? stableHash(updateKey) : null;
+  if (dedupeKey && report.appliedUpdateKeys?.includes(dedupeKey)) return report;
+
+  const timestamp = nowIso();
+  const next: AnalysisReport = {
+    ...report,
+    sections: report.sections.map((section) => ({ ...section, sources: [...section.sources] })),
+    sources: [...report.sources],
+    changes: [...report.changes],
+    appliedUpdateKeys: [...(report.appliedUpdateKeys ?? [])],
+  };
+  const section = next.sections.find((item) => item.id === sectionId);
+  if (!section) return report;
+
+  section.markdown = update.action === "replace" || !section.markdown.trim()
+    ? markdown
+    : `${section.markdown.trim()}\n\n${markdown}`;
+  section.status = update.status ?? "draft";
+  section.updatedAt = timestamp;
+  const sources = normalizeSources(update.sources);
+  section.sources = sources.length > 0 ? sources : section.sources;
+
+  const invalidates = Array.isArray(update.invalidates) ? update.invalidates.map(normalizeSectionId).filter(Boolean) : [];
+  for (const invalidated of invalidates) {
+    const invalidatedSection = next.sections.find((item) => item.id === invalidated);
+    if (invalidatedSection && invalidatedSection.id !== section.id) {
+      invalidatedSection.status = "outdated";
+      invalidatedSection.updatedAt = timestamp;
+    }
+  }
+
+  next.sources = [...next.sources, ...sources].filter((source, index, all) => {
+    const key = `${source.type}:${source.id ?? ""}:${source.path ?? ""}:${source.label}`;
+    return all.findIndex((candidate) => `${candidate.type}:${candidate.id ?? ""}:${candidate.path ?? ""}:${candidate.label}` === key) === index;
+  });
+  next.changes = [
+    {
+      id: `change-${Date.now()}`,
+      timestamp,
+      title: `Updated ${section.title}`,
+      detail: update.note || "Applied a structured analysis report update from the assistant.",
+    },
+    ...next.changes,
+  ].slice(0, 50);
+  if (dedupeKey) {
+    next.appliedUpdateKeys = [dedupeKey, ...(next.appliedUpdateKeys ?? [])].slice(0, 500);
+  }
+  return next;
+}
+
+export function generateReportFromSession(input: {
+  report: AnalysisReport;
+  context: SessionContext;
+  sessionTitle?: string;
+  topic?: string;
+}): AnalysisReport {
+  const report = {
+    ...input.report,
+    title: input.report.title || input.sessionTitle || "Analysis Report",
+    sections: input.report.sections.map((section) => ({ ...section, sources: [...section.sources] })),
+    sources: [...input.report.sources],
+    changes: [...input.report.changes],
+    appliedUpdateKeys: [...(input.report.appliedUpdateKeys ?? [])],
+  };
+  const source: AnalysisReportSource = {
+    type: "session",
+    id: report.sessionId,
+    label: "Current conversation",
+  };
+  const hasBioContent = sessionHasBioAnalysisContent(input.context);
+  if (!hasBioContent) {
+    return hasReportSectionContent(report.sections)
+      ? { ...report, markdown: renderReportMarkdown(report.title, report.sections) }
+      : {
+          ...report,
+          sections: SECTION_DEFS.map((section) => makeEmptySection(section.id, section.title)),
+          sources: [],
+          changes: [],
+          markdown: "",
+        };
+  }
+
+  const objective = firstAnalysisUserText(input.context) || firstUserText(input.context);
+  const files = extractOutputFiles(input.context);
+  const signals = collectSessionSignals(input.context);
+  const topic = input.topic ?? (objective ? cleanText(objective).slice(0, 80) : "");
+  const figuresMarkdown = representativeFigures(files);
+  const resultsMarkdown = combineMarkdown([
+    signals.results.length > 0 ? bullets(signals.results) : "",
+    figuresMarkdown,
+  ]);
+
+  if (input.topic) {
+    let nextReport: AnalysisReport = report;
+    const addTopicUpdate = (section: string, markdown: string, sources: AnalysisReportSource[] = []) => {
+      const cleaned = markdown.trim();
+      if (!cleaned) return;
+      nextReport = applyReportUpdate(nextReport, {
+        topic,
+        section,
+        action: "append",
+        status: "draft",
+        markdown: cleaned,
+        sources,
+        note: `Added current-topic summary for ${topic}.`,
+      }, `${report.sessionId}:${topic}:${section}:${stableHash(cleaned)}`);
+    };
+
+    addTopicUpdate("objective", objective ? `- ${objective}` : "", objective ? [source] : []);
+    addTopicUpdate("input_data", files.length > 0
+      ? [
+          "Detected data or result paths mentioned in this topic:",
+          "",
+          outputTable(files.slice(0, 12)),
+        ].join("\n")
+      : "", files.length > 0 ? [source] : []);
+    addTopicUpdate("methods", signals.methods.length > 0 ? bullets(signals.methods) : "", signals.methods.length > 0 ? [source] : []);
+    addTopicUpdate("quality_control", signals.qc.length > 0 ? bullets(signals.qc) : "", signals.qc.length > 0 ? [source] : []);
+    addTopicUpdate("results", resultsMarkdown, resultsMarkdown ? [source] : []);
+    addTopicUpdate("interpretation", signals.interpretation.length > 0 ? bullets(signals.interpretation) : "", signals.interpretation.length > 0 ? [source] : []);
+    addTopicUpdate("outputs", files.length > 0 ? outputTable(files) : "", files.length > 0 ? [source] : []);
+    addTopicUpdate("reproducibility", signals.reproducibility.length > 0 ? bullets(signals.reproducibility) : "", signals.reproducibility.length > 0 ? [source] : []);
+    return nextReport;
+  }
+
+  updateSection(
+    report,
+    "objective",
+    objective ? withTopicPrefix(`- ${objective}`, topic) : "",
+    objective ? "draft" : "draft",
+    objective ? [source] : []
+  );
+  updateSection(
+    report,
+    "input_data",
+    files.length > 0
+      ? withTopicPrefix([
+          "Detected data or result paths mentioned in this session:",
+          "",
+          outputTable(files.slice(0, 12)),
+        ].join("\n"), topic)
+      : "",
+    files.length > 0 ? "draft" : "draft",
+    files.length > 0 ? [source] : []
+  );
+  updateSection(report, "methods", signals.methods.length > 0 ? withTopicPrefix(bullets(signals.methods), topic) : "", signals.methods.length > 0 ? "draft" : "draft", signals.methods.length > 0 ? [source] : []);
+  updateSection(report, "quality_control", signals.qc.length > 0 ? withTopicPrefix(bullets(signals.qc), topic) : "", signals.qc.length > 0 ? "draft" : "draft", signals.qc.length > 0 ? [source] : []);
+  updateSection(report, "results", resultsMarkdown ? withTopicPrefix(resultsMarkdown, topic) : "", resultsMarkdown ? "draft" : "draft", resultsMarkdown ? [source] : []);
+  updateSection(report, "interpretation", signals.interpretation.length > 0 ? withTopicPrefix(bullets(signals.interpretation), topic) : "", signals.interpretation.length > 0 ? "draft" : "draft", signals.interpretation.length > 0 ? [source] : []);
+  updateSection(report, "outputs", files.length > 0 ? withTopicPrefix(outputTable(files), topic) : "", files.length > 0 ? "draft" : "draft", files.length > 0 ? [source] : []);
+  updateSection(report, "reproducibility", signals.reproducibility.length > 0 ? withTopicPrefix(bullets(signals.reproducibility), topic) : "", signals.reproducibility.length > 0 ? "draft" : "draft", signals.reproducibility.length > 0 ? [source] : []);
+
+  if (hasReportSectionContent(report.sections)) {
+    report.sources = [source];
+    report.changes = [
+      {
+        id: `change-${Date.now()}`,
+        timestamp: nowIso(),
+        title: "Generated from conversation",
+        detail: "Refreshed the analysis report from the current session, keeping only analysis objectives, methods, results, interpretations, outputs, and reproducibility notes.",
+      },
+      ...report.changes,
+    ].slice(0, 50);
+  }
+  return report;
+}
+
+export function renderReportMarkdown(title: string, sections: AnalysisReportSection[]): string {
+  const contentSections = sections.filter((section) => normalizeEmptyMarkdown(section.markdown).length > 0);
+  if (contentSections.length === 0) return "";
+
+  const body = contentSections.map((section) => {
+    const status = section.status === "verified"
+      ? "verified"
+      : section.status === "outdated"
+      ? "outdated"
+      : section.status === "needs_review"
+      ? "needs review"
+      : "draft";
+    const content = normalizeEmptyMarkdown(section.markdown);
+    return `## ${section.title}\n\n_Status: ${status}_\n\n${content}`;
+  });
+  return [`# ${title || "Analysis Report"}`, ...body].join("\n\n");
+}

package/lib/report-update-parser.ts

@@ -0,0 +1,66 @@
+import type { AnalysisReportUpdate } from "@/lib/report-store";
+
+export interface ParsedReportUpdate {
+  update: AnalysisReportUpdate;
+  raw: string;
+}
+
+const REPORT_FENCE_RE = /```(?:analysis-report-update|report-update)\s*\n([\s\S]*?)```/gi;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeStatus(value: unknown): AnalysisReportUpdate["status"] | undefined {
+  if (value === "draft" || value === "verified" || value === "outdated" || value === "needs_review") return value;
+  if (value === "needs review") return "needs_review";
+  return undefined;
+}
+
+function normalizeAction(value: unknown): AnalysisReportUpdate["action"] | undefined {
+  return value === "replace" ? "replace" : value === "append" ? "append" : undefined;
+}
+
+function parseUpdate(rawJson: string): AnalysisReportUpdate | null {
+  try {
+    const parsed = JSON.parse(rawJson) as unknown;
+    if (!isRecord(parsed)) return null;
+    return {
+      topic: typeof parsed.topic === "string" ? parsed.topic : undefined,
+      section: typeof parsed.section === "string" ? parsed.section : undefined,
+      action: normalizeAction(parsed.action),
+      status: normalizeStatus(parsed.status),
+      markdown: typeof parsed.markdown === "string" ? parsed.markdown : undefined,
+      sources: Array.isArray(parsed.sources) ? parsed.sources as AnalysisReportUpdate["sources"] : undefined,
+      invalidates: Array.isArray(parsed.invalidates)
+        ? parsed.invalidates.filter((item): item is string => typeof item === "string")
+        : undefined,
+      note: typeof parsed.note === "string" ? parsed.note : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function parseReportUpdates(content: string): ParsedReportUpdate[] {
+  const updates: ParsedReportUpdate[] = [];
+  for (const match of content.matchAll(REPORT_FENCE_RE)) {
+    const raw = match[0];
+    const body = match[1]?.trim() ?? "";
+    const update = parseUpdate(body);
+    if (update) updates.push({ update, raw });
+  }
+  return updates;
+}
+
+export function stripReportUpdateFences(content: string): string {
+  return content
+    .replace(REPORT_FENCE_RE, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export function hasReportUpdateFence(content: string): boolean {
+  REPORT_FENCE_RE.lastIndex = 0;
+  return REPORT_FENCE_RE.test(content);
+}