@mutagent/helix 0.1.0-alpha.14

package/mutagent-orchestrator/scripts/index/build-index.ts

@@ -0,0 +1,351 @@
+/**
+ * scripts/index/build-index.ts
+ * F4 — the `.mutagent/index.md` spec ↔ implementation REGISTRY writer (build core).
+ * Type A — Pure core (data → model) + a thin INJECTED-I/O regenerate wrapper.
+ *
+ * WHAT this is: one deterministic writer that regenerates a single `.mutagent/index.md`
+ * linking each registered AgentSpec to everything that realizes it — HIGH-LEVEL ONLY:
+ * spec identity · stage · verdict · build target + LINKS to implementation code and
+ * context docs, stamped with `spec_version` + an injected `updated` date.
+ *
+ * ANTI-DRIFT (LOAD-BEARING): the index carries identity + stage/verdict + version/date +
+ * LINKS ONLY. It NEVER restates eval criteria / scenarios / dataset detail — that lives in
+ * the evaluator's living-suite; duplicating it here is a drift + maintenance burden. The
+ * index only points; it never copies.
+ *
+ * DETERMINISM (mirrors mutagent-diagnostics `store.ts` regenerateIndex):
+ *   - entries sorted by spec_id · code/context links sorted by path · deduped
+ *   - the ONLY non-determinism (the `updated` date) is INJECTED by the caller (nowIso)
+ *   - pure `buildIndexModel` (no I/O, no clock) + pure `renderIndex` (render-index.ts)
+ *   - `regenerateIndex` takes an INJECTED IndexIo seam → byte-stable tests with no disk
+ *
+ * The rendered markdown IS the machine surface — no sidecar JSON. See render-index.ts for
+ * the exact layout and references/index-registry.md for the update-point convention.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+
+import {
+  MUTAGENT_DIR,
+  STAGE_DIRS,
+  mutagentDir,
+  stageDir,
+  resolveConfigRoot,
+} from "../resolve-paths.ts";
+import { renderIndex } from "./render-index.ts";
+
+// ── Model ────────────────────────────────────────────────────────────────────
+
+/** A link to an implementation file that realizes an agent (from a target `code_refs[]`). */
+export interface IndexCodeLink {
+  /** Project-root-relative path (config determinism: never absolute). */
+  path: string;
+  /** WHY this file matters (verbatim from the config `code_refs[].why`). */
+  why: string;
+}
+
+/** A link to a context / product doc (from `global.context[]`). */
+export interface IndexContextLink {
+  /** Project-root-relative path. */
+  path: string;
+  what: string;
+  why: string;
+  when: string;
+}
+
+/** One agent's HIGH-LEVEL registry entry. Links only — no eval detail. */
+export interface IndexEntry {
+  /** Display name — `definition.identity.name`, falling back to the spec_id. */
+  name: string;
+  /** The stable identity anchor `meta.spec_id` (also the sort key). */
+  specId: string;
+  /** `meta.spec_version`. */
+  specVersion: string;
+  /** `meta.loop_state.stage` — where in the ADL loop the spec sits. */
+  stage: string;
+  /** `meta.loop_state.last_verdict`, or null when the agent has no verdict yet. */
+  lastVerdict: string | null;
+  /** `.mutagent/`-relative link to the spec file: `specs/<id>/agentspec.yaml`. */
+  specPath: string;
+  /** `build.{target_framework, runtime}`, or null when the spec has no build block. */
+  build: { targetFramework: string; runtime: string } | null;
+  /** Implementation links (config `global.targets[].code_refs`), sorted + deduped by path. */
+  codeRefs: IndexCodeLink[];
+  /** Context / product doc links (`global.context[]`), sorted by path. */
+  contextLinks: IndexContextLink[];
+}
+
+/** The whole index — an injected `updated` date + spec_id-sorted entries. */
+export interface IndexModel {
+  /** Injected `updated` date, formatted YYYY-MM-DD. */
+  updated: string;
+  entries: IndexEntry[];
+}
+
+/** A parsed spec keyed by its on-disk directory id (the spec_id dir under `.mutagent/specs`). */
+export interface LoadedSpec {
+  /** The on-disk directory name (canonically the spec_id). Drives the spec link path. */
+  id: string;
+  /** The parsed agentspec.yaml (unknown — defensively narrowed here). */
+  spec: unknown;
+}
+
+export interface BuildIndexInput {
+  specs: LoadedSpec[];
+  /** The parsed `.mutagent/config.yaml` (unknown — the code_refs + context source). */
+  config: unknown;
+  /** INJECTED ISO8601 timestamp — the `updated` stamp is `nowIso.slice(0,10)`. */
+  nowIso: string;
+}
+
+// ── Defensive narrowing helpers (no cross-package schema import — standalone rule) ──
+
+function asRecord(v: unknown): Record<string, unknown> | null {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+    ? (v as Record<string, unknown>)
+    : null;
+}
+
+function asString(v: unknown): string | null {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+function asArray(v: unknown): unknown[] {
+  return Array.isArray(v) ? v : [];
+}
+
+// ── Config extraction (code_refs + context — the realized-impl + doc links) ─────
+
+/**
+ * Pull every target's `code_refs` from `global.targets[]`, flatten, dedupe by path
+ * (first `why` wins), and sort by path. These are the realized implementation links
+ * shared across the install (per PR-013 the spec never enumerates its own impls, so the
+ * config's targets are the impl-link source of truth).
+ */
+export function extractCodeRefs(config: unknown): IndexCodeLink[] {
+  const global = asRecord(asRecord(config)?.global);
+  const targets = asArray(global?.targets);
+  const byPath = new Map<string, IndexCodeLink>();
+  for (const t of targets) {
+    const refs = asArray(asRecord(t)?.code_refs);
+    for (const r of refs) {
+      const rec = asRecord(r);
+      const p = asString(rec?.path);
+      if (!p) continue;
+      if (!byPath.has(p)) {
+        byPath.set(p, { path: p, why: asString(rec?.why) ?? "" });
+      }
+    }
+  }
+  return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+/** Pull `global.context[]` context links, sorted by path. */
+export function extractContextLinks(config: unknown): IndexContextLink[] {
+  const global = asRecord(asRecord(config)?.global);
+  const context = asArray(global?.context);
+  const links: IndexContextLink[] = [];
+  for (const c of context) {
+    const rec = asRecord(c);
+    const p = asString(rec?.path);
+    if (!p) continue;
+    links.push({
+      path: p,
+      what: asString(rec?.what) ?? "",
+      why: asString(rec?.why) ?? "",
+      when: asString(rec?.when) ?? "",
+    });
+  }
+  return links.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// ── Spec extraction ────────────────────────────────────────────────────────────
+
+/**
+ * Narrow one parsed agentspec into an IndexEntry. Reads HIGH-LEVEL fields only —
+ * meta identity + loop_state + build — plus the shared config-sourced code/context links.
+ * Tolerant of missing fields (fall back to the dir id / sensible placeholders) so a
+ * partially-written spec still lands a row rather than crashing the whole regen.
+ */
+export function buildEntry(
+  loaded: LoadedSpec,
+  codeRefs: IndexCodeLink[],
+  contextLinks: IndexContextLink[],
+): IndexEntry {
+  const spec = asRecord(loaded.spec);
+  const meta = asRecord(spec?.meta);
+  const loopState = asRecord(meta?.loop_state);
+  const definition = asRecord(spec?.definition);
+  const identity = asRecord(definition?.identity);
+  const build = asRecord(spec?.build);
+
+  const specId = asString(meta?.spec_id) ?? loaded.id;
+  const targetFramework = asString(build?.target_framework);
+
+  return {
+    name: asString(identity?.name) ?? specId,
+    specId,
+    specVersion: asString(meta?.spec_version) ?? "unknown",
+    stage: asString(loopState?.stage) ?? "unknown",
+    lastVerdict: asString(loopState?.last_verdict),
+    // Link path uses the on-disk dir id (disk truth), not the parsed spec_id.
+    specPath: `${STAGE_DIRS.specs}/${loaded.id}/agentspec.yaml`,
+    build: targetFramework
+      ? { targetFramework, runtime: asString(build?.runtime) ?? "—" }
+      : null,
+    codeRefs,
+    contextLinks,
+  };
+}
+
+/**
+ * Build the whole index model from parsed specs + config + an injected clock. PURE:
+ * no I/O, no `Date.now()`. Entries are sorted by spec_id for deterministic output.
+ */
+export function buildIndexModel(input: BuildIndexInput): IndexModel {
+  const codeRefs = extractCodeRefs(input.config);
+  const contextLinks = extractContextLinks(input.config);
+  const entries = input.specs
+    .map((s) => buildEntry(s, codeRefs, contextLinks))
+    .sort((a, b) => a.specId.localeCompare(b.specId));
+  return { updated: input.nowIso.slice(0, 10), entries };
+}
+
+// ── Injected I/O seam (byte-stable tests with no disk) ──────────────────────────
+
+/**
+ * The file-system seam `regenerateIndex` depends on. The live binding uses `node:fs`;
+ * tests inject an in-memory fake so a full regenerate round-trips WITHOUT touching disk.
+ */
+export interface IndexIo {
+  /** List the spec directories directly under `<root>/.mutagent/specs` (dir names only). */
+  listSpecDirs(specsRoot: string): string[];
+  /** Read `<specsRoot>/<specId>/agentspec.yaml`, or null when absent. */
+  readSpec(specsRoot: string, specId: string): string | null;
+  /** Read `<root>/.mutagent/config.yaml`, or null when absent. */
+  readConfig(configFile: string): string | null;
+  /** Write the regenerated `<root>/.mutagent/index.md`. */
+  writeIndex(indexFile: string, content: string): void;
+}
+
+/** Live IndexIo — binds real `node:fs`. */
+export const liveIo: IndexIo = {
+  listSpecDirs(specsRoot: string): string[] {
+    let names: string[];
+    try {
+      names = fs.readdirSync(specsRoot);
+    } catch {
+      return [];
+    }
+    return names.filter((n) => {
+      try {
+        return fs.statSync(path.join(specsRoot, n)).isDirectory();
+      } catch {
+        return false;
+      }
+    });
+  },
+  readSpec(specsRoot: string, specId: string): string | null {
+    const p = path.join(specsRoot, specId, "agentspec.yaml");
+    try {
+      return fs.readFileSync(p, "utf8");
+    } catch {
+      return null;
+    }
+  },
+  readConfig(configFile: string): string | null {
+    try {
+      return fs.readFileSync(configFile, "utf8");
+    } catch {
+      return null;
+    }
+  },
+  writeIndex(indexFile: string, content: string): void {
+    fs.mkdirSync(path.dirname(indexFile), { recursive: true });
+    fs.writeFileSync(indexFile, content, "utf8");
+  },
+};
+
+export interface RegenerateResult {
+  /** Absolute path to the written `.mutagent/index.md`. */
+  indexFile: string;
+  /** The exact bytes written (returned for round-trip assertions). */
+  content: string;
+}
+
+/**
+ * Regenerate `<root>/.mutagent/index.md` from every `agentspec.yaml` under
+ * `<root>/.mutagent/specs/*` + the install config. DETERMINISTIC given (disk state, nowIso):
+ * re-running with the same inputs writes byte-identical output. The clock is INJECTED; the
+ * fs is INJECTED (defaults to `liveIo`). A spec whose YAML fails to parse is SKIPPED (its
+ * row is dropped rather than crashing the whole regen — fail-soft per-entry).
+ */
+export function regenerateIndex(
+  root: string,
+  nowIso: string,
+  io: IndexIo = liveIo,
+): RegenerateResult {
+  const specsRoot = stageDir(root, STAGE_DIRS.specs);
+  const configFile = path.join(mutagentDir(root), "config.yaml");
+  const indexFile = path.join(mutagentDir(root), "index.md");
+
+  const specs: LoadedSpec[] = [];
+  for (const id of io.listSpecDirs(specsRoot)) {
+    const raw = io.readSpec(specsRoot, id);
+    if (raw === null) continue;
+    let parsed: unknown;
+    try {
+      parsed = parseYaml(raw);
+    } catch {
+      continue; // fail-soft: a malformed spec drops its row, never the whole index.
+    }
+    specs.push({ id, spec: parsed });
+  }
+
+  const configRaw = io.readConfig(configFile);
+  let config: unknown = null;
+  if (configRaw !== null) {
+    try {
+      config = parseYaml(configRaw);
+    } catch {
+      config = null; // no config links rather than a crash.
+    }
+  }
+
+  const model = buildIndexModel({ specs, config, nowIso });
+  const content = renderIndex(model);
+  io.writeIndex(indexFile, content);
+  return { indexFile, content };
+}
+
+// ── CLI — regenerate the index for the resolved (or supplied) install root ──────
+//
+//   bun run scripts/index/build-index.ts [root] [--now <ISO8601>]
+//
+// `root` defaults to the resolved `.mutagent/` install root. `--now` overrides the
+// clock (deterministic scripting / reproducing a stamp); default is the wall clock.
+
+function runCli(argv: string[]): number {
+  const args = argv.slice(2);
+  const nowFlagIdx = args.indexOf("--now");
+  const nowIso =
+    nowFlagIdx >= 0 && args[nowFlagIdx + 1]
+      ? (args[nowFlagIdx + 1] as string)
+      : new Date().toISOString();
+  const positional = args.find((a, i) => !a.startsWith("--") && i !== nowFlagIdx + 1);
+  const root = positional ? path.resolve(positional) : resolveConfigRoot();
+
+  const { indexFile } = regenerateIndex(root, nowIso);
+  console.info(`[build-index] wrote ${indexFile} (root: ${path.join(root, MUTAGENT_DIR)})`);
+  return 0;
+}
+
+const isMain =
+  typeof import.meta !== "undefined" &&
+  (import.meta as unknown as { main?: boolean }).main === true;
+if (isMain) {
+  const argv = typeof Bun !== "undefined" ? Bun.argv : process.argv;
+  process.exit(runCli(argv));
+}

package/mutagent-orchestrator/scripts/index/render-index.ts

@@ -0,0 +1,110 @@
+/**
+ * scripts/index/render-index.ts
+ * F4 — the `.mutagent/index.md` REGISTRY renderer (pure model → markdown).
+ * Type A — Pure Script (no I/O, no clock — the model already carries the injected date).
+ *
+ * The rendered markdown IS the machine surface (no sidecar JSON): section headers +
+ * markdown links are what downstream reads. HIGH-LEVEL ONLY — identity · stage · verdict ·
+ * build target + LINKS. NEVER eval criteria / scenarios (anti-drift; see build-index.ts).
+ *
+ * DETERMINISM: a pure function of the model. Same model in → byte-identical string out.
+ * Output ends with exactly one trailing newline (POSIX-friendly, stable across regens).
+ */
+
+import type {
+  IndexCodeLink,
+  IndexContextLink,
+  IndexEntry,
+  IndexModel,
+} from "./build-index.ts";
+
+const TITLE = "# MutagenT — Agent Index";
+const BLURB_1 =
+  "> Spec ↔ implementation registry. Regenerated at each ADL stage — do not hand-edit.";
+const BLURB_2 =
+  "> HIGH-LEVEL links only (anti-drift): identity · stage · verdict · version/date + links. No eval criteria/scenarios.";
+const EMPTY_NOTE = "_No agent specs registered yet._";
+
+/** The em-dash placeholder for an absent value (verdict / runtime). */
+const NONE = "—";
+
+/**
+ * Link out to a PROJECT-ROOT-relative path from the index, which lives at
+ * `<root>/.mutagent/index.md`. Config paths are project-root-relative (determinism rule),
+ * so hop out of `.mutagent/` with a `../` prefix. Absolute paths (unusual) pass through.
+ */
+function projectRootHref(p: string): string {
+  if (p.startsWith("/")) return p;
+  return `../${p.replace(/^\.\//, "")}`;
+}
+
+/** `[label](href)` — label defaults to the raw path (its most recognizable form). */
+function mdLink(hrefPath: string, label: string, projectRoot: boolean): string {
+  const href = projectRoot ? projectRootHref(hrefPath) : hrefPath;
+  return `[${label}](${href})`;
+}
+
+function renderCodeRefs(refs: IndexCodeLink[]): string[] {
+  if (refs.length === 0) return [];
+  const lines = ["- **Agent code / tooling / harness / runtime:**"];
+  for (const r of refs) {
+    const suffix = r.why ? ` — ${r.why}` : "";
+    lines.push(`  - ${mdLink(r.path, r.path, true)}${suffix}`);
+  }
+  return lines;
+}
+
+function renderContextLinks(links: IndexContextLink[]): string[] {
+  if (links.length === 0) return [];
+  const lines = ["- **Context / product docs:**"];
+  for (const c of links) {
+    const what = c.what ? ` — ${c.what}` : "";
+    const when = c.when ? ` _(when: ${c.when})_` : "";
+    lines.push(`  - ${mdLink(c.path, c.path, true)}${what}${when}`);
+  }
+  return lines;
+}
+
+/**
+ * Render one agent's section. `updated` is the model's injected date (a single regen stamp
+ * for the whole file) — NOT the spec's own `loop_state.updated_at`, so the file is byte-stable
+ * under an injected clock (the F4 determinism contract).
+ */
+export function renderEntry(entry: IndexEntry, updated: string): string[] {
+  const verdict = entry.lastVerdict ?? NONE;
+  const lines: string[] = [
+    `## ${entry.name} — \`spec_id: ${entry.specId}\`  ·  spec v${entry.specVersion}  ·  updated ${updated}`,
+    `- **Spec:** ${mdLink(entry.specPath, "agentspec.yaml", false)} · stage: ${entry.stage} · verdict: ${verdict}`,
+  ];
+  if (entry.build) {
+    lines.push(
+      `- **Build:** target ${entry.build.targetFramework} · runtime ${entry.build.runtime}`,
+    );
+  }
+  lines.push(...renderCodeRefs(entry.codeRefs));
+  lines.push(...renderContextLinks(entry.contextLinks));
+  return lines;
+}
+
+/**
+ * Render the whole index model to markdown. PURE: same model → byte-identical string.
+ * Layout: title · two-line anti-drift blurb · `updated <date> · N agent(s)` summary ·
+ * one `##` section per agent (sorted by spec_id upstream). Empty index → a friendly note.
+ */
+export function renderIndex(model: IndexModel): string {
+  const count = model.entries.length;
+  const summary = `_updated ${model.updated} · ${count} ${count === 1 ? "agent" : "agents"}_`;
+
+  const blocks: string[] = [TITLE, "", BLURB_1, BLURB_2, "", summary, ""];
+
+  if (count === 0) {
+    blocks.push(EMPTY_NOTE);
+  } else {
+    for (const entry of model.entries) {
+      blocks.push(...renderEntry(entry, model.updated), "");
+    }
+    blocks.pop(); // drop the trailing spacer; the final newline is added below.
+  }
+
+  return blocks.join("\n") + "\n";
+}

package/mutagent-orchestrator/scripts/monitor/slack-notify.ts

@@ -0,0 +1,111 @@
+// ---------------------------------------------------------------------------
+// monitor/slack-notify — the External Monitor's OWN Slack emitter (EXT-1).
+//
+// The OUTWARD monitor's voice: a discrete NOTIFICATION (one standalone message)
+// each time a trigger fires — human-readable + precise (trigger · what fired ·
+// routed stage). This is NOT a live thread (that is the dogfood monitor's voice,
+// dogfood/slack-thread.ts); it is a one-shot event notification.
+//
+// PURE message builder: `monitorNotifyMessage(match, meta) → SlackMsg` is
+// `input → message`, no I/O/clock/random — identical input ⇒ byte-identical text
+// (deterministic tests). Posting goes through `../slack/post` (the ONE shared
+// impure seam), config-gated: an unconfigured sink ⇒ a no-op that touches ZERO
+// network (the guard lives in slack/post — a broken/absent Slack never errors).
+//
+// SEPARATION (load-bearing — ADR-6/ADR-11): this emitter imports ONLY `../slack/*`
+// (shared transport + primitives) + its sibling `./triggers.ts` (the TriggerMatch
+// type). It NEVER imports the dogfood monitor's emitter (`../dogfood/*`). Shared
+// transport, separate semantics — a test asserts the import boundary.
+// ---------------------------------------------------------------------------
+
+import { bold, code, italic } from "../slack/format.ts";
+import { postMessage } from "../slack/post.ts";
+import type { PostDeps, PostResult, SlackMsg } from "../slack/post.ts";
+import type { TriggerMatch } from "./triggers.ts";
+
+/** Routing ADL-stage → a compact display label with its circled numeral (self-contained). */
+const STAGE_DISPLAY: Readonly<Record<string, string>> = {
+  spec: "① SPEC",
+  build: "② BUILD",
+  evaluate: "③ EVALUATE",
+  diagnose: "④ DIAGNOSE",
+  improve: "⑤ IMPROVE",
+  audit: "③ EVALUATE (audit)",
+};
+
+/** Display a stage token; unknown tokens fall back to their upper-case form. */
+function stageLabel(stage: string): string {
+  return STAGE_DISPLAY[stage] ?? stage.toUpperCase();
+}
+
+/** Metadata for a monitor notification (optional context on the fired trigger). */
+export interface MonitorNotifyMeta {
+  /** Human project label (the monitored system), optional. */
+  project?: string;
+}
+
+/**
+ * Build the discrete notification for one fired trigger. PURE + deterministic —
+ * identical (match, meta) ⇒ identical `SlackMsg`. `kind:"root"` because each
+ * notification is a standalone top-level message (not a thread reply).
+ */
+export function monitorNotifyMessage(match: TriggerMatch, meta: MonitorNotifyMeta = {}): SlackMsg {
+  const project = meta.project ? ` · project ${bold(meta.project)}` : "";
+  const runs = match.run ? ` · runs ${code(match.run)}` : "";
+  const text =
+    `🛰️ ${bold("External Monitor")} — trigger ${code(match.rule.on)} fired → routed ` +
+    `${bold(stageLabel(match.stage))}${project} · ${italic(match.reason)}${runs}`;
+  return { kind: "root", text };
+}
+
+/**
+ * The External Monitor's Slack sink config (mirrors `config.monitor.slack`). Kept
+ * as a LOCAL structural type — this emitter deliberately does NOT import
+ * `../config-schema.ts` (the separation boundary is `../slack/*` only). The agent
+ * passes `config.monitor?.slack` in.
+ */
+export interface MonitorSlackConfig {
+  enabled?: boolean;
+  channel: string;
+  /** The ENV-VAR NAME holding the bot token (xoxb-…) — a reference, never a secret. */
+  token_ref: string;
+}
+
+/** A resolved Slack sink — a concrete channel + bot token ready to post with. */
+export interface MonitorSink {
+  channel: string;
+  token: string;
+}
+
+/**
+ * Resolve `config.monitor.slack` to a concrete sink, or null when Slack is not
+ * configured. Active ONLY when `enabled:true` AND the `token_ref` env var is set
+ * (same discipline as the dogfood sink / credentials_ref: `token_ref` is an
+ * env-var NAME, never a raw secret). `env` is INJECTED so tests stay deterministic
+ * (defaults to `process.env`).
+ */
+export function resolveMonitorSink(
+  slack: MonitorSlackConfig | undefined,
+  env: Record<string, string | undefined> = process.env,
+): MonitorSink | null {
+  if (slack === undefined || slack.enabled !== true) return null;
+  const token = env[slack.token_ref];
+  if (token === undefined || token.length === 0) return null;
+  return { channel: slack.channel, token };
+}
+
+/**
+ * Post a monitor notification via the shared transport. CONFIG-GATED NO-OP: with a
+ * null sink (Slack unconfigured/disabled) the underlying `postMessage` receives an
+ * empty channel/undefined token and no-ops — returns null, ZERO network. `deps`
+ * injects `fetch` for tests (mirrors slack/post).
+ */
+export async function postMonitorNotification(
+  match: TriggerMatch,
+  meta: MonitorNotifyMeta,
+  sink: MonitorSink | null,
+  deps: PostDeps = {},
+): Promise<PostResult | null> {
+  const msg = monitorNotifyMessage(match, meta);
+  return postMessage({ channel: sink?.channel ?? "", text: msg.text, token: sink?.token }, deps);
+}