@surlymochan/evalid 0.5.20 → 0.5.21

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project are documented here. Detailed notes live in
 [RELEASE_NOTES.md](RELEASE_NOTES.md).
 
+## [0.5.21] - 2026-11-10
+
+### Added
+- **Agent progress streaming through the execution log and SSE, external contribution (#95)**: `xflow workflow run` now streams live agent progress — `codex exec --json` and `claude --output-format stream-json --verbose` feed the execution log as the event bus, `entry_hash` is the resume token, and `xflow serve` pushes the stream over SSE. Appends no longer re-read the whole file (tail cache + 16 KB tail read, expanding to a full line when the last entry exceeds the window); a >16 KB last entry no longer breaks the hash chain on a cold cache. Test evidence: 32/32 across the four affected test files (`test/agent-stream.test.js`, `test/log-tail.test.js`, `test/execution-log.test.js`, `test/server.test.js`) locally; demo `node scripts/demo-agent-stream.mjs` 5 pushed / 5 written / 5 received over SSE, latency 16–419 ms; PR CI runs verify 42761169188 and ledger 42761169204 both pass on the final HEAD; merged main CI run 42762022933 success.
+
+Milestone M4 "lite fast track" — **not yet accepted**: this release ships no M4 slice; slices 1–4 remain merged checkpoints and the wall-clock verdict still awaits bench numbers. This release makes no M4 acceptance claim.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2 / P1-3 / P2-1 / P2-3 still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), which is at 98/135 with the 15th relaunch in flight. No bench numbers are claimed in this release.
+
 ## [0.5.20] - 2026-11-10
 
 ### Added

package/RELEASE_NOTES.md

@@ -1,5 +1,15 @@
 # Release Notes
 
+## 0.5.21 - Agent progress streaming (external contribution #95)
+
+Patch release. One merged PR since 0.5.20, verified end to end in CI and locally.
+
+**Agent progress streaming through the execution log and SSE (#95, author MAOLVLHL).** `xflow workflow run` now streams live agent progress: `codex exec --json` and `claude --output-format stream-json --verbose` feed the execution log as the event bus, `entry_hash` is the resume token, and `xflow serve` pushes the stream over SSE. Appends no longer re-read the whole file (tail cache + 16 KB tail read, expanding to a full line when the last entry exceeds the window); a >16 KB last entry no longer breaks the hash chain on a cold cache (verified with a cold-cache reproduction: a fresh process appending after a 20 KB entry keeps the chain intact). Test evidence: 32/32 across the four affected test files locally; demo `node scripts/demo-agent-stream.mjs` 5 pushed / 5 written / 5 received over SSE, latency 16–419 ms; PR CI runs verify 42761169188 and ledger 42761169204 both pass on the final HEAD; merged main CI run 42762022933 success. Maintainer fix on the branch: the author's fix commit had dropped the executable bit on `bin/xflow.js`, breaking one CLI usability test — restored mode-only (commit fcd81d8) before merge.
+
+Milestone M4 "lite fast track" — **not yet accepted.** This release ships no M4 slice; the wall-clock verdict still awaits bench numbers.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2, P1-3, P2-1 and P2-3 — the wall-clock/token/resolved lines from issue #5 — still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), which is at 98/135 with the 15th relaunch in flight. No bench numbers are claimed in this release.
+
 ## 0.5.20 - M4 lite fast track, slices 3–4 (milestone M4 not yet accepted)
 
 Patch release. Two merged PRs since 0.5.19, both verified end to end in CI and locally.

package/bin/xflow.js

@@ -42,6 +42,7 @@ import { createHash } from 'crypto';
 import { tmpdir } from 'os';
 import { ackPendingGate } from '../src/core/pending-gates.js';
 import { runAudit, renderAuditReport } from '../src/core/audit.js';
+import { readEntriesFromOffset, readExecutionLogSize } from '../src/core/log-tail.js';
 import { exportDomRectsToFile, resolveCliPath } from '../src/agent_team/atoms/visual/dom-rect-export.js';
 import { capturePageEvidence } from '../src/agent_team/atoms/visual/page-evidence-capture.js';
 import { computeImageDiffMetrics } from '../src/agent_team/atoms/visual/image-diff.js';
@@ -5508,7 +5509,12 @@ async function handleWorkflow(sub, args) {
           changeId,
           input,
         });
-        await executor.run();
+        const progress = args.includes('--progress') ? startProgressTail(projectRoot) : null;
+        try {
+          await executor.run();
+        } finally {
+          if (progress) await progress.stop();
+        }
       }
       break;
     }
@@ -5538,6 +5544,72 @@ async function handleWorkflow(sub, args) {
   }
 }
 
+// ─── progress tail ────────────────────────────────────────────────────────────
+
+const PROGRESS_TICK_MS = 200;
+
+/**
+ * Follow the execution log on stderr while a workflow runs.
+ *
+ * Opt-in (`--progress`) so the default CLI output stays byte-identical, and stderr-only so it
+ * cannot corrupt anything a caller pipes out of stdout.
+ */
+function startProgressTail(projectRoot, { tickMs = PROGRESS_TICK_MS } = {}) {
+  let offset = null;
+  let stopped = false;
+  let draining = Promise.resolve();
+
+  const drain = async () => {
+    if (offset === null) offset = await readExecutionLogSize(projectRoot);
+    // A run that emits faster than one tick writes more than a single batch, so keep reading
+    // until the log is caught up: one capped read left the tail of a chatty run unprinted.
+    for (;;) {
+      const from = offset;
+      const batch = await readEntriesFromOffset(projectRoot, from, { limit: 100 });
+      offset = batch.nextOffset;
+      for (const entry of batch.entries) {
+        process.stderr.write(`${formatProgressEntry(entry)}\n`);
+      }
+      // Stop when the log is caught up, or when the last batch could not advance past a
+      // half-written entry (re-read on the next tick or on shutdown).
+      if (!batch.hasMore || offset <= from) return;
+    }
+  };
+
+  draining = drain().catch(() => {});
+  const timer = setInterval(() => {
+    if (stopped) return;
+    draining = draining.then(drain).catch(() => {});
+  }, tickMs);
+
+  return {
+    async stop() {
+      stopped = true;
+      clearInterval(timer);
+      await draining.catch(() => {});
+      // Drain whatever was written between the last tick and shutdown.
+      await drain().catch(() => {});
+    },
+  };
+}
+
+function formatProgressEntry(entry) {
+  const time = String(entry.timestamp || '').slice(11, 19);
+  if (entry.kind === 'agent_event') {
+    const detail = entry.tool || entry.text || entry.reason || entry.event_type || '';
+    return `[progress] ${time} agent ${entry.event}${detail ? ' · ' + singleLine(detail) : ''}`;
+  }
+  const subject = entry.atom_id || entry.phase_id || null;
+  const parts = [entry.kind || 'event'];
+  if (subject && subject !== entry.kind) parts.push(subject);
+  if (entry.status) parts.push(entry.status);
+  return `[progress] ${time} ${parts.join(' ')}`;
+}
+
+function singleLine(value) {
+  return String(value).replace(/\s+/g, ' ').slice(0, 120);
+}
+
 const CORPS_PROOF_ARTIFACTS = [
   'status.json',
   'proposal.md',
@@ -6703,7 +6775,8 @@ function printWorkflowHelp() {
 Usage: xflow workflow <command>
 
 Commands:
-  run <yaml|yolo|corps>       Run a workflow (add --dry-run to preview)
+  run <yaml|yolo|corps>       Run a workflow (add --dry-run to preview,
+                              --progress to follow agent events on stderr)
   validate <yaml|yolo|corps>  Validate workflow YAML as preflight only
 
 Options:

package/docs/launch-dossier.md

@@ -117,7 +117,7 @@ Evidence:
 - Adoption records: 1; status: pass
 - Goal audit: pass; goal: Keep evalid credible as an open-source agent delivery runtime: repo-owned workflow contracts, executable verification gates, durable project context, and honest benchmark evidence.
 - Package evidence: missing; source: registry_json
-- Package name/version: @surlymochan/evalid@0.5.20
+- Package name/version: @surlymochan/evalid@0.5.21
 
 ## Passing Evidence
 

package/docs/workflow-manual.md

@@ -17,7 +17,8 @@
 9. [CLI 参考](#9-cli-参考)
 10. [本地 Release Checklist](#10-本地-release-checklist)
 11. [环境变量](#11-环境变量)
-12. [常见问题](#12-常见问题)
+12. [实时事件流（agent 进度）](#12-实时事件流agent-进度)
+13. [常见问题](#13-常见问题)
 
 ---
 
@@ -1077,7 +1078,109 @@ sh xflow/scripts/check_installed_xflow_skill_sync.sh
 
 ---
 
-## 12. 常见问题
+## 12. 实时事件流（agent 进度）
+
+`agent_invoke` 一次调用默认最长 300 秒（heavy CLI 1800 秒），期间 agent 的 stdout 以前只累加进字符串，运行结束时才有一条 `atom_run`。现在这段时间里发生的事会以 `agent_event` 条目写入 `.as-xflow/logs/execution.ndjson`，并通过 `/api/events` 增量推给看板。
+
+### 数据通路
+
+```
+codex exec --json  /  claude -p --output-format stream-json
+        │  stdout（NDJSON，逐行）
+        ▼
+src/core/agent-stream.js   createLineSplitter → normalizeAgentEvent → 200ms 合并
+        │  appendExecutionLog({ kind: 'agent_event', … })
+        ▼
+.as-xflow/logs/execution.ndjson   （既有 hash 链，一条一条追加）
+        │  src/core/log-tail.js   readEntriesFromOffset(offset)
+        ▼
+GET /api/events   event: log, id: <entry_hash>
+```
+
+写入侧只做归一化与截断，读侧只做字节偏移 tail；两侧都复用既有的执行日志，没有新增文件、没有新增依赖。
+
+只有能逐行输出 NDJSON 的 adapter 会接上这条通路：`codex_cli`（`codex exec --json`）与 `claude_cli`（`claude -p --output-format stream-json`）。`pencil_cli` 没有对应的 JSON 行协议，`stub` 根本没有子进程，因此这两者不产生 `agent_event`，其进度只能看到 phase/atom 级的 `atom_run` 记录——这是刻意的，不是遗漏。
+
+### 事件类型
+
+| event | 来源 | 关键字段 |
+|---|---|---|
+| `agent_start` | codex `thread.started` / claude `system:init` | `adapter` |
+| `tool_start` | codex `item.started`：`command_execution`(→ `tool`=`shell`)、`mcp_tool_call`、`file_change`、`web_search`；claude `tool_use` | `event_type`(CLI 原始 item 类型), `tool`, `args_preview`(≤160 字符), `args_digest`(sha256 前 16 位) |
+| `tool_end` | codex `item.completed` 的同四种 item 类型（`event_type` 区分）；claude 侧没有配对事件 | `event_type`, `tool`, `exit_code`, `status` |
+| `message_end` | codex `agent_message` / claude assistant `text` | `text`(≤2048 字符，超出以 `…` 结尾) |
+| `agent_end` | codex `turn.completed` / claude `result` | `usage`{`input`,`output`,`cache_read`,`cache_write`}, `cost_usd`, `duration_ms` |
+| `raw` | 无法识别、无法解析、或超长被截断的行；CLI 报错（`turn.failed` / `error`） | `reason`(`invalid_json` / `non_object_payload` / `line_truncated`), `event_type`, `level`(`error`), `truncated` |
+
+每条记录的完整形状：
+
+```json
+{
+  "timestamp": "2026-11-09T04:12:33.412Z",
+  "kind": "agent_event",
+  "event": "tool_start",
+  "phase": "implementation",
+  "atom": "I6a.tdd.run",
+  "adapter": "codex_cli",
+  "seq": 3,
+  "event_type": "command_execution",
+  "tool": "shell",
+  "args_preview": "npm test",
+  "args_digest": "9f2c1e0b7d4a5c88",
+  "change_id": "chg-124",
+  "mission_id": "mis-9",
+  "prev_hash": "…",
+  "entry_hash": "…"
+}
+```
+
+未知的 CLI 事件类型一律降级为 `raw` 或被忽略，不抛错：CLI 升级不会让整条 workflow 失败。
+
+### 订阅
+
+```javascript
+const events = new EventSource('/api/events');
+const seen = new Set();
+
+events.addEventListener('snapshot', () => { /* 首帧仍是全量快照，可整体重置 UI */ });
+events.addEventListener('log', (message) => {
+  const entry = JSON.parse(message.data);
+  if (entry.entry_hash && seen.has(entry.entry_hash)) return;  // 快照与增量可能重叠
+  if (entry.entry_hash) seen.add(entry.entry_hash);
+  renderActivity(entry);
+});
+```
+
+- 首帧永远是 `event: snapshot`（与旧行为一致），之后才是增量。
+- 增量帧带 `id: <entry_hash>`；浏览器断线重连会自动带上 `Last-Event-ID`，服务端据此回放缺失条目，不丢也不重。
+- 若该 id 对应的日志已被删除或轮转，服务端回退为正常跟随（客户端拿不到历史，只收到之后的新条目）。
+- `event: snapshot` 仍然每 3 秒重发一次。增量流只解决了“一条条新条目怎么到达”，没有取消全量快照：看板的 summary、pending gates、pending tasks 都由快照刷新，增量帧里没有这些字段。也就是说常驻连接的主要带宽仍是快照；要再降，需要把 summary/gates 也改成增量事件，那是另一个 PR 的边界。
+- 排序一律以文件顺序为准，不要用 `timestamp` 排序：同一毫秒内可能有多条。
+
+### CLI 进度输出
+
+```bash
+CHANGE_ID=<id> xflow workflow run workflows/yolo.yaml --progress
+```
+
+`--progress` 是 opt-in 的：不加时终端输出与以前逐字节一致。开启后每 200ms 把新条目打印到 stderr（stdout 留给 workflow 自己的输出），例如：
+
+```
+[progress] 12:13:02 agent tool_start · shell
+[progress] 12:13:41 agent message_end · Tests pass; writing the artifact.
+[progress] 12:13:44 atom_run I6a.tdd.run completed
+```
+
+### 性能约束
+
+- 写入：每 200ms 合并一次，单条 `text` ≤2048 字符、`args_preview` ≤160 字符；队列上限 500，超出丢最旧条目并计入 `stats.dropped`。
+- 读取：只从字节偏移往后读，单次 ≤4MB；未写完的尾行留到下次；游标只停在换行边界。
+- 哈希链：追加时从文件尾部 16KB 起求 `prev_hash`；若窗口里没有完整行（单条记录大于 16KB），窗口按 4 倍扩大直到找到为止，否则会写出 `prev_hash: null` 把链断掉。缓存按 `(size, mtimeMs)` 失效，避免同尺寸的轮转或截断命中陈旧哈希。
+- 订阅：每个 SSE 连接各自持有一个 200ms 的 tailer，一次 tick 是“stat + 从上次偏移读一小段”，单个看板标签页可以忽略；若将来有大量客户端同时观看同一 run，更省的形状是**一个共享 tailer 广播给所有连接**（当前版本未做）。
+
+---
+
+## 13. 常见问题
 
 ### workflow 停在 human gate 怎么恢复？
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surlymochan/evalid",
-  "version": "0.5.20",
+  "version": "0.5.21",
   "description": "Claimed != verified: a runtime verification layer for coding agents. It seals each test run and replays it from a clean snapshot, with a zero-judge gate pipeline (spec clarification, code review, TDD proof) and the xflow CLI.",
   "keywords": [
     "ai-agents",

package/scripts/demo-agent-stream.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * demo-agent-stream.mjs — proves the agent progress path end to end.
+ *
+ * Feeds synthetic codex events through `createAgentEventSink` (the same sink
+ * `agent_invoke` uses), then prints each one as `xflow serve` delivers it over
+ * /api/events, together with the observed latency. No agent CLI is required.
+ *
+ *   node scripts/demo-agent-stream.mjs
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import startServer from '../src/server.js';
+import { createAgentEventSink } from '../src/core/agent-stream.js';
+
+const PUSH_INTERVAL_MS = 200;
+const FIXTURE = [
+  '{"type":"thread.started","thread_id":"thread_demo"}',
+  '{"type":"item.started","item":{"id":"i1","type":"command_execution","command":"npm test"}}',
+  '{"type":"item.completed","item":{"id":"i1","type":"command_execution","command":"npm test","exit_code":0,"status":"completed"}}',
+  '{"type":"item.completed","item":{"id":"i2","type":"agent_message","text":"Tests pass; writing the artifact."}}',
+  '{"type":"turn.completed","usage":{"input_tokens":1200,"output_tokens":340}}',
+];
+
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+
+function labelOf(entry) {
+  if (entry.event === 'agent_start') return 'agent_start';
+  if (entry.event === 'agent_end') return 'agent_end';
+  if (entry.tool) return `${entry.event} ${entry.tool}`;
+  return `${entry.event} ${String(entry.text || '').slice(0, 40)}`;
+}
+
+const projectRoot = mkdtempSync(join(tmpdir(), 'xflow-demo-stream-'));
+const server = await startServer({ projectRoot, port: 0 });
+const base = `http://127.0.0.1:${server.address().port}`;
+const startedAt = Date.now();
+const sentAt = new Map();
+
+console.log(`[demo] project root: ${projectRoot}`);
+console.log(`[demo] dashboard:    ${base}/`);
+console.log(`[demo] pushing ${FIXTURE.length} synthetic codex events, one every ${PUSH_INTERVAL_MS}ms\n`);
+
+const sink = createAgentEventSink({
+  projectRoot,
+  changeId: 'chg-demo-stream',
+  missionId: 'mis-demo',
+  phase: 'demo phase',
+  atom: 'demo.atom',
+  adapter: 'codex_cli',
+});
+
+const streamResponse = await fetch(`${base}/api/events`);
+const reader = streamResponse.body.getReader();
+const decoder = new TextDecoder();
+const latencies = [];
+let buffer = '';
+let received = 0;
+
+const pump = (async () => {
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let frameEnd = buffer.indexOf('\n\n');
+    while (frameEnd !== -1) {
+      const frame = buffer.slice(0, frameEnd);
+      buffer = buffer.slice(frameEnd + 2);
+      frameEnd = buffer.indexOf('\n\n');
+      // Frames carry an `id:` line first, so match the event name rather than the first line.
+      if (!frame.includes('event: log')) continue;
+      const data = frame.split('\n').find((line) => line.startsWith('data: '));
+      if (!data) continue;
+      const entry = JSON.parse(data.slice(6));
+      const label = labelOf(entry);
+      const elapsed = Date.now() - startedAt;
+      const latency = sentAt.has(label) ? Date.now() - sentAt.get(label) : null;
+      if (latency !== null) latencies.push(latency);
+      received += 1;
+      console.log(
+        `[demo] +${String(elapsed).padStart(5)}ms  ${label.padEnd(26)} ` +
+        `phase=${entry.phase} atom=${entry.atom} id=${String(entry.entry_hash).slice(0, 8)}…` +
+        (latency === null ? '' : `  latency=${latency}ms`),
+      );
+    }
+  }
+})();
+
+for (const line of FIXTURE) {
+  const entry = JSON.parse(line);
+  sentAt.set(labelOf({
+    event: entry.type === 'thread.started' ? 'agent_start'
+      : entry.type === 'turn.completed' ? 'agent_end'
+        : entry.item?.type === 'command_execution' ? 'tool_start'
+          : 'message_end',
+    tool: entry.item?.type === 'command_execution' ? 'shell' : null,
+    text: entry.item?.text,
+  }), Date.now());
+  sink.push(`${line}\n`);
+  await sleep(PUSH_INTERVAL_MS);
+}
+await sink.close();
+await sleep(500);
+await reader.cancel();
+
+const stats = sink.stats;
+console.log(`\n[demo] events pushed: ${stats.events}, written: ${stats.written}, received over SSE: ${received}`);
+if (latencies.length) {
+  const min = Math.min(...latencies);
+  const max = Math.max(...latencies);
+  console.log(`[demo] end-to-end latency (push -> SSE): min ${min}ms, max ${max}ms over ${latencies.length} events`);
+}
+console.log('[demo] open the dashboard URL above while this script runs to watch the same stream live.');
+
+await pump.catch(() => {});
+await new Promise((resolveClose) => server.close(resolveClose));
+rmSync(projectRoot, { recursive: true, force: true });