@mutagent/helix 0.1.0-alpha.14

package/mutagent-orchestrator/scripts/dogfood/resolve-subagents.ts

@@ -0,0 +1,160 @@
+// ---------------------------------------------------------------------------
+// dogfood/resolve-subagents — DOG-2: resolve the dispatched-subagent session
+// JSONLs for a main Helix session, so `reconstruct-trajectory` (which already
+// accepts `subagentPaths`) can ingest them (today it saw `subagents=0`).
+//
+// LINKAGE (see the DOG-2 ADR in monitoring-system-design.md). Verified against
+// the local Claude-projects store: this Claude Code build persists NO
+// `isSidechain:true` lines and NO `Task` tool_use in the parent transcript, so
+// there is no in-file parent→child pointer to follow TODAY. We therefore resolve
+// by a precedence chain, favouring what the dogfood target actually produces:
+//
+//   (1) per-session convention dir  <source_dir>/subagents/<sessionId>/*.jsonl
+//   (2) flat convention dir         <source_dir>/subagents/*.jsonl
+//   (3) sidechain siblings          <source_dir>/*.jsonl (≠ main) whose entries
+//                                   carry `isSidechain:true` AND a `parentUuid`
+//                                   that roots in the MAIN session's uuids
+//                                   (forward-compatible for a Claude Code build
+//                                   that DOES colocate sidechain files).
+//
+// (3) is best-effort + precise: a sibling is linked ONLY when a parentUuid
+// actually matches a main-session uuid — never by mere co-location (no
+// cross-session bleed). The whole resolver is gated by `include_subagents`
+// (default true). PURITY: `selectSidechainSiblings` is pure; the file wrapper
+// `resolveSubagentPaths` does the ONLY I/O (dir listing + a raw uuid scan).
+// ---------------------------------------------------------------------------
+
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/** Raw linkage facts scanned from ONE session JSONL (cheap, adapter-free). */
+export interface SessionLinkage {
+  /** Absolute path of the scanned file. */
+  path: string;
+  /** Every `parentUuid` seen across the file's entries (non-null). */
+  parentUuids: string[];
+  /** True if ANY entry carried `isSidechain:true`. */
+  isSidechain: boolean;
+}
+
+/**
+ * PURE core: from the MAIN session's uuid set + pre-scanned sibling linkages,
+ * select the sibling paths that are dispatched subagents of THIS session — a
+ * sidechain file with a `parentUuid` rooting in `mainUuids`. Deterministic
+ * (sorted, de-duplicated). Never links by co-location alone.
+ */
+export function selectSidechainSiblings(args: {
+  mainUuids: Set<string>;
+  siblings: SessionLinkage[];
+}): string[] {
+  const linked = new Set<string>();
+  for (const sib of args.siblings) {
+    if (!sib.isSidechain) continue;
+    if (sib.parentUuids.some((p) => args.mainUuids.has(p))) linked.add(sib.path);
+  }
+  return [...linked].sort();
+}
+
+/** List `*.jsonl` files (basenames) in a dir; missing/unreadable dir ⇒ []. */
+function listJsonl(dir: string): string[] {
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith(".jsonl"))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Scan one JSONL file for its linkage facts (uuids we ignore here; parents + sidechain). */
+function scanLinkage(path: string): SessionLinkage {
+  const out: SessionLinkage = { path, parentUuids: [], isSidechain: false };
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return out;
+  }
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    let ev: { parentUuid?: string | null; isSidechain?: boolean };
+    try {
+      ev = JSON.parse(trimmed) as typeof ev;
+    } catch {
+      continue;
+    }
+    if (typeof ev.parentUuid === "string" && ev.parentUuid.length > 0) out.parentUuids.push(ev.parentUuid);
+    if (ev.isSidechain === true) out.isSidechain = true;
+  }
+  return out;
+}
+
+/** Collect the set of `uuid`s emitted by one JSONL file (for sidechain rooting). */
+function collectUuids(path: string): Set<string> {
+  const uuids = new Set<string>();
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return uuids;
+  }
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const ev = JSON.parse(trimmed) as { uuid?: string };
+      if (typeof ev.uuid === "string" && ev.uuid.length > 0) uuids.add(ev.uuid);
+    } catch {
+      /* tolerant — skip unparseable lines */
+    }
+  }
+  return uuids;
+}
+
+/** Inputs for the file-wrapper resolver. */
+export interface ResolveSubagentsInput {
+  /** The dogfood target's Claude-projects session dir. */
+  sourceDir: string;
+  /** The main session id (the `<sessionId>.jsonl` in `sourceDir`). */
+  sessionId: string;
+  /** config.dogfood.include_subagents (default true). */
+  includeSubagents?: boolean;
+}
+
+/**
+ * Resolve the dispatched-subagent JSONL paths for a main session by the
+ * precedence chain above. Best-effort + honest: returns [] (never throws) when
+ * disabled or when nothing links. The ONLY I/O in this module.
+ */
+export function resolveSubagentPaths(input: ResolveSubagentsInput): string[] {
+  if (input.includeSubagents === false) return [];
+  const { sourceDir, sessionId } = input;
+  const found: string[] = [];
+
+  // (1) per-session convention dir
+  const perSessionDir = join(sourceDir, "subagents", sessionId);
+  const perSession = listJsonl(perSessionDir).map((f) => join(perSessionDir, f));
+  found.push(...perSession);
+
+  // (2) flat convention dir (only when the per-session dir yielded nothing)
+  if (perSession.length === 0) {
+    const flatDir = join(sourceDir, "subagents");
+    found.push(...listJsonl(flatDir).map((f) => join(flatDir, f)));
+  }
+
+  // (3) sidechain siblings in the source dir (forward-compatible best-effort)
+  const mainFile = join(sourceDir, `${sessionId}.jsonl`);
+  const siblingNames = listJsonl(sourceDir).filter((f) => f !== `${sessionId}.jsonl`);
+  if (siblingNames.length > 0) {
+    const siblings = siblingNames.map((f) => scanLinkage(join(sourceDir, f)));
+    // only pay for the main uuid scan if a sibling actually looks like a sidechain
+    if (siblings.some((s) => s.isSidechain)) {
+      const mainUuids = collectUuids(mainFile);
+      found.push(...selectSidechainSiblings({ mainUuids, siblings }));
+    }
+  }
+
+  // de-dupe (a path can never satisfy two branches, but stay defensive) + stable order
+  return [...new Set(found)].sort();
+}

package/mutagent-orchestrator/scripts/dogfood/run-report.ts

@@ -0,0 +1,264 @@
+#!/usr/bin/env bun
+/**
+ * scripts/dogfood/run-report.ts — the *dogfood report runner.
+ *
+ * Composes the pure dogfood functions (parse → reconstruct → extract → render) into a written
+ * HTML "Live Status" report. The `dogfood-monitor` agent shells out to this; `*dogfood` is ALWAYS
+ * a live monitor (DOG-0): the watch loop is the DEFAULT (re-render on the session file changing OR
+ * every `--interval` seconds — default 180 = 3 min, matching the monitor cadence). Pass `--once`
+ * for a single render + exit (internal/test only, NOT the operator path).
+ *
+ * When `config.dogfood.slack.enabled` (DOG-3), each render also drives a LIVE Slack THREAD: a root
+ * message on start + typed threaded replies derived by diffing successive trajectories. Slack is a
+ * strictly-optional sink — unconfigured/disabled ⇒ HTML report only, never an error.
+ *
+ * Usage:
+ *   run-report.ts --session <id> --source-dir <dir> [--out <path>]
+ *                 [--refresh <sec=180>] [--include-subagents] [--interval <sec=180>] [--once]
+ */
+import { reconstructTrajectory, parseSessionFile } from "./reconstruct-trajectory.ts";
+import { extractFeedback } from "./extract-feedback.ts";
+import { renderDogfoodReport } from "./render-dogfood-report.ts";
+import { resolveSubagentPaths } from "./resolve-subagents.ts";
+import { dogfoodThreadMessages } from "./slack-thread.ts";
+import type { DogfoodEvent, DogfoodThreadMeta } from "./slack-thread.ts";
+import type { FeedbackItem, Trajectory } from "./types.ts";
+import { postMessage, postReply } from "../slack/post.ts";
+import { writeFileSync, mkdirSync, statSync, watch } from "node:fs";
+import { join, dirname } from "node:path";
+import { setInterval } from "node:timers";
+
+/** Options for a single report build. I/O reads happen here; `now` is INJECTED (testable). */
+export interface BuildReportOpts {
+  /** The main session JSONL path (explicit — the CLI derives it from session+source-dir). */
+  mainPath: string;
+  sessionId: string;
+  sourceDir?: string;
+  /** Dispatched subagent session JSONL paths (empty ⇒ none). */
+  subagentPaths?: string[];
+  /** Injected wall-clock (epoch ms) — the report's "as of" time. */
+  now: number;
+  /** Browser auto-reload cadence in seconds (0/undefined ⇒ static, no auto-reload). */
+  refreshSeconds?: number;
+  title?: string;
+}
+
+export interface BuildReportResult {
+  html: string;
+  stats: { commands: number; feedback: number; subagents: number };
+  /** The reconstructed trajectory (exposed so the watch loop can diff for DOG-3). */
+  trajectory: Trajectory;
+  /** The extracted feedback items (exposed for the same diff). */
+  feedback: FeedbackItem[];
+}
+
+/** Compose the pure pipeline into an HTML string + counts + structured outputs. Reads the session file(s). */
+export async function buildReport(opts: BuildReportOpts): Promise<BuildReportResult> {
+  const main = await parseSessionFile(opts.mainPath);
+  if (main === null) {
+    throw new Error(`run-report: no recognizable events in ${opts.mainPath}`);
+  }
+  const subagentPaths = opts.subagentPaths ?? [];
+  const trajectory = await reconstructTrajectory({ mainPath: opts.mainPath, subagentPaths, now: opts.now });
+  const feedback = extractFeedback(main);
+  const html = renderDogfoodReport({
+    trajectory,
+    feedback,
+    meta: {
+      runId: `dogfood-${opts.now}`,
+      sessionId: opts.sessionId,
+      sourceDir: opts.sourceDir,
+      generatedAt: new Date(opts.now).toISOString(),
+      title: opts.title ?? "Helix Dogfood — Live Status",
+      subagentCount: subagentPaths.length,
+      refreshSeconds: opts.refreshSeconds && opts.refreshSeconds > 0 ? opts.refreshSeconds : undefined,
+    },
+  });
+  return {
+    html,
+    stats: { commands: trajectory.commands.length, feedback: feedback.length, subagents: subagentPaths.length },
+    trajectory,
+    feedback,
+  };
+}
+
+// ── DOG-0: watch decision (pure, unit-testable — no loop spawned) ─────────────
+
+/**
+ * `*dogfood` is ALWAYS a live monitor. Watch is the DEFAULT; the ONLY opt-out is
+ * an explicit `--once` (a single render + exit — internal/test use only, never
+ * the operator path). Pure over argv so it is testable WITHOUT arming the loop.
+ */
+export function shouldWatch(argv: string[]): boolean {
+  return !argv.includes("--once");
+}
+
+// ── DOG-3: successive-trajectory diff → live-thread events (pure) ─────────────
+
+/** A render snapshot the watch loop diffs between ticks. */
+export interface DogfoodSnapshot {
+  trajectory: Trajectory;
+  feedback: FeedbackItem[];
+}
+
+/** Stable identity for a feedback item (order-independent diffing). */
+function feedbackKey(f: FeedbackItem): string {
+  return `${f.kind}:${f.evidencePointer.spanId}:${f.evidencePointer.turnIndex}`;
+}
+
+/**
+ * Derive the NEW live-thread events between two render snapshots. PURE +
+ * deterministic. Emits: stage-change (new timeline segment with a stage flip),
+ * agent-dispatch (a subagent unseen in `prev`), feedback (a new `feedback-block`),
+ * and signal (a new implicit signal). `prev` undefined ⇒ the first render (no
+ * replies — the ROOT is posted separately from meta).
+ */
+export function diffDogfoodEvents(prev: DogfoodSnapshot | undefined, next: DogfoodSnapshot): DogfoodEvent[] {
+  if (prev === undefined) return [];
+  const events: DogfoodEvent[] = [];
+
+  // stage-change — new timeline segments (append-only) with an actual stage flip
+  const tl = next.trajectory.timeline;
+  for (let i = prev.trajectory.timeline.length; i < tl.length; i++) {
+    const to = tl[i].stage;
+    const from = i > 0 ? tl[i - 1].stage : undefined;
+    if (from !== to) events.push(from ? { type: "stage-change", to, from } : { type: "stage-change", to });
+  }
+
+  // agent-dispatch — subagents unseen in prev (by sessionId)
+  const prevSubs = new Set(prev.trajectory.subagents.map((s) => s.sessionId));
+  for (const s of next.trajectory.subagents) {
+    if (!prevSubs.has(s.sessionId)) events.push({ type: "agent-dispatch", agent: s.agentName });
+  }
+
+  // feedback / signal — items whose identity is new
+  const prevKeys = new Set(prev.feedback.map(feedbackKey));
+  for (const f of next.feedback) {
+    if (prevKeys.has(feedbackKey(f))) continue;
+    if (f.kind === "feedback-block") events.push({ type: "feedback", text: f.observation, severity: f.severity });
+    else events.push({ type: "signal", kind: f.kind, count: 1 });
+  }
+
+  return events;
+}
+
+// ── CLI (impure boundary: argv · clock · fs · watch · Slack post) ─────────────
+function arg(name: string, def?: string): string | undefined {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? process.argv[i + 1] : def;
+}
+function flag(name: string): boolean {
+  return process.argv.includes(`--${name}`);
+}
+
+/** The resolved dogfood Slack sink (config-gated). null ⇒ no Slack this run. */
+interface SlackSink {
+  channel: string;
+  token: string;
+  cadenceLabel: string;
+}
+
+/**
+ * Resolve the Slack sink from `config.dogfood.slack` (DOG-3). Active ONLY when
+ * enabled AND the `token_ref` env var is set. Guarded (never throws): any miss ⇒
+ * null ⇒ HTML report only. The config module is imported LAZILY so the render
+ * path never hard-depends on it (a consumer install without deps still renders;
+ * Slack simply no-ops).
+ */
+async function resolveSlackSink(): Promise<SlackSink | null> {
+  try {
+    const { loadConfig } = await import("../config-schema.ts");
+    const { resolveConfigPath } = await import("../resolve-paths.ts");
+    const res = loadConfig(resolveConfigPath());
+    if (!res.ok) return null;
+    const slack = res.config.dogfood?.slack;
+    if (slack === undefined || slack.enabled !== true) return null;
+    const token = process.env[slack.token_ref];
+    if (token === undefined || token.length === 0) return null;
+    const cadence = res.config.dogfood?.cadence_seconds ?? 180;
+    return { channel: slack.channel, token, cadenceLabel: `${Math.max(1, Math.round(cadence / 60))}m` };
+  } catch {
+    return null;
+  }
+}
+
+async function main(): Promise<void> {
+  const sessionId = arg("session");
+  const sourceDir = arg("source-dir");
+  if (sessionId === undefined || sourceDir === undefined) {
+    console.error("run-report: --session <id> and --source-dir <dir> are required");
+    process.exit(2);
+  }
+  const mainPath = join(sourceDir, `${sessionId}.jsonl`);
+  const outPath = arg("out", join(process.cwd(), ".mutagent", "dogfood", `${sessionId}.html`))!;
+  const refreshSeconds = Number(arg("refresh", "180"));
+  const intervalMs = Number(arg("interval", "180")) * 1000;
+
+  // DOG-2: resolve dispatched subagent JSONLs by parent→child linkage (gated by
+  // --include-subagents, which the monitor passes when config.include_subagents).
+  const resolveSubs = (): string[] =>
+    flag("include-subagents") ? resolveSubagentPaths({ sourceDir, sessionId, includeSubagents: true }) : [];
+
+  // DOG-3: Slack live-thread state (config-gated; null ⇒ no Slack).
+  const slack = await resolveSlackSink();
+  let threadTs: string | null = null;
+  let prevSnap: DogfoodSnapshot | undefined;
+
+  const postThread = async (result: BuildReportResult): Promise<void> => {
+    if (slack === null) return;
+    const nextSnap: DogfoodSnapshot = { trajectory: result.trajectory, feedback: result.feedback };
+    if (threadTs === null) {
+      // First render: open the thread with the ROOT (from meta); baseline the diff.
+      const meta: DogfoodThreadMeta = { sessionId, project: sourceDir, cadenceLabel: slack.cadenceLabel };
+      const root = dogfoodThreadMessages([], meta)[0];
+      const res = await postMessage({ channel: slack.channel, text: root.text, token: slack.token });
+      threadTs = res?.ts ?? null;
+    } else {
+      // Subsequent renders: post one threaded reply per NEW event.
+      const events = diffDogfoodEvents(prevSnap, nextSnap);
+      for (const msg of dogfoodThreadMessages(events, { sessionId }).filter((m) => m.kind === "reply")) {
+        await postReply({ channel: slack.channel, thread_ts: threadTs, text: msg.text, token: slack.token });
+      }
+    }
+    prevSnap = nextSnap;
+  };
+
+  const renderOnce = async (reason: string): Promise<void> => {
+    try {
+      const result = await buildReport({
+        mainPath, sessionId, sourceDir, subagentPaths: resolveSubs(), now: Date.now(), refreshSeconds,
+      });
+      mkdirSync(dirname(outPath), { recursive: true });
+      writeFileSync(outPath, result.html);
+      const { commands, feedback, subagents } = result.stats;
+      console.info(`[dogfood] rendered (${reason}) → ${outPath} · commands=${commands} feedback=${feedback} subagents=${subagents}`);
+      await postThread(result);
+    } catch (e) {
+      console.error(`[dogfood] render error (${reason}): ${(e as Error).message}`);
+    }
+  };
+
+  await renderOnce("initial");
+
+  // DOG-0: *dogfood is ALWAYS live — watch is the default; --once opts out.
+  if (shouldWatch(process.argv)) {
+    console.info(`[dogfood] watch ARMED — re-render on drift OR every ${intervalMs / 1000}s`);
+    setInterval(() => void renderOnce("heartbeat"), intervalMs);
+    let lastMtime = 0;
+    try {
+      watch(mainPath, { persistent: true }, () => {
+        const m = statSync(mainPath).mtimeMs;
+        if (m !== lastMtime) {
+          lastMtime = m;
+          void renderOnce("drift");
+        }
+      });
+    } catch (e) {
+      console.error(`[dogfood] cannot watch ${mainPath} for drift: ${(e as Error).message}`);
+    }
+  }
+}
+
+if (import.meta.main) {
+  await main();
+}

package/mutagent-orchestrator/scripts/dogfood/slack-thread.ts

@@ -0,0 +1,106 @@
+// ---------------------------------------------------------------------------
+// dogfood/slack-thread — the DOGFOOD-ONLY Slack emitter (DOG-3): a LIVE THREAD.
+//
+// One dogfood session ⇒ one Slack thread: a ROOT message on start + typed
+// THREADED replies as the session moves (stage-change · agent-dispatch ·
+// feedback · signal · progress-heartbeat · stop). Human-readable + precise —
+// coworkers follow the pulse in Slack while the HTML report stays the deep view.
+//
+// PURE: `dogfoodThreadMessages(events, meta) → SlackMsg[]` is `input → messages`,
+// no I/O/clock/random. The run-report watch loop diffs successive trajectories
+// into `DogfoodEvent[]`, calls this, and posts via `slack/post` (the only impure
+// seam). SEPARATION (load-bearing): this emitter imports ONLY `../slack/*` — it
+// is the dogfood VOICE and never imports the External Monitor's (`../monitor/*`).
+// ---------------------------------------------------------------------------
+
+import { bold, code, italic } from "../slack/format.ts";
+import type { SlackMsg } from "../slack/post.ts";
+
+/**
+ * A dogfood live-thread event (derived by the watch loop from successive
+ * trajectory diffs). The union is closed so the emitter is exhaustive.
+ */
+export type DogfoodEvent =
+  | { type: "stage-change"; to: string; from?: string }
+  | { type: "agent-dispatch"; agent: string; stage?: string; role?: string }
+  | { type: "feedback"; text: string; severity?: string }
+  | { type: "signal"; kind: string; count?: number }
+  | { type: "progress"; minutes: number; commands: number; feedback: number; subagents: number }
+  | { type: "stop"; commands: number; feedback: number };
+
+/** Metadata for the thread ROOT (posted once on start). */
+export interface DogfoodThreadMeta {
+  sessionId: string;
+  /** Human project label (the dogfood target), optional. */
+  project?: string;
+  /** Cadence label for the root ("3m" etc.); default "3m". */
+  cadenceLabel?: string;
+}
+
+/** ADL-stage → a compact display label with its circled numeral (self-contained). */
+const STAGE_DISPLAY: Readonly<Record<string, string>> = {
+  spec: "① SPEC",
+  build: "② BUILD",
+  discover: "◇ DISCOVER",
+  evaluate: "③ EVALUATE",
+  diagnose: "④ DIAGNOSE",
+  improve: "⑤ IMPROVE",
+  meta: "· META",
+};
+
+/** Display a stage token; unknown tokens fall back to their upper-case form. */
+function stageLabel(stage: string): string {
+  return STAGE_DISPLAY[stage] ?? stage.toUpperCase();
+}
+
+/** Short session id for the root header (first 8 chars + ellipsis when longer). */
+function shortId(id: string): string {
+  return id.length > 8 ? `${id.slice(0, 8)}…` : id;
+}
+
+/** Render the thread ROOT message from the session meta. */
+function rootText(meta: DogfoodThreadMeta): string {
+  const project = meta.project ? ` · project ${bold(meta.project)}` : "";
+  const cadence = meta.cadenceLabel ?? "3m";
+  return `🧬 ${bold("Dogfood live")} — session ${code(shortId(meta.sessionId))}${project} · watching (${cadence} + on-drift)`;
+}
+
+/** Render ONE event to its threaded-reply text. */
+function eventText(ev: DogfoodEvent): string {
+  switch (ev.type) {
+    case "stage-change": {
+      const from = ev.from ? ` (from ${stageLabel(ev.from)})` : "";
+      return `⏩ Stage → ${bold(stageLabel(ev.to))}${from}`;
+    }
+    case "agent-dispatch": {
+      const parts: string[] = [];
+      if (ev.stage) parts.push(stageLabel(ev.stage));
+      if (ev.role) parts.push(ev.role);
+      const suffix = parts.length > 0 ? ` (${parts.join(" · ")})` : "";
+      return `🤖 dispatched ${code(ev.agent)}${suffix}`;
+    }
+    case "feedback":
+      return `💬 feedback — ${italic(`"${ev.text}"`)}`;
+    case "signal": {
+      const count = ev.count !== undefined ? ` ×${ev.count}` : "";
+      return `⚠️ signal — ${ev.kind}${count}`;
+    }
+    case "progress":
+      return `📊 ${ev.minutes}m · ${ev.commands} commands · ${ev.feedback} feedback · ${ev.subagents} subagents`;
+    case "stop":
+      return `🏁 watch ended · ${ev.commands} commands · ${ev.feedback} feedback · report attached`;
+  }
+}
+
+/**
+ * Build the full thread message list for a session: the ROOT (from meta) followed
+ * by one threaded REPLY per event, in order. PURE + deterministic — identical
+ * (events, meta) ⇒ identical `SlackMsg[]`.
+ */
+export function dogfoodThreadMessages(events: DogfoodEvent[], meta: DogfoodThreadMeta): SlackMsg[] {
+  const msgs: SlackMsg[] = [{ kind: "root", text: rootText(meta) }];
+  for (const ev of events) {
+    msgs.push({ kind: "reply", text: eventText(ev) });
+  }
+  return msgs;
+}