@keyou007/agent-bot 0.1.24-alpha.1 → 0.1.24-alpha.3

package/src/index.ts

@@ -29,9 +29,10 @@ import { ProxySessionController } from "./proxy/ProxySessionController.js";
 import type { AgentEnvironmentContext } from "./runtime/agentEnvironment.js";
 import { createAgentRuntimeRegistry } from "./runtime/createAgentRuntimeRegistry.js";
 import { StateStore } from "./state/StateStore.js";
+import { ManualUpdateController } from "./updates/ManualUpdateController.js";
 import { DailyUpdateMonitor } from "./updates/DailyUpdateMonitor.js";
-import { readLatestStableVersion, readReleaseNotes } from "./updates/PublishedRelease.js";
-import { checkAutomaticUpdateSupport, prepareAutomaticUpdate } from "./updates/AutomaticUpdatePreparer.js";
+import { readLatestStableVersion, readReleaseNotes, readPublishedReleases } from "./updates/PublishedRelease.js";
+import { checkAutomaticUpdateSupport, prepareAutomaticUpdate, prepareSelectedUpdate } from "./updates/AutomaticUpdatePreparer.js";
 import { StartupNotifier } from "./startup/StartupNotifier.js";
 import { SessionMetadataHydrator } from "./startup/SessionMetadataHydrator.js";
 import { startFeishu } from "./startup/startFeishu.js";
@@ -56,6 +57,7 @@ import {
 import { refreshedSystemEnvironment } from "./supervision/systemEnvironment.js";
 import {
   assertSelfUpdatePlanPath,
+  finalizeSelfUpdatePlan,
   launchSelfUpdateRunner,
   readPendingSelfUpdate,
   releaseSelfUpdatePlan,
@@ -75,15 +77,18 @@ const consoleOnly = process.env.AGENT_BOT_CONSOLE_ONLY === "1";
 const config = loadConfig();
 const transport = consoleOnly ? "console" : requireServerFeishuTransport(config.feishu);
 const logger = createLogger(config);
-const store = new StateStore(config.storage.sqlitePath);
+const store = new StateStore(config.storage.sqlitePath, (error) => logger.error({ error }, "Failed to persist Turn preview journal."));
 let localFileViewer: LocalFileViewerServer | undefined;
+let loadTurnDetails: ((turnId: string) => Promise<unknown>) | undefined;
 if (config.fileViewer.enabled) {
   const viewer = new LocalFileViewerServer({
     host: config.fileViewer.host,
     port: config.fileViewer.port,
     publicBaseUrl: config.fileViewer.publicBaseUrl,
     stateDirectory: path.join(path.dirname(config.storage.sqlitePath), "file-viewer"),
+    previewJournal: store.previews,
     getTurnSnapshot: (turnId) => store.getTurnSnapshot(turnId),
+    loadTurnSnapshot: (turnId) => loadTurnDetails?.(turnId) ?? Promise.resolve(store.getTurnSnapshot(turnId)),
   });
   try {
     const address = await viewer.start();
@@ -153,6 +158,7 @@ const outbound = new OutboundRouter(routes);
 let shuttingDown = false;
 let restartRequested = false;
 let pendingSelfUpdatePlanPath: string | undefined;
+let preparingSelfUpdate = false;
 const safeRestart = new SafeRestartScheduler({
   readActivity: () => store.getServerActivityState(),
   onReady: (reason, notificationTargets) => pendingSelfUpdatePlanPath
@@ -168,29 +174,62 @@ if (feishuOutbound && config.updates?.enabled !== false) {
     readLatest: readLatestStableVersion,
     readNotes: readReleaseNotes,
     checkSupport: () => checkAutomaticUpdateSupport({ home: agentBotHome(), configPath: activeConfigPath }),
-    hasPendingUpdate: () => shuttingDown || restartRequested || !!pendingSelfUpdatePlanPath || safeRestart.scheduled,
+    hasPendingUpdate: () => preparingSelfUpdate || shuttingDown || restartRequested || !!pendingSelfUpdatePlanPath || safeRestart.scheduled,
     pendingVersion: () => pendingSelfUpdatePlanPath ? readPendingSelfUpdate(agentBotHome())?.plan.toVersion : undefined,
-    applyUpdate: async (version) => {
-      const prepared = await prepareAutomaticUpdate(version, { home: agentBotHome(), configPath: activeConfigPath });
-      try {
-        if (shuttingDown || restartRequested || pendingSelfUpdatePlanPath || safeRestart.scheduled) {
-          throw new Error("服务正在停止或已有更新/重启等待执行，本次自动更新已停止。");
-        }
-        const target = privateRestartNotificationTarget(config.feishu.userOpenId);
-        if (prepared.status === "prepared") {
-          assertSelfUpdatePlanPath(prepared.planPath, agentBotHome());
-          pendingSelfUpdatePlanPath = prepared.planPath;
-        }
-        safeRestart.schedule(`Agent Bot 自动更新到 ${version}`, target);
-      } catch (error) {
-        if (prepared.status === "prepared") releaseSelfUpdatePlan(prepared.planPath);
-        throw error;
-      }
-    },
+    applyUpdate: (version) => prepareAndScheduleUpdate(version, privateRestartNotificationTarget(config.feishu.userOpenId)),
   });
 }
+const manualUpdates = new ManualUpdateController({
+  store, outbound, logger, currentVersion: agentBotVersion,
+  ownerOpenId: () => config.feishu.userOpenId,
+  readReleases: readPublishedReleases,
+  checkSupport: () => checkAutomaticUpdateSupport({ home: agentBotHome(), configPath: activeConfigPath }),
+  hasPendingUpdate: () => preparingSelfUpdate || shuttingDown || restartRequested || !!pendingSelfUpdatePlanPath || safeRestart.scheduled,
+  applyUpdate: (version, contextKey, replyTarget) => prepareAndScheduleUpdate(version, {
+    contextKey,
+    ...(replyTarget ? { replyMessageId: replyTarget.messageId } : {}),
+  }, true),
+});
+
+async function prepareAndScheduleUpdate(version: string, target: RestartNotificationTarget, manual = false): Promise<void> {
+  if (preparingSelfUpdate || shuttingDown || restartRequested || pendingSelfUpdatePlanPath || safeRestart.scheduled) {
+    throw new Error("已有更新或重启正在进行，请稍后重试。");
+  }
+  preparingSelfUpdate = true;
+  try {
+    const prepare = manual ? prepareSelectedUpdate : prepareAutomaticUpdate;
+    const prepared = await prepare(version, { home: agentBotHome(), configPath: activeConfigPath });
+    try {
+      if (shuttingDown || restartRequested || pendingSelfUpdatePlanPath || safeRestart.scheduled) {
+        throw new Error("服务正在停止或已有更新/重启等待执行，本次更新已停止。");
+      }
+      if (prepared.status === "prepared") {
+        assertSelfUpdatePlanPath(prepared.planPath, agentBotHome());
+        finalizeSelfUpdatePlan(prepared.planPath, {
+          controlEndpoint: controlEndpoint(config.storage.sqlitePath),
+          databasePath: config.storage.sqlitePath,
+          restartService: true,
+          notificationTarget: target,
+        });
+        pendingSelfUpdatePlanPath = prepared.planPath;
+      }
+      safeRestart.schedule(`Agent Bot ${manual ? "更新" : "自动更新"}到 ${version}`, target);
+    } catch (error) {
+      if (prepared.status === "prepared") {
+        if (pendingSelfUpdatePlanPath === prepared.planPath) pendingSelfUpdatePlanPath = undefined;
+        releaseSelfUpdatePlan(prepared.planPath);
+      }
+      throw error;
+    }
+  } finally {
+    preparingSelfUpdate = false;
+  }
+}
+
 const controller = new ProxySessionController(config, store, runtimes, outbound, logger, {
   supervised,
+  showUpdates: (contextKey, userId) => manualUpdates.show(contextKey, userId),
+  selectUpdate: (action, replyTarget) => manualUpdates.select(action, replyTarget),
   restart: requestRestart,
   forceSafeRestart: async (scheduleId) => {
     if (shuttingDown || restartRequested) return false;
@@ -226,6 +265,7 @@ const controller = new ProxySessionController(config, store, runtimes, outbound,
     logger.info({ agentName, changed }, "Stored Agent execution defaults.");
   },
 });
+loadTurnDetails = (turnId) => controller.loadTurnDetails(turnId);
 
 if (feishuOutbound) {
   feishuConnector = new FeishuConnector(
@@ -278,7 +318,7 @@ function recoverPendingSelfUpdate(): void {
   if (!pending || pendingSelfUpdatePlanPath || restartRequested || safeRestart.scheduled) return;
   let notificationTarget: RestartNotificationTarget | undefined;
   try {
-    notificationTarget = inferServerRestartTarget(pending.plan.notificationSessionId);
+    notificationTarget = pending.plan.notificationTarget ?? inferServerRestartTarget(pending.plan.notificationSessionId);
   } catch (error) {
     logger.warn({ error }, "Could not restore the self-update notification target; update recovery will continue.");
   }

package/src/local-files/DiagramPreview.ts

@@ -0,0 +1,173 @@
+import type MarkdownIt from "markdown-it";
+
+export function enableDiagramFences(markdown: InstanceType<typeof MarkdownIt>): void {
+  const original = markdown.renderer.rules.fence!;
+  markdown.renderer.rules.fence = (tokens, index, options, environment, renderer) => {
+    const token = tokens[index]!;
+    if (!/^(mermaid|flowchart)$/iu.test(token.info.trim())) return original(tokens, index, options, environment, renderer);
+    const zh = environment?.language !== "en";
+    const source = markdown.utils.escapeHtml(token.content);
+    return `<div class="diagram" data-diagram data-diagram-size="fit" data-preview-key="diagram:${index}">
+      <div class="diagram-toolbar" role="group" aria-label="${zh ? "图表显示模式" : "Diagram display mode"}">
+        <button type="button" data-diagram-mode="preview" aria-pressed="true">${zh ? "预览" : "Preview"}</button>
+        <button type="button" data-diagram-mode="source" aria-pressed="false">${zh ? "源码" : "Source"}</button>
+        <button type="button" data-diagram-size-toggle hidden>${zh ? "原大" : "Actual size"}</button>
+      </div>
+      <p class="diagram-notice" role="status">${zh ? "正在渲染图表…" : "Rendering diagram…"}</p>
+      <div class="diagram-preview" role="img" aria-label="${zh ? "Mermaid 图表" : "Mermaid diagram"}"></div>
+      <pre class="diagram-source" hidden><code>${source}</code></pre>
+      <noscript><pre><code>${source}</code></pre></noscript>
+    </div>`;
+  };
+}
+
+export const DIAGRAM_PREVIEW_CSS = `
+.diagram { --diagram-max-height:min(640px, 70vh); border:1px solid var(--border, #d8dee8); border-radius:12px; overflow:hidden; margin:12px 0; }
+.diagram-toolbar { display:flex; flex-wrap:wrap; gap:4px; padding:6px 8px; border-bottom:1px solid var(--border, #d8dee8); }
+.diagram-toolbar button { font:inherit; font-size:12px; color:inherit; background:transparent; border:1px solid transparent; border-radius:6px; padding:3px 10px; cursor:pointer; }
+.diagram-toolbar button[aria-pressed="true"] { border-color:currentColor; }
+.diagram-toolbar [data-diagram-size-toggle] { margin-left:auto; }
+.diagram-toolbar button:focus-visible { outline:2px solid #4285d4; outline-offset:1px; }
+.diagram-notice { font-size:12px; opacity:.75; margin:8px 12px!important; }
+.diagram-preview { padding:12px; overflow:auto; max-height:var(--diagram-max-height); }
+.diagram-preview svg { display:block; margin:auto; max-width:none!important; height:auto; width:min(100%, var(--diagram-width, 100%))!important; }
+.diagram[data-diagram-size="actual"] .diagram-preview svg { width:var(--diagram-width, 100%)!important; }
+@media (max-width:640px), (pointer:coarse) {
+  .diagram { --diagram-max-height:min(480px, 55vh); }
+  @supports (height:1svh) { .diagram { --diagram-max-height:min(480px, 55svh); } }
+}
+.diagram .diagram-source { margin:0; border:0; border-radius:0; max-height:30em; overflow:auto; white-space:pre; }
+.diagram [hidden] { display:none!important; }
+@media (hover:none), (pointer:coarse) { .diagram-preview, .diagram-source { scrollbar-width:none; } .diagram-preview::-webkit-scrollbar, .diagram-source::-webkit-scrollbar { display:none; } }
+`;
+
+export const DIAGRAM_PREVIEW_CLIENT_SCRIPT = String.raw`(() => {
+  const zh = /^zh/i.test(document.documentElement.lang);
+  const loading = zh ? "正在渲染图表…" : "Rendering diagram…";
+  const failed = zh ? "图表暂时无法渲染，已显示源码。" : "Diagram could not be rendered. Showing source.";
+  const states = new WeakMap();
+  let library;
+  let sequence = 0;
+  const loadLibrary = () => {
+    if (!library) library = new Promise((resolve, reject) => {
+      const url = document.body.dataset.diagramScript;
+      if (!url) { reject(new Error("Diagram renderer unavailable")); return; }
+      const script = document.createElement("script");
+      script.src = url;
+      const timeout = setTimeout(() => {
+        script.remove();
+        reject(new Error("Diagram renderer timed out"));
+      }, 15000);
+      script.onload = () => {
+        clearTimeout(timeout);
+        const mermaid = window.mermaid;
+        if (!mermaid) { reject(new Error("Diagram renderer unavailable")); return; }
+        try {
+          mermaid.initialize({
+            startOnLoad: false, securityLevel: "strict", suppressErrorRendering: true,
+            maxTextSize: 50000, maxEdges: 500, htmlLabels: false,
+            flowchart: { htmlLabels: false },
+            theme: window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "default",
+            secure: ["securityLevel", "startOnLoad", "maxTextSize", "maxEdges", "suppressErrorRendering", "htmlLabels", "flowchart", "secure"],
+          });
+          resolve(mermaid);
+        } catch (error) { reject(error); }
+      };
+      script.onerror = () => { clearTimeout(timeout); script.remove(); reject(new Error("Diagram renderer unavailable")); };
+      document.head.appendChild(script);
+    }).catch((error) => { library = undefined; throw error; });
+    return library;
+  };
+  const show = (block, state) => {
+    const mode = state.error ? "source" : state.mode;
+    block.querySelector(".diagram-preview").hidden = mode !== "preview";
+    block.querySelector(".diagram-source").hidden = mode !== "source";
+    block.dataset.diagramSize = state.size;
+    const sizeButton = block.querySelector("[data-diagram-size-toggle]");
+    sizeButton.hidden = mode !== "preview" || state.rendered !== state.source;
+    sizeButton.textContent = state.size === "actual" ? (zh ? "适应" : "Fit") : (zh ? "原大" : "Actual size");
+    sizeButton.setAttribute("aria-label", state.size === "actual"
+      ? (zh ? "适应容器宽度" : "Fit diagram to width")
+      : (zh ? "按原始尺寸查看图表" : "View diagram at actual size"));
+    const notice = block.querySelector(".diagram-notice");
+    notice.hidden = !state.error && (state.rendered === state.source || mode === "source");
+    notice.textContent = state.error ? failed : loading;
+    block.querySelectorAll("[data-diagram-mode]").forEach((button) => {
+      button.setAttribute("aria-pressed", String(button.dataset.diagramMode === mode));
+    });
+  };
+  const render = async (block, state, revision) => {
+    const source = state.source;
+    let container;
+    try {
+      // Keep model-authored Mermaid config from weakening the renderer's safety policy.
+      if (source.length > 50000 || /^\s*---(?:\r?\n|$)/u.test(source) || /%%\s*\{/u.test(source)) {
+        throw new Error("Diagram configuration or size is unsupported");
+      }
+      const mermaid = await loadLibrary();
+      if (!block.isConnected || state.revision !== revision) return;
+      container = document.createElement("div");
+      container.style.cssText = "position:absolute;left:-100000px;top:0;width:1000px;visibility:hidden;pointer-events:none";
+      document.body.appendChild(container);
+      const result = await mermaid.render("agentbot-diagram-" + (++sequence), source, container);
+      if (!block.isConnected || state.revision !== revision) return;
+      const template = document.createElement("template");
+      template.innerHTML = result.svg;
+      // Mermaid's strict renderer sanitizes SVG. Also prohibit links, images and callbacks.
+      template.content.querySelectorAll("script,foreignObject,iframe,object,embed,image").forEach((node) => node.remove());
+      template.content.querySelectorAll("*").forEach((node) => {
+        for (const attr of Array.from(node.attributes)) {
+          if (/^on/i.test(attr.name) || /^(href|xlink:href|src)$/i.test(attr.name) && !attr.value.startsWith("#")) node.removeAttribute(attr.name);
+        }
+      });
+      const svg = template.content.querySelector("svg");
+      if (!svg) throw new Error("Missing SVG");
+      const viewBox = (svg.getAttribute("viewBox") || "").split(/[ ,]+/).map(Number);
+      if (viewBox.length === 4 && viewBox.every(Number.isFinite) && viewBox[2] > 0 && viewBox[3] > 0) {
+        svg.style.setProperty("--diagram-width", viewBox[2] + "px");
+      }
+      block.querySelector(".diagram-preview").replaceChildren(template.content);
+      state.rendered = source;
+      state.error = false;
+      show(block, state);
+    } catch {
+      if (block.isConnected && state.revision === revision) { state.error = true; show(block, state); }
+    } finally { if (container) container.remove(); }
+  };
+  const schedule = (block, state) => {
+    clearTimeout(state.timer);
+    state.revision += 1;
+    if (state.mode !== "preview" || state.rendered === state.source) return;
+    const revision = state.revision;
+    state.timer = setTimeout(() => void render(block, state, revision), 180);
+  };
+  const refresh = (block) => {
+    const source = block.querySelector(".diagram-source code").textContent;
+    let state = states.get(block);
+    if (!state) {
+      state = { source, mode: "preview", size: "fit", revision: 0, error: false };
+      states.set(block, state);
+      block.querySelector("[data-diagram-size-toggle]").addEventListener("click", () => {
+        state.size = state.size === "actual" ? "fit" : "actual";
+        const preview = block.querySelector(".diagram-preview");
+        preview.scrollLeft = 0;
+        preview.scrollTop = 0;
+        show(block, state);
+      });
+      block.querySelectorAll("[data-diagram-mode]").forEach((button) => {
+        button.addEventListener("click", () => {
+          state.mode = button.dataset.diagramMode;
+          if (state.mode === "preview") state.error = false;
+          show(block, state);
+          schedule(block, state);
+        });
+      });
+    } else if (state.source === source) { return; }
+    else { state.source = source; state.error = false; }
+    show(block, state);
+    schedule(block, state);
+  };
+  const scan = () => document.querySelectorAll("[data-diagram]").forEach(refresh);
+  window.agentBotDiagrams = { refresh, scan };
+  scan();
+})();`;

package/src/local-files/LocalFileViewerServer.ts

@@ -1,5 +1,7 @@
+import { TurnPreviewProjection, type TurnPreviewJournal } from "../state/TurnPreviewJournal.js";
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import fs from "node:fs";
+import { createRequire } from "node:module";
 import http, { type IncomingMessage, type ServerResponse } from "node:http";
 import path from "node:path";
 import hljs from "highlight.js/lib/common";
@@ -16,10 +18,15 @@ import {
   isTurnPreviewState,
   detectTurnPreviewLanguage,
   renderTurnPreviewPage,
+  renderTurnPreviewPatch,
+  renderToolFooter,
+  renderTurnPreviewDetail,
   renderTurnPreviewSnapshot,
   TURN_PREVIEW_CLIENT_SCRIPT,
 } from "./TurnPreviewPage.js";
 
+const require = createRequire(import.meta.url);
+let mermaidSource: string | undefined;
 const SECRET_FILE = "secret";
 const PORT_FILE = "port";
 const SHORT_TOKEN_BYTES = 12;
@@ -230,7 +237,9 @@ export interface LocalFileViewerServerOptions {
   port: number;
   publicBaseUrl?: string;
   stateDirectory: string;
+  previewJournal?: TurnPreviewJournal;
   getTurnSnapshot?: (turnId: string) => unknown;
+  loadTurnSnapshot?: (turnId: string) => Promise<unknown>;
   turnPreviewPollIntervalMs?: number;
 }
 
@@ -376,6 +385,11 @@ export class LocalFileViewerServer {
       this.sendJavascript(response, request.method === "HEAD", TURN_PREVIEW_CLIENT_SCRIPT);
       return;
     }
+    if (route === "/assets/mermaid.js") {
+      mermaidSource ??= fs.readFileSync(require.resolve("mermaid/dist/mermaid.min.js"), "utf8");
+      this.sendJavascript(response, request.method === "HEAD", mermaidSource);
+      return;
+    }
     const turnPreviewMatch = new RegExp(`^/turn-preview/([A-Za-z0-9_-]{${SHORT_TOKEN_LENGTH}})$`, "u").exec(route);
     if (turnPreviewMatch) {
       const turnId = this.verifyTurnPreviewToken(
@@ -386,23 +400,68 @@ export class LocalFileViewerServer {
         this.sendHtml(response, 403, errorPage("Turn 链接无效", "签名校验失败，Agent Bot 已拒绝该请求。"), request.method === "HEAD");
         return;
       }
-      const snapshot = this.options.getTurnSnapshot?.(turnId);
+      const journal = this.options.previewJournal;
+      const recorded = journal?.has(turnId);
+      if (recorded && requestUrl.searchParams.get("events") === "1") {
+        this.serveJournalEvents(request, response, turnId, journal!);
+        return;
+      }
+      const detailKey = requestUrl.searchParams.get("detail");
+      let snapshot = recorded
+        ? journal!.load(turnId, detailKey ?? false)
+        : this.options.getTurnSnapshot?.(turnId);
+      if (!recorded && this.options.loadTurnSnapshot && request.method !== "HEAD"
+        && requestUrl.searchParams.get("events") !== "1" && !requestUrl.searchParams.has("detail")) {
+        const saved = snapshot;
+        try {
+          snapshot = await this.options.loadTurnSnapshot(turnId);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (!isTurnPreviewState(saved)) {
+            this.sendHtml(response, 502, errorPage("历史执行详情读取失败", `${message} 刷新页面重试；任务状态未改变。`), false);
+            return;
+          }
+          snapshot = { ...saved, historyDetailError: message };
+        }
+      }
       if (!isTurnPreviewState(snapshot)) {
         this.sendHtml(response, 404, errorPage("Turn 不存在", "这次执行可能尚未保存或已被清理。"), request.method === "HEAD");
         return;
       }
+      if (requestUrl.searchParams.has("detail")) {
+        const language = detectTurnPreviewLanguage(request.headers["accept-language"]);
+        const key = requestUrl.searchParams.get("detail") ?? "";
+        const tool = snapshot.activities.find((a) => a.kind === "tool" && `tool:${a.id}` === key);
+        const after = requestUrl.searchParams.get("detailAfter");
+        const outputAppend = recorded && after && tool?.kind === "tool" && tool.tool.kind === "command" && !tool.tool.error
+          && !/repl/i.test(tool.tool.title) && snapshot.previewCursor !== undefined
+          ? journal!.outputAppend(turnId, tool.id, Number(after), snapshot.previewCursor) : undefined;
+        const detail = outputAppend !== undefined && tool?.kind === "tool"
+          && (snapshot.fullToolOutputs?.[tool.id]?.length ?? 0) > outputAppend.length
+          ? { key, revision: String(tool.tool.previewRevision), content: "", outputAppend,
+              footer: renderToolFooter(tool.tool, snapshot.fullToolOutputs?.[tool.id]?.length ?? 0, language) }
+          : renderTurnPreviewDetail(snapshot, key, (filePath) => this.createFileUrl(filePath), language);
+        setSecurityHeaders(response);
+        response.statusCode = detail ? 200 : 404;
+        response.setHeader("Cache-Control", "no-store");
+        response.setHeader("Content-Type", "application/json; charset=utf-8");
+        response.end(request.method === "HEAD" ? undefined : JSON.stringify(detail ? { ...detail, cursor: snapshot.previewCursor } : { error: "Turn detail not found." }));
+        return;
+      }
       if (requestUrl.searchParams.get("events") === "1") {
         this.serveTurnEvents(request, response, turnId);
         return;
       }
       const eventsUrl = new URL(this.createTurnPreviewUrl(turnId)!);
       eventsUrl.searchParams.set("events", "1");
+      if (snapshot.previewCursor !== undefined) eventsUrl.searchParams.set("after", String(snapshot.previewCursor));
       const language = detectTurnPreviewLanguage(request.headers["accept-language"]);
       const html = renderTurnPreviewPage({
         state: snapshot,
         eventsUrl: eventsUrl.toString(),
         scriptPath: `${this.basePath}/assets/turn-preview.js`.replace(/\/{2,}/gu, "/"),
         localFileUrl: (filePath) => this.createFileUrl(filePath),
+        diagramScriptPath: `${this.basePath}/assets/mermaid.js`.replace(/\/{2,}/gu, "/"),
         language,
       });
       this.sendHtml(response, 200, html, request.method === "HEAD");
@@ -683,6 +742,74 @@ export class LocalFileViewerServer {
     response.once("close", cleanup);
   }
 
+  private serveJournalEvents(request: IncomingMessage, response: ServerResponse, turnId: string, journal: TurnPreviewJournal): void {
+    journal.flush(turnId);
+    setSecurityHeaders(response);
+    response.writeHead(200, { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-cache, no-store", "X-Accel-Buffering": "no" });
+    if (request.method === "HEAD") { response.end(); return; }
+    response.flushHeaders();
+    const language = detectTurnPreviewLanguage(request.headers["accept-language"]);
+    const projection = new TurnPreviewProjection(false);
+    let offset = 0;
+    let closed = false;
+    let initial = true;
+    const cursor = request.headers["last-event-id"] ?? new URL(request.url!, "http://localhost").searchParams.get("after");
+    if (typeof cursor === "string" && /^\d+$/u.test(cursor) && Number.isSafeInteger(Number(cursor)) && Number(cursor) > 0
+      && Number(cursor) <= fs.statSync(journal.file(turnId)).size) {
+      while (offset < Number(cursor)) {
+        const batch = journal.read(turnId, offset, 256 * 1024, Number(cursor));
+        for (const record of batch.records) projection.apply(record, ++projection.revision);
+        if (batch.offset === offset) break;
+        offset = batch.offset;
+      }
+      initial = offset !== Number(cursor);
+    }
+    let waitingDrain = false;
+    const poll = () => {
+      if (closed || waitingDrain) return;
+      try {
+        projection.changed.clear();
+        projection.removed.clear();
+        const batch = journal.read(turnId, offset);
+        if (!batch.records.length) {
+          const state = projection.state;
+          if (state && ["completed", "cancelled", "failed"].includes(state.status)) {
+            const update = renderTurnPreviewPatch(state, new Set(), new Set(), (file) => this.createFileUrl(file), language);
+            response.write(`id: ${offset}\nevent: patch\ndata: ${JSON.stringify(update)}\n\n`);
+            cleanup(); response.end();
+          }
+          return;
+        }
+        offset = batch.offset;
+        for (const record of batch.records) projection.apply(record, ++projection.revision);
+        const state = projection.state;
+        if (!state) return;
+        const render = initial
+          ? renderTurnPreviewSnapshot(state, (file) => this.createFileUrl(file), language, { deferDetails: true })
+          : renderTurnPreviewPatch(state, projection.changed, projection.removed, (file) => this.createFileUrl(file), language);
+        // A terminal record can share a batch with later metadata. Drain the captured prefix first.
+        render.terminal = render.terminal && batch.end;
+        waitingDrain = !response.write(`id: ${offset}\nevent: ${initial ? "update" : "patch"}\ndata: ${JSON.stringify(render)}\n\n`);
+        initial = false;
+        if (render.terminal) { cleanup(); response.end(); }
+        else if (!batch.end) setImmediate(poll);
+      } catch (error) {
+        writeServerSentEvent(response, "unavailable", JSON.stringify({ message: "Turn preview could not be read." }));
+        cleanup();
+        response.end();
+      }
+    };
+    const poller = setInterval(poll, Math.max(50, this.options.turnPreviewPollIntervalMs ?? 1_000));
+    poller.unref();
+    const keepAlive = setInterval(() => { if (!closed && !waitingDrain) response.write(": keep-alive\n\n"); }, 15_000);
+    keepAlive.unref();
+    const cleanup = () => { closed = true; clearInterval(poller); clearInterval(keepAlive); };
+    response.on("drain", () => { waitingDrain = false; poll(); });
+    response.once("close", cleanup);
+    request.once("aborted", cleanup);
+    poll();
+  }
+
   private serveTurnEvents(request: IncomingMessage, response: ServerResponse, turnId: string): void {
     setSecurityHeaders(response);
     response.statusCode = 200;
@@ -710,7 +837,7 @@ export class LocalFileViewerServer {
       const serialized = JSON.stringify(state);
       if (serialized === previousSnapshot) return;
       previousSnapshot = serialized;
-      const snapshot = renderTurnPreviewSnapshot(state, (filePath) => this.createFileUrl(filePath), language);
+      const snapshot = renderTurnPreviewSnapshot(state, (filePath) => this.createFileUrl(filePath), language, { deferDetails: true });
       writeServerSentEvent(response, "update", JSON.stringify(snapshot));
     };
     sendSnapshot();

package/src/local-files/PreviewSyntaxHighlight.ts

@@ -0,0 +1,58 @@
+import hljs from "highlight.js/lib/common";
+import dockerfile from "highlight.js/lib/languages/dockerfile";
+import dos from "highlight.js/lib/languages/dos";
+import powershell from "highlight.js/lib/languages/powershell";
+
+hljs.registerLanguage("dockerfile", dockerfile);
+hljs.registerLanguage("dos", dos);
+hljs.registerLanguage("powershell", powershell);
+
+const LANGUAGE_ALIASES: Readonly<Record<string, string>> = { zsh: "bash", pwsh: "powershell" };
+export const MAX_PREVIEW_HIGHLIGHT_BYTES = 64 * 1024;
+const MAX_CACHE_BYTES = 1024 * 1024;
+const MAX_CACHE_ENTRIES = 32;
+const cache = new Map<string, { html: string; bytes: number }>();
+let cacheBytes = 0;
+
+// Returning an empty string asks MarkdownIt to escape the original code unchanged.
+export function highlightPreviewCode(value: string, language: string): string {
+  const name = language.trim().toLowerCase();
+  const resolved = Object.hasOwn(LANGUAGE_ALIASES, name) ? LANGUAGE_ALIASES[name]! : name;
+  if (!resolved || !hljs.getLanguage(resolved) || Buffer.byteLength(value, "utf8") > MAX_PREVIEW_HIGHLIGHT_BYTES) return "";
+  const key = `${resolved}\0${value}`;
+  const cached = cache.get(key);
+  if (cached) {
+    cache.delete(key);
+    cache.set(key, cached);
+    return cached.html;
+  }
+  try {
+    const html = hljs.highlight(value, { language: resolved, ignoreIllegals: true }).value;
+    const bytes = Buffer.byteLength(key, "utf8") + Buffer.byteLength(html, "utf8");
+    if (bytes <= MAX_CACHE_BYTES) {
+      while (cache.size >= MAX_CACHE_ENTRIES || cacheBytes + bytes > MAX_CACHE_BYTES) {
+        const oldest = cache.keys().next().value!;
+        cacheBytes -= cache.get(oldest)!.bytes;
+        cache.delete(oldest);
+      }
+      cache.set(key, { html, bytes });
+      cacheBytes += bytes;
+    }
+    return html;
+  } catch {
+    return "";
+  }
+}
+
+export const PREVIEW_SYNTAX_CSS = `
+.markdown pre { --syntax-comment:#667080; --syntax-keyword:#9639a5; --syntax-string:#087f5b; --syntax-number:#986801; --syntax-title:#005cc5; --syntax-deletion:#b31d28; }
+.markdown pre .hljs-comment, .markdown pre .hljs-quote { color:var(--syntax-comment); }
+.markdown pre .hljs-keyword, .markdown pre .hljs-selector-tag, .markdown pre .hljs-literal, .markdown pre .hljs-section, .markdown pre .hljs-link { color:var(--syntax-keyword); }
+.markdown pre .hljs-string, .markdown pre .hljs-regexp, .markdown pre .hljs-name, .markdown pre .hljs-type, .markdown pre .hljs-attribute, .markdown pre .hljs-symbol, .markdown pre .hljs-bullet, .markdown pre .hljs-addition, .markdown pre .hljs-variable, .markdown pre .hljs-template-tag, .markdown pre .hljs-template-variable { color:var(--syntax-string); }
+.markdown pre .hljs-number, .markdown pre .hljs-meta, .markdown pre .hljs-built_in, .markdown pre .hljs-builtin-name, .markdown pre .hljs-params, .markdown pre .hljs-attr { color:var(--syntax-number); }
+.markdown pre .hljs-title { color:var(--syntax-title); }
+.markdown pre .hljs-deletion { color:var(--syntax-deletion); }
+@media (prefers-color-scheme:dark) {
+  .markdown pre { --syntax-comment:#8b949e; --syntax-keyword:#ff7b72; --syntax-string:#a5d6ff; --syntax-number:#d2a8ff; --syntax-title:#79c0ff; --syntax-deletion:#ffdcd7; }
+}
+`;