@surlymochan/evalid 0.5.20 → 0.5.21

package/src/core/execution-log.js

@@ -1,8 +1,16 @@
-import { appendFile, mkdir, readFile } from 'node:fs/promises';
-import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { appendFile, mkdir, open, readFile, stat } from 'node:fs/promises';
+import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { buildLogEntryHash, validateExecutionLogChain } from './workflow-integrity.js';
 
+const TAIL_WINDOW_BYTES = 16_384;
+
+// Tail anchors are cached per log file: an append only needs the previous entry_hash, and
+// re-reading a multi-megabyte log for every event made appends O(n^2). The cache is keyed by
+// (size, mtimeMs) so an external writer (another xflow process, a rotated or truncated log that
+// lands on the same size) invalidates it instead of serving a stale anchor.
+const tailStateCache = new Map();
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -25,28 +33,34 @@ export async function appendExecutionLog(projectRoot, entry = {}) {
 async function appendExecutionLogUnlocked(projectRoot, entry = {}) {
   const file = resolveExecutionLogPath(projectRoot);
   await mkdir(dirname(file), { recursive: true });
-  const previousHash = await readLastEntryHash(file);
+  const tail = await readTailState(file);
   const payload = {
     timestamp: nowIso(),
     ...entry,
-    prev_hash: previousHash,
+    prev_hash: tail.hash,
   };
   payload.entry_hash = buildLogEntryHash(payload);
-  await appendFile(file, `${JSON.stringify(payload)}\n`, 'utf8');
+  // A crash can leave a partial trailing line; start a fresh line so the new entry stays
+  // parseable instead of being glued onto the fragment.
+  const line = `${tail.size > 0 && !tail.endsWithNewline ? '\n' : ''}${JSON.stringify(payload)}\n`;
+  await appendFile(file, line, 'utf8');
+  await rememberAppendedTail(file, payload.entry_hash);
   return file;
 }
 
 export function appendExecutionLogSync(projectRoot, entry = {}) {
   const file = resolveExecutionLogPath(projectRoot);
   mkdirSync(dirname(file), { recursive: true });
-  const previousHash = readLastEntryHashSync(file);
+  const tail = readTailStateSync(file);
   const payload = {
     timestamp: nowIso(),
     ...entry,
-    prev_hash: previousHash,
+    prev_hash: tail.hash,
   };
   payload.entry_hash = buildLogEntryHash(payload);
-  appendFileSync(file, `${JSON.stringify(payload)}\n`, 'utf8');
+  const line = `${tail.size > 0 && !tail.endsWithNewline ? '\n' : ''}${JSON.stringify(payload)}\n`;
+  appendFileSync(file, line, 'utf8');
+  rememberAppendedTailSync(file, payload.entry_hash);
   return file;
 }
 
@@ -76,32 +90,178 @@ export async function readExecutionLog(projectRoot, options = {}) {
   }
 }
 
-async function readLastEntryHash(file) {
+export async function readLastEntryHash(file) {
+  const tail = await readTailState(file);
+  return tail.hash;
+}
+
+async function readTailState(file) {
   try {
-    const raw = await readFile(file, 'utf8');
-    return lastEntryHashFromRaw(raw);
+    const info = await stat(file);
+    const cached = tailStateCache.get(file);
+    if (cached && cached.size === info.size && cached.mtimeMs === info.mtimeMs) {
+      return cached;
+    }
+    const state = {
+      size: info.size,
+      mtimeMs: info.mtimeMs,
+      hash: await readTailHash(file, info.size),
+      endsWithNewline: await tailEndsWithNewline(file, info.size),
+    };
+    tailStateCache.set(file, state);
+    return state;
+  } catch {
+    return { size: 0, mtimeMs: null, hash: null, endsWithNewline: true };
+  }
+}
+
+function readTailStateSync(file) {
+  try {
+    const info = statSync(file);
+    const cached = tailStateCache.get(file);
+    if (cached && cached.size === info.size && cached.mtimeMs === info.mtimeMs) {
+      return cached;
+    }
+    const state = {
+      size: info.size,
+      mtimeMs: info.mtimeMs,
+      hash: readTailHashSync(file, info.size),
+      endsWithNewline: tailEndsWithNewlineSync(file, info.size),
+    };
+    tailStateCache.set(file, state);
+    return state;
+  } catch {
+    return { size: 0, mtimeMs: null, hash: null, endsWithNewline: true };
+  }
+}
+
+async function readTailHash(file, size) {
+  if (!size) return null;
+  // The window must contain at least one complete line to anchor the chain. A single entry
+  // larger than the window (an error or detail field is unbounded) leaves no complete line, so
+  // the window grows until the previous entry comes into view. Returning null instead made the
+  // next append pick up prev_hash: null, which permanently breaks the chain after a restart or
+  // from a second process.
+  let windowBytes = TAIL_WINDOW_BYTES;
+  for (;;) {
+    const start = Math.max(0, size - windowBytes);
+    const hash = await readHashWindow(file, start, size);
+    if (hash !== null || start === 0) return hash;
+    windowBytes *= 4;
+  }
+}
+
+function readTailHashSync(file, size) {
+  if (!size) return null;
+  let windowBytes = TAIL_WINDOW_BYTES;
+  for (;;) {
+    const start = Math.max(0, size - windowBytes);
+    const hash = readHashWindowSync(file, start, size);
+    if (hash !== null || start === 0) return hash;
+    windowBytes *= 4;
+  }
+}
+
+async function readHashWindow(file, start, size) {
+  const handle = await open(file, 'r');
+  try {
+    const buffer = Buffer.alloc(size - start);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, start);
+    return lastEntryHashFromRaw(buffer.subarray(0, bytesRead).toString('utf8'), start > 0);
   } catch {
     return null;
+  } finally {
+    await handle.close();
   }
 }
 
-function readLastEntryHashSync(file) {
+function readHashWindowSync(file, start, size) {
+  const fd = openSync(file, 'r');
   try {
-    const raw = readFileSync(file, 'utf8');
-    return lastEntryHashFromRaw(raw);
+    const buffer = Buffer.alloc(size - start);
+    const bytesRead = readSync(fd, buffer, 0, buffer.length, start);
+    return lastEntryHashFromRaw(buffer.subarray(0, bytesRead).toString('utf8'), start > 0);
   } catch {
     return null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Record the anchor that was just written. One cheap stat keeps the cache key (size, mtimeMs)
+ * honest, so a later writer that rewrites the file at the same size invalidates the entry.
+ */
+async function rememberAppendedTail(file, entryHash) {
+  try {
+    const info = await stat(file);
+    tailStateCache.set(file, {
+      size: info.size,
+      mtimeMs: info.mtimeMs,
+      hash: entryHash,
+      endsWithNewline: true,
+    });
+  } catch {
+    tailStateCache.delete(file);
+  }
+}
+
+function rememberAppendedTailSync(file, entryHash) {
+  try {
+    const info = statSync(file);
+    tailStateCache.set(file, {
+      size: info.size,
+      mtimeMs: info.mtimeMs,
+      hash: entryHash,
+      endsWithNewline: true,
+    });
+  } catch {
+    tailStateCache.delete(file);
   }
 }
 
-function lastEntryHashFromRaw(raw) {
-  const lines = raw.split('\n').map((line) => line.trim()).filter(Boolean);
+async function tailEndsWithNewline(file, size) {
+  if (!size) return true;
+  const handle = await open(file, 'r');
+  try {
+    const buffer = Buffer.alloc(1);
+    const { bytesRead } = await handle.read(buffer, 0, 1, size - 1);
+    return bytesRead === 0 || buffer[0] === 0x0a;
+  } catch {
+    return true;
+  } finally {
+    await handle.close();
+  }
+}
+
+function tailEndsWithNewlineSync(file, size) {
+  if (!size) return true;
+  const fd = openSync(file, 'r');
+  try {
+    const buffer = Buffer.alloc(1);
+    const bytesRead = readSync(fd, buffer, 0, 1, size - 1);
+    return bytesRead === 0 || buffer[0] === 0x0a;
+  } catch {
+    return true;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function lastEntryHashFromRaw(raw, startedMidLine = false) {
+  const lines = raw.split('\n');
+  if (startedMidLine) {
+    // The first line of a tail window is usually a fragment; it cannot anchor the chain.
+    lines.shift();
+  }
   for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index].trim();
+    if (!line) continue;
     try {
-      const entry = JSON.parse(lines[index]);
+      const entry = JSON.parse(line);
       if (entry.entry_hash) return entry.entry_hash;
     } catch {
-      return null;
+      // A corrupt or truncated trailing line must not reset the chain; keep scanning upwards.
     }
   }
   return null;

package/src/core/log-tail.js

@@ -0,0 +1,176 @@
+/**
+ * log-tail — byte-offset reader for the hash-chained execution log.
+ *
+ * The execution log (.as-xflow/logs/execution.ndjson) is the single source of truth for
+ * workflow progress: the CLI writes it, `xflow serve` reads it. Live consumers therefore tail
+ * it by byte offset instead of re-reading it, and resume from the `entry_hash` they last saw
+ * (SSE Last-Event-ID). Every offset returned here sits on a line boundary, so a consumer never
+ * observes half an entry.
+ */
+import { open, stat } from 'node:fs/promises';
+import { resolveExecutionLogPath } from './execution-log.js';
+
+export const DEFAULT_TAIL_LIMIT = 200;
+export const MAX_TAIL_READ_BYTES = 4 * 1024 * 1024;
+const OVERSCAN_BYTES = 64 * 1024;
+const MAX_OVERSCAN_BYTES = 64 * 1024 * 1024;
+
+export async function readExecutionLogSize(projectRoot = process.cwd()) {
+  try {
+    return (await stat(resolveExecutionLogPath(projectRoot))).size;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Read the entries written after `offset`.
+ *
+ * Returns { entries, nextOffset, size, hasMore, partial, eof }. `nextOffset` only ever advances
+ * past a complete line, so an entry that is still being written is re-read (not skipped) on the
+ * next call. `limit` caps one call so a large backlog is drained over several calls instead of
+ * one unbounded read.
+ */
+export async function readEntriesFromOffset(projectRoot = process.cwd(), offset = 0, options = {}) {
+  const file = resolveExecutionLogPath(projectRoot);
+  const limit = Math.max(1, Math.floor(Number(options.limit) || DEFAULT_TAIL_LIMIT));
+  const size = await readExecutionLogSize(projectRoot);
+  const requested = Math.floor(Number(offset) || 0);
+  const start = Math.min(Math.max(0, requested), size);
+  if (start >= size) {
+    return { file, entries: [], nextOffset: size, size, hasMore: false, partial: false, eof: true };
+  }
+
+  const end = Math.min(size, start + MAX_TAIL_READ_BYTES);
+  const window = await readRange(file, start, end);
+  const entries = [];
+  let cursor = 0;
+  let nextOffset = start;
+  let sawNewline = false;
+
+  while (entries.length < limit) {
+    const newlineAt = window.indexOf(0x0a, cursor);
+    if (newlineAt === -1) break;
+    sawNewline = true;
+    const line = window.subarray(cursor, newlineAt).toString('utf8').trim();
+    cursor = newlineAt + 1;
+    nextOffset = start + cursor;
+    if (!line) continue;
+    entries.push(parseEntryLine(line));
+  }
+
+  if (!sawNewline && end < size) {
+    // One entry larger than the read window would stall the tail forever (the same offset
+    // would be returned on every poll). Skip to the next line boundary and tell the caller.
+    const skippedTo = await skipOversizedLine(file, end, size);
+    entries.push({
+      kind: 'invalid_log_line',
+      raw: 'line_exceeds_read_window',
+      reason: 'entry_larger_than_read_window',
+      truncated: true,
+    });
+    return {
+      file,
+      entries,
+      nextOffset: skippedTo,
+      size,
+      hasMore: skippedTo < size,
+      partial: false,
+      eof: skippedTo >= size,
+    };
+  }
+
+  return {
+    file,
+    entries,
+    nextOffset,
+    size,
+    hasMore: nextOffset < size,
+    // Anything left in the window sits after the last newline, i.e. an entry still being written.
+    partial: cursor < window.length,
+    eof: nextOffset >= size,
+  };
+}
+
+/**
+ * Map an entry_hash to the byte offset just past that entry.
+ *
+ * Returns null when the hash is unknown (rotated or deleted log), which callers treat as
+ * "replay is impossible, fall back to a snapshot" rather than as an error.
+ */
+export async function resolveEntryOffset(projectRoot = process.cwd(), entryHash) {
+  const wanted = String(entryHash || '').trim();
+  if (!wanted) return null;
+  const file = resolveExecutionLogPath(projectRoot);
+  let size;
+  try {
+    size = (await stat(file)).size;
+  } catch {
+    return null;
+  }
+  if (!size) return null;
+
+  // A reconnect resolves a single hash, and the entry the client last saw is almost always
+  // among the most recent ones, so scan the tail first and widen the window until the log is
+  // covered. Every window ends at EOF on purpose: a window that stopped at an arbitrary offset
+  // would split an entry across two reads and never see it whole.
+  let windowBytes = OVERSCAN_BYTES;
+  for (;;) {
+    const start = Math.max(0, size - windowBytes);
+    const window = await readRange(file, start, size);
+    const offset = matchEntryOffset(window, start, wanted);
+    if (offset !== null) return offset;
+    if (start === 0) return null;
+    windowBytes *= 4;
+  }
+}
+
+function matchEntryOffset(window, base, wanted) {
+  let cursor = 0;
+  while (cursor < window.length) {
+    const newlineAt = window.indexOf(0x0a, cursor);
+    if (newlineAt === -1) break;
+    const line = window.subarray(cursor, newlineAt).toString('utf8').trim();
+    cursor = newlineAt + 1;
+    if (!line) continue;
+    try {
+      if (JSON.parse(line).entry_hash === wanted) return base + cursor;
+    } catch {
+      // Corrupt lines cannot match a hash; keep scanning.
+    }
+  }
+  return null;
+}
+
+function parseEntryLine(line) {
+  try {
+    const entry = JSON.parse(line);
+    return entry && typeof entry === 'object' ? entry : { kind: 'invalid_log_line', raw: line.slice(0, 512) };
+  } catch {
+    return { kind: 'invalid_log_line', raw: line.slice(0, 512), reason: 'invalid_json' };
+  }
+}
+
+async function readRange(file, start, end) {
+  const handle = await open(file, 'r');
+  try {
+    const buffer = Buffer.alloc(end - start);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, start);
+    return buffer.subarray(0, bytesRead);
+  } finally {
+    await handle.close();
+  }
+}
+
+async function skipOversizedLine(file, from, size) {
+  let position = from;
+  while (position < size) {
+    const chunkEnd = Math.min(size, position + OVERSCAN_BYTES);
+    const chunk = await readRange(file, position, chunkEnd);
+    const newlineAt = chunk.indexOf(0x0a);
+    if (newlineAt !== -1) return position + newlineAt + 1;
+    position = chunkEnd;
+    if (position - from > MAX_OVERSCAN_BYTES) return position;
+  }
+  return size;
+}

package/src/server.js

@@ -23,6 +23,7 @@ import {
 } from './core/mission-state.js';
 import { mutateStore, readStore, resolveDataFile } from './core/state-store.js';
 import { readExecutionLog, resolveExecutionLogPath } from './core/execution-log.js';
+import { readEntriesFromOffset, readExecutionLogSize, resolveEntryOffset } from './core/log-tail.js';
 import { ackPendingGate, listPendingGates } from './core/pending-gates.js';
 import { prepareWorkflowRerun } from './core/workflow-rerun.js';
 import { readBinding } from './core/bindings.js';
@@ -140,7 +141,11 @@ function sendHtml(response, statusCode, html) {
   response.end(html);
 }
 
-function sendEvent(response, event, payload) {
+function sendEvent(response, event, payload, id) {
+  if (response.writableEnded || response.destroyed) return;
+  // `id` is optional: entries written by older builds carry no entry_hash, and an empty id line
+  // would make the browser replay from a meaningless position.
+  if (id) response.write(`id: ${id}\n`);
   response.write(`event: ${event}\n`);
   response.write(`data: ${JSON.stringify(payload)}\n\n`);
 }
@@ -526,10 +531,22 @@ function renderDashboardHtml() {
           '</div>'
         )).join('') || '<div class="meta">No pending gates</div>';
       }
-      function renderActivity(entries) {
-        document.getElementById('activity').innerHTML = entries.map((entry) => (
-          '<li><div><strong>' + (entry.atom_id || entry.kind || 'event') + '</strong></div>' +
-          '<div class="meta">' + [
+      let activityEntries = [];
+      // Hashes already on screen. Seeded from the snapshot as well as from log events: an
+      // entry can arrive twice, once inside the snapshot and once as a stream event written
+      // between the snapshot read and the point where the stream started.
+      const seenHashes = new Set();
+      function describeEntry(entry) {
+        if (entry.kind === 'agent_event') {
+          const detail = entry.text || entry.args_preview || entry.reason || '';
+          return {
+            title: entry.event + (entry.tool ? ' · ' + entry.tool : ''),
+            meta: [entry.phase, entry.atom, detail ? String(detail).slice(0, 120) : '', entry.timestamp],
+          };
+        }
+        return {
+          title: entry.atom_id || entry.kind || 'event',
+          meta: [
             entry.phase_id,
             entry.status,
             entry.adapter,
@@ -537,8 +554,44 @@ function renderDashboardHtml() {
             entry.artifact_type,
             entry.parallel_weight ? 'weight ' + entry.parallel_weight : '',
             entry.timestamp,
-          ].filter(Boolean).join(' · ') + '</div></li>'
-        )).join('') || '<li class="meta">No execution activity yet</li>';
+          ],
+        };
+      }
+      function paintActivity() {
+        document.getElementById('activity').innerHTML = activityEntries.map((entry) => {
+          const view = describeEntry(entry);
+          return '<li><div><strong>' + view.title + '</strong></div>' +
+            '<div class="meta">' + view.meta.filter(Boolean).join(' · ') + '</div></li>';
+        }).join('') || '<li class="meta">No execution activity yet</li>';
+      }
+      // A snapshot carries entries a log event may already have painted. Merging by entry_hash
+      // instead of replacing the list keeps anything that arrived while the snapshot was in
+      // flight (replacing it made those rows disappear again for up to one snapshot interval).
+      // Entries already on screen stay first: they are strictly newer than anything the snapshot
+      // adds, so this preserves file order without trusting timestamps.
+      function renderActivity(entries, options) {
+        const incoming = entries.slice(0, 20);
+        for (const entry of incoming) {
+          if (entry.entry_hash) seenHashes.add(entry.entry_hash);
+        }
+        if (options && options.merge) {
+          const merged = activityEntries.slice();
+          const seen = new Set(merged.map((entry) => entry.entry_hash).filter(Boolean));
+          for (const entry of incoming) {
+            if (entry.entry_hash && seen.has(entry.entry_hash)) continue;
+            if (entry.entry_hash) seen.add(entry.entry_hash);
+            merged.push(entry);
+          }
+          activityEntries = merged.slice(0, 20);
+        } else {
+          activityEntries = incoming;
+        }
+        paintActivity();
+      }
+      function appendActivity(entry) {
+        activityEntries.unshift(entry);
+        if (activityEntries.length > 20) activityEntries.length = 20;
+        paintActivity();
       }
       async function refreshFallback() {
         const [summaryRes, gatesRes, logsRes] = await Promise.all([
@@ -617,7 +670,15 @@ function renderDashboardHtml() {
           const payload = JSON.parse(event.data);
           renderSummary(payload.summary);
           renderGates(payload.pending_gates || []);
-          renderActivity(payload.execution_log?.entries || []);
+          renderActivity(payload.execution_log?.entries || [], { merge: true });
+        });
+        events.addEventListener('log', (event) => {
+          const entry = JSON.parse(event.data);
+          if (entry.entry_hash) {
+            if (seenHashes.has(entry.entry_hash)) return;
+            seenHashes.add(entry.entry_hash);
+          }
+          appendActivity(entry);
         });
         events.onerror = () => {
           events.close();
@@ -816,22 +877,68 @@ export default async function startServer(options = {}) {
       });
       response.write('\n');
 
+      let closed = false;
+      let offset = null;
+
       const sendSnapshot = async () => {
         const nextState = await readStore(dataFile);
         sendEvent(response, 'snapshot', await buildSnapshot(projectRoot, nextState));
       };
 
+      // Append-only tail of the execution log. Each entry is one `log` event whose SSE id is the
+      // entry hash, so a reconnecting client resumes from Last-Event-ID instead of re-reading.
+      const sendNewEntries = async () => {
+        const batch = await readEntriesFromOffset(projectRoot, offset, { limit: 100 });
+        offset = batch.nextOffset;
+        for (const entry of batch.entries) {
+          sendEvent(response, 'log', entry, entry.entry_hash);
+        }
+      };
+
+      const lastEventId = String(request.headers['last-event-id'] || '').trim();
+      if (lastEventId) {
+        const resumed = await resolveEntryOffset(projectRoot, lastEventId);
+        if (resumed !== null) offset = resumed;
+      }
+
+      if (offset === null) {
+        // A fresh client already has history in the snapshot, so follow only entries from here on.
+        // The offset is taken before the snapshot is written: anything that lands in between is
+        // tailed right after it and deduplicated client-side by entry_hash, so nothing is missed.
+        offset = await readExecutionLogSize(projectRoot);
+      }
+
+      // Snapshot stays the first frame: the dashboard relies on it for summary and gates.
+      await sendSnapshot();
+      await sendNewEntries().catch(() => {});
+
+      const tail = async () => {
+        if (closed) return;
+        try {
+          await sendNewEntries();
+        } catch {
+          // A transient read failure must not kill the stream; the next tick retries.
+        }
+      };
+
       const heartbeat = setInterval(() => {
-        response.write(': ping\n\n');
+        if (!closed) response.write(': ping\n\n');
       }, 15000);
       const timer = setInterval(() => {
-        sendSnapshot().catch(() => {});
+        if (!closed) sendSnapshot().catch(() => {});
       }, 3000);
+      // One tailer per connection: the read is a stat plus a short read from the last offset, so a
+      // dashboard tab costs a few hundred bytes per tick. If many clients ever watch the same run,
+      // the cheaper shape is one shared tailer broadcasting to all responses.
+      const tailer = setInterval(() => {
+        tail().catch(() => {});
+      }, 200);
 
-      await sendSnapshot();
       request.on('close', () => {
+        closed = true;
         clearInterval(timer);
         clearInterval(heartbeat);
+        clearInterval(tailer);
       });
       return;
     }