@haiyangbg/buildbeat 2.0.0-beta.2 → 2.0.0-beta.4

package/src/v2/runtime/liveness.js

@@ -0,0 +1,193 @@
+// Liveness and timing, derived only from the ledger and the live output
+// streams the shell adapter leaves in the run directory. Nothing here is
+// written to the ledger: "how long has this been running" and "when did the
+// worker last print something" are readings, not facts a Run must carry.
+//
+// Real incident (deploy campaign, 2026-08-30): the owner asked "半小时了，
+// 正常吗 / 十分钟了，是卡住了吗" more than ten times because status showed
+// steps and attempts and nothing about time. This module is that answer.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { EventLedger } from "../storage/event-ledger.js";
+import { LIVE_MARKER } from "../adapters/shell.js";
+
+export const DEFAULT_STALL_AFTER_MS = 15 * 60 * 1000;
+
+export function runDir(repoRoot, runId) {
+  return join(repoRoot, ".buildbeat", "runtime", "runs", runId);
+}
+
+// Every step attempt as a timed row; the in-flight one (if any) has no end.
+export function stepTimeline(events) {
+  const open = new Map();
+  const rows = [];
+  let running = null;
+  for (const event of events) {
+    if (event.type === "STEP_STARTED") {
+      const key = `${event.data.step}#${event.data.attempt}`;
+      open.set(key, { step: event.data.step, attempt: event.data.attempt, worker: event.data.worker, startedAt: event.ts });
+      running = open.get(key);
+    } else if (event.type === "STEP_FINISHED") {
+      const key = `${event.data.step}#${event.data.attempt}`;
+      const started = open.get(key);
+      const startedAt = started?.startedAt ?? null;
+      rows.push({
+        step: event.data.step,
+        attempt: event.data.attempt,
+        worker: started?.worker ?? null,
+        startedAt,
+        finishedAt: event.ts,
+        status: event.data.status,
+        durationMs: startedAt ? Date.parse(event.ts) - Date.parse(startedAt) : null,
+      });
+      open.delete(key);
+      if (running && running.step === event.data.step && running.attempt === event.data.attempt) {
+        running = null;
+      }
+    }
+  }
+  return { rows, running };
+}
+
+function median(values) {
+  if (values.length === 0) {
+    return null;
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+}
+
+// Typical (median) duration per step across every readable ledger in the
+// repository, optionally excluding the run being described. Crashed and
+// timed-out attempts are excluded: they measure the host, not the step.
+export function typicalDurations(repoRoot, { excludeRun = null } = {}) {
+  const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
+  const samples = {};
+  if (!existsSync(runsDir)) {
+    return {};
+  }
+  for (const entry of readdirSync(runsDir)) {
+    if (entry === excludeRun) {
+      continue;
+    }
+    const ledgerPath = join(runsDir, entry, "events.jsonl");
+    if (!existsSync(ledgerPath)) {
+      continue;
+    }
+    const ledger = EventLedger.open(ledgerPath);
+    for (const row of stepTimeline(ledger.events).rows) {
+      if (row.durationMs === null || row.status === "crashed" || row.status === "timeout") {
+        continue;
+      }
+      (samples[row.step] ??= []).push(row.durationMs);
+    }
+  }
+  const result = {};
+  for (const [step, values] of Object.entries(samples)) {
+    result[step] = { medianMs: median(values), samples: values.length };
+  }
+  return result;
+}
+
+// Reads the shell adapter's live marker and the mtime/size of its streams.
+export function readLive(repoRoot, runId) {
+  const dir = runDir(repoRoot, runId);
+  const markerPath = join(dir, LIVE_MARKER);
+  if (!existsSync(markerPath)) {
+    return null;
+  }
+  let marker;
+  try {
+    marker = JSON.parse(readFileSync(markerPath, "utf8"));
+  } catch {
+    return null;
+  }
+  let lastOutputAt = null;
+  let bytes = 0;
+  for (const path of [marker.stdout, marker.stderr]) {
+    if (!path || !existsSync(path)) {
+      continue;
+    }
+    const stat = statSync(path);
+    bytes += stat.size;
+    if (stat.size > 0 && (lastOutputAt === null || stat.mtimeMs > lastOutputAt)) {
+      lastOutputAt = stat.mtimeMs;
+    }
+  }
+  return { ...marker, lastOutputAt: lastOutputAt === null ? null : new Date(lastOutputAt).toISOString(), bytes };
+}
+
+export function tailLive(repoRoot, runId, lines = 5) {
+  const live = readLive(repoRoot, runId);
+  if (!live) {
+    return [];
+  }
+  const out = [];
+  for (const path of [live.stdout, live.stderr]) {
+    if (!path || !existsSync(path)) {
+      continue;
+    }
+    const text = readFileSync(path, "utf8");
+    out.push(...text.split("\n").filter((line) => line.trim().length > 0));
+  }
+  return out.slice(-lines);
+}
+
+export function describeLiveness({ repoRoot, runId, ledger, stallAfterMs = DEFAULT_STALL_AFTER_MS, now = Date.now }) {
+  const { rows, running } = stepTimeline(ledger.events);
+  const typical = typicalDurations(repoRoot, { excludeRun: runId });
+  const steps = {};
+  for (const row of rows) {
+    const entry = (steps[row.step] ??= { attempts: 0, totalMs: 0, lastMs: null, typicalMs: typical[row.step]?.medianMs ?? null, samples: typical[row.step]?.samples ?? 0 });
+    entry.attempts += 1;
+    if (row.durationMs !== null) {
+      entry.totalMs += row.durationMs;
+      entry.lastMs = row.durationMs;
+    }
+  }
+  let inFlight = null;
+  if (running && ledger.state.run?.status === "RUNNING") {
+    const nowMs = now();
+    const live = readLive(repoRoot, runId);
+    const elapsedMs = nowMs - Date.parse(running.startedAt);
+    const lastOutputMs = live?.lastOutputAt ? Date.parse(live.lastOutputAt) : null;
+    const sinceOutputMs = lastOutputMs === null ? elapsedMs : nowMs - lastOutputMs;
+    inFlight = {
+      step: running.step,
+      attempt: running.attempt,
+      worker: running.worker,
+      startedAt: running.startedAt,
+      elapsedMs,
+      command: live?.command ?? null,
+      lastOutputAt: live?.lastOutputAt ?? null,
+      sinceOutputMs,
+      bytes: live?.bytes ?? 0,
+      stalled: sinceOutputMs >= stallAfterMs,
+      stallAfterMs,
+      typicalMs: typical[running.step]?.medianMs ?? null,
+      samples: typical[running.step]?.samples ?? 0,
+    };
+    steps[running.step] ??= { attempts: 0, totalMs: 0, lastMs: null, typicalMs: inFlight.typicalMs, samples: inFlight.samples };
+  }
+  return { steps, inFlight };
+}
+
+export function formatMs(ms) {
+  if (ms === null || ms === undefined || Number.isNaN(ms)) {
+    return "?";
+  }
+  const total = Math.max(0, Math.round(ms / 1000));
+  if (total < 60) {
+    return `${total}s`;
+  }
+  const minutes = Math.floor(total / 60);
+  if (minutes < 60) {
+    return `${minutes}m`;
+  }
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  return rest === 0 ? `${hours}h` : `${hours}h${String(rest).padStart(2, "0")}m`;
+}

package/src/v2/runtime/metrics.js

@@ -6,6 +6,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 
 import { EventLedger } from "../storage/event-ledger.js";
+import { formatMs, typicalDurations } from "./liveness.js";
 
 export function computeMetrics(repoRoot) {
   const runsDir = join(repoRoot, ".buildbeat", "runtime", "runs");
@@ -105,6 +106,9 @@ export function computeMetrics(repoRoot) {
   summary.autoReachedHumanRate = measurable === 0 ? null : autoReached / measurable;
   summary.evidenceCompleteness =
     summary.finishedSteps === 0 ? null : evidencedSteps / summary.finishedSteps;
+  // Typical step duration (median over finished attempts, crashes and
+  // timeouts excluded): the number behind "is this taking too long".
+  summary.stepDurations = typicalDurations(repoRoot);
   return summary;
 }
 
@@ -136,5 +140,9 @@ export function renderMetrics(summary) {
     lines.push("approval waits: (none recorded)");
   }
   lines.push(`stale approvals: ${summary.staleApprovals}; budget stops: ${summary.budgetStops}`);
+  const durations = Object.entries(summary.stepDurations ?? {})
+    .map(([step, row]) => `${step}=${formatMs(row.medianMs)} (n=${row.samples})`)
+    .join(" ");
+  lines.push(`typical step duration (median): ${durations || "(no finished attempts)"}`);
   return lines.join("\n");
 }

package/src/v2/runtime/notify.js

@@ -0,0 +1,223 @@
+// Outbound notifications (iteration 08, C4): a Run that stops for a human
+// should reach that human where they are, not wait for them to open a
+// session and ask. Approval waits in the deploy campaign averaged 7–12 hours
+// because nothing said "there is something for you".
+//
+// Discipline: fail-open (a notification failure never touches a run), secrets
+// stay out of Git (the webhook URL comes from an env var named in the
+// config), payloads carry identifiers and the next reply — never candidate
+// content, never logs.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parseYamlSubset } from "../engine/yaml-subset.js";
+
+export const NOTIFY_CONFIG = join(".buildbeat", "notify.yaml");
+export const NOTIFY_EVENTS = ["HUMAN_REQUESTED", "RUN_TERMINAL", "STALLED"];
+const CHANNEL_TYPES = ["webhook", "dingtalk"];
+
+export class NotifyConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NotifyConfigError";
+  }
+}
+
+// Returns null when no config exists. Throws NotifyConfigError on a config
+// that exists but is malformed — callers decide whether that is fatal (it is
+// not for a run; it is for `doctor`).
+export function loadNotifyConfig(repoRoot) {
+  const path = join(repoRoot, NOTIFY_CONFIG);
+  if (!existsSync(path)) {
+    return null;
+  }
+  const doc = parseYamlSubset(readFileSync(path, "utf8"));
+  if (doc.kind !== "notify" || doc.version !== 1) {
+    throw new NotifyConfigError(`${NOTIFY_CONFIG}: expected kind: notify / version: 1`);
+  }
+  if (!Array.isArray(doc.channels) || doc.channels.length === 0) {
+    throw new NotifyConfigError(`${NOTIFY_CONFIG}: channels must be a non-empty list`);
+  }
+  const channels = doc.channels.map((channel, index) => {
+    const where = `${NOTIFY_CONFIG} channels[${index}]`;
+    if (typeof channel.id !== "string" || channel.id.length === 0) {
+      throw new NotifyConfigError(`${where}: id is required`);
+    }
+    if (!CHANNEL_TYPES.includes(channel.type)) {
+      throw new NotifyConfigError(`${where}: type must be one of ${CHANNEL_TYPES.join("|")}`);
+    }
+    if (typeof channel.urlEnv !== "string" || channel.urlEnv.length === 0) {
+      throw new NotifyConfigError(
+        `${where}: urlEnv is required (the webhook URL lives in that env var, never in Git)`,
+      );
+    }
+    if (channel.url !== undefined) {
+      throw new NotifyConfigError(`${where}: url is not allowed in Git; use urlEnv`);
+    }
+    const events = channel.events ?? NOTIFY_EVENTS;
+    if (!Array.isArray(events) || events.length === 0) {
+      throw new NotifyConfigError(`${where}: events must be a non-empty list`);
+    }
+    for (const event of events) {
+      if (!NOTIFY_EVENTS.includes(event)) {
+        throw new NotifyConfigError(`${where}: unknown event ${event} (allowed: ${NOTIFY_EVENTS.join("|")})`);
+      }
+    }
+    return { id: channel.id, type: channel.type, urlEnv: channel.urlEnv, events, keyword: channel.keyword ?? "BuildBeat" };
+  });
+  return { channels };
+}
+
+export function subscribes(config, event) {
+  return Boolean(config?.channels.some((channel) => channel.events.includes(event)));
+}
+
+// The exact commands a human can copy to answer a pending request. Shared by
+// status, inbox and notifications so "what do I say now" has one answer.
+export function nextReply({ repoLabel, state }) {
+  const pending = state.pendingHuman;
+  if (!pending || !state.run) {
+    return [];
+  }
+  const runId = state.run.id;
+  const lines = [];
+  if (pending.kind === "finding-triage") {
+    lines.push(`buildbeat-v2 findings list --repo ${repoLabel} --work ${state.run.work}`);
+    lines.push(
+      `buildbeat-v2 findings adjudicate --repo ${repoLabel} --work ${state.run.work} --fingerprint <fp> --action accept|dismiss --by <you>`,
+    );
+  }
+  lines.push(
+    `buildbeat-v2 approve --repo ${repoLabel} --run ${runId} --transition ${pending.transition} --by <you>` +
+      (pending.kind === "final-decision" ? "   # merge-ready; merge/push stay yours" : "   # then: resume --config <run-config.yaml>"),
+  );
+  lines.push(`buildbeat-v2 reject --repo ${repoLabel} --run ${runId} --reason <why> --by <you>`);
+  return lines;
+}
+
+export function buildNotification(kind, { repoLabel, state, detail = {} }) {
+  const run = state.run;
+  const base = {
+    kind,
+    run: run?.id ?? null,
+    work: run?.work ?? null,
+    status: run?.status ?? null,
+    repo: repoLabel,
+    at: new Date().toISOString(),
+  };
+  if (kind === "HUMAN_REQUESTED") {
+    const pending = state.pendingHuman;
+    return {
+      ...base,
+      title: `[BuildBeat] ${run.id} 等你拍板：${pending?.transition ?? "?"}`,
+      reasons: pending?.reasons ?? [],
+      candidate: pending?.subject?.candidate ?? null,
+      nextReply: nextReply({ repoLabel, state }),
+    };
+  }
+  if (kind === "RUN_TERMINAL") {
+    return {
+      ...base,
+      title: `[BuildBeat] ${run.id} 结束：${state.terminal?.status ?? run.status}`,
+      reasons: state.terminal?.reason ? [state.terminal.reason] : [],
+      candidate: state.workspaces?.[run.id]?.candidate ?? null,
+      nextReply: [],
+    };
+  }
+  if (kind === "STALLED") {
+    return {
+      ...base,
+      title: `[BuildBeat] ${run.id} 疑似卡住：${detail.step ?? "?"} 已 ${detail.sinceOutput ?? "?"} 无输出`,
+      reasons: [
+        `step ${detail.step ?? "?"} attempt ${detail.attempt ?? "?"} started ${detail.startedAt ?? "?"}, elapsed ${detail.elapsed ?? "?"}`,
+        detail.command ? `worker: ${detail.command}` : "worker: (unknown)",
+        `threshold ${detail.threshold ?? "?"}; the process is NOT killed — check status, then decide`,
+      ],
+      candidate: null,
+      nextReply: [`buildbeat-v2 status --repo ${repoLabel} --run ${run.id}`],
+    };
+  }
+  throw new NotifyConfigError(`unknown notification kind: ${kind}`);
+}
+
+function renderText(notification) {
+  const lines = [notification.title, `work: ${notification.work}  status: ${notification.status}`];
+  for (const reason of notification.reasons ?? []) {
+    lines.push(`- ${reason}`);
+  }
+  if (notification.candidate) {
+    lines.push(`candidate: ${notification.candidate}`);
+  }
+  if (notification.nextReply?.length) {
+    lines.push("next:");
+    for (const line of notification.nextReply) {
+      lines.push(`  ${line}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function payloadFor(channel, notification) {
+  if (channel.type === "dingtalk") {
+    // DingTalk custom robots require a configured keyword in the text; the
+    // title carries it (default "BuildBeat").
+    const text = renderText(notification);
+    return {
+      msgtype: "text",
+      text: { content: text.includes(channel.keyword) ? text : `${channel.keyword}\n${text}` },
+    };
+  }
+  return { ...notification, text: renderText(notification) };
+}
+
+function logLine(repoRoot, runId, line) {
+  if (!runId) {
+    return;
+  }
+  try {
+    const dir = join(repoRoot, ".buildbeat", "runtime", "runs", runId);
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "notify.log"), `${new Date().toISOString()} ${line}\n`, "utf8");
+  } catch {
+    // logging a notification must never fail the caller
+  }
+}
+
+// Sends to every channel subscribed to the notification kind. Never throws;
+// each channel reports ok/skipped/failed. A missing URL env var is a skip
+// with a visible reason, not silence.
+export async function dispatchNotification(config, notification, { repoRoot, fetchImpl = globalThis.fetch, timeoutMs = 8000, env = process.env } = {}) {
+  const results = [];
+  for (const channel of config?.channels ?? []) {
+    if (!channel.events.includes(notification.kind)) {
+      continue;
+    }
+    const url = env[channel.urlEnv];
+    if (!url) {
+      results.push({ channel: channel.id, ok: false, skipped: true, error: `env ${channel.urlEnv} not set` });
+      logLine(repoRoot, notification.run, `${notification.kind} ${channel.id} SKIPPED env ${channel.urlEnv} not set`);
+      continue;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await fetchImpl(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payloadFor(channel, notification)),
+        signal: controller.signal,
+      });
+      const ok = response.ok;
+      results.push({ channel: channel.id, ok, status: response.status, error: ok ? null : `HTTP ${response.status}` });
+      logLine(repoRoot, notification.run, `${notification.kind} ${channel.id} ${ok ? "SENT" : "FAILED"} HTTP ${response.status}`);
+    } catch (error) {
+      const message = error?.name === "AbortError" ? `timeout after ${timeoutMs}ms` : error?.message ?? String(error);
+      results.push({ channel: channel.id, ok: false, error: message });
+      logLine(repoRoot, notification.run, `${notification.kind} ${channel.id} FAILED ${message}`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  return results;
+}