@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/scripts/run-stop-guard.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * run-stop-guard.mjs  -  a session driving a pipeline run does not end its turn
+ * mid-phase without saying why.
+ *
+ * Claude Code Stop hook. When the session that is driving an active run tries
+ * to stop while the run is `in_progress`, below its mode's last phase, with no
+ * `haltReason` and no `waitingFor`, it answers
+ * `{"decision":"block","reason":...}`. The reason names the phase to finish
+ * and the two legal ways out: finish it, or record a halt (operations.md,
+ * "Halt visibility").
+ *
+ * Which run: _active-run.mjs findActiveRun, and only a run bound to this
+ * session by `sessionId` (MULTI_AGENT_SESSION_ID) or `hostSessionId`. A run
+ * found only because its worktree is the session's cwd never holds a stop: an
+ * old local-mode run has the project root as its worktree and would trap
+ * every later session opened there. No bound run: exit 0, no output.
+ *
+ * The stop is let through, with no output, whenever the session has a reason
+ * to stop that the state does not record:
+ *   - the turn ends waiting for the user: `last_assistant_message` ends in a
+ *     question or asks for a reply (the pipeline's plain-text waits: plan
+ *     approval, commit, PR, a local-test handoff);
+ *   - background tasks or scheduled crons are running, so the run is driven
+ *     elsewhere and this session is waiting;
+ *   - prefs.global.stopGuard.enabled is false.
+ *
+ * SubagentStop is never held: a subagent finishes its piece and the session
+ * that dispatched it decides what comes next.
+ *
+ * Repeat ceiling: the host sets `stop_hook_active` while it continues because
+ * of a Stop hook, and overrides a hook that blocks too many times in a row.
+ * This hook counts its own consecutive blocks per run in `.stop-guard.json`
+ * next to the state. After REPEAT_LIMIT blocks it stops blocking, writes the
+ * halt record itself (`status: paused`, `haltReason: "<phase>:stop-guard: ..."`)
+ * and tells the user through `systemMessage`. write-state.mjs clears that
+ * halt the moment the run advances a phase, so it never outlives the run
+ * moving on. A stop with `stop_hook_active` false is a new turn and starts the
+ * count again.
+ *
+ * This is a completion aid, not a security gate: any error (unparseable
+ * payload, unreadable state, a failed write) exits 0 with no decision and a
+ * line in <log root>/hook-failures.log.
+ *
+ * @module pipeline/scripts/run-stop-guard
+ */
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { globalPref } from "../lib/prefs-value.mjs";
+import {
+  finalPhaseOf,
+  findActiveRun,
+  logHookFailure,
+  modeOf,
+  phaseName,
+  runDirOf,
+} from "./_active-run.mjs";
+
+export const REPEAT_LIMIT = 3;
+export const STOP_GUARD_HALT = "stop-guard:";
+const COUNTER_FILE = ".stop-guard.json";
+const HOOK = "run-stop-guard";
+const SESSION_BOUND = new Set(["session", "host-session"]);
+
+// A reply the turn asks for, in the closing text: a question mark (ASCII or
+// full-width) at the end of a line, or a request addressed to the user. A
+// request is an imperative that opens a sentence ("Confirm the plan.") or a
+// second-person phrase ("can you", "tell me"); a reply verb inside a
+// statement ("Next I will confirm the build") is the model's own plan and
+// does not count, nor does one used as a label ("Answer: the cache was stale").
+const QUESTION_END = /[?？]\s*(?:\(.{0,40}\))?\s*$/;
+const REPLY_VERB =
+  "(?:reply|respond|answer|confirm|choose|pick|approve|send|write your|tell me|let me know)";
+const ASKS_FOR_REPLY = new RegExp(
+  [
+    `(?:^|[.!:;]\\s+)(?:please\\s+)?${REPLY_VERB}\\b(?!\\s*:)`,
+    `\\bplease\\s+${REPLY_VERB}\\b(?!\\s*:)`,
+    "\\b(?:can|could|would|will) you\\b",
+    "\\b(?:do|would) you (?:want|like|prefer)\\b",
+    "\\b(?:let me know|tell me)\\b",
+    "\\b(?:reply|respond|answer) with\\b",
+    "\\(\\s*(?:yes|y)\\s*\\/\\s*(?:no|n)\\s*\\)",
+  ].join("|"),
+  "im",
+);
+
+/**
+ * True when the closing assistant text waits for the user.
+ *
+ * @param {unknown} message  last_assistant_message
+ */
+export function asksTheUser(message) {
+  if (typeof message !== "string" || !message.trim()) return false;
+  const lines = message
+    .trim()
+    .split("\n")
+    .map((l) => l.replace(/[*_`>#]+/g, "").trim())
+    .filter(Boolean);
+  const tail = lines.slice(-3);
+  if (tail.some((l) => QUESTION_END.test(l))) return true;
+  return ASKS_FOR_REPLY.test(tail.join("\n"));
+}
+
+/**
+ * Why the run may stop now, or null when it is mid-phase and must not.
+ *
+ * @param {object} state
+ * @returns {string|null}
+ */
+export function stopAllowedBecause(state) {
+  if (!state || typeof state !== "object") return "no state";
+  if (state.status !== "in_progress") return `status is ${state.status ?? "unset"}`;
+  if (state.haltReason) return "a halt is recorded";
+  if (state.waitingFor) return `waiting for ${state.waitingFor}`;
+  const final = finalPhaseOf(state);
+  if (final === null) return `mode ${modeOf(state)} is not declared in phases.json`;
+  const cur = Number(state.currentPhase);
+  if (!Number.isInteger(cur)) return "currentPhase is not recorded";
+  if (cur >= final) return "the final phase is reached";
+  return null;
+}
+
+/** The block reason: where the run is and the two ways out. */
+export function blockReason(state, statePath) {
+  const cur = Number(state.currentPhase);
+  const final = finalPhaseOf(state);
+  const id = state.taskId || "this run";
+  return [
+    `Pipeline run ${id} (mode ${modeOf(state)}) is at Phase ${cur} (${phaseName(cur)}) of ${final}, status in_progress, and no halt or wait is recorded.`,
+    `Now finish Phase ${cur} (${phaseName(cur)}) and go on as its document says.`,
+    `If you are waiting for the user, ask the question so the turn ends on it, or record the wait: printf '{"waitingFor":"attended-reply"}' | node "$HOME/.claude/scripts/write-state.mjs" "${statePath}".`,
+    `If the run cannot go on, record the halt before stopping: printf '{"status":"paused","haltReason":"${cur}:<cause>"}' | node "$HOME/.claude/scripts/write-state.mjs" "${statePath}" (operations.md, Halt visibility).`,
+  ].join(" ");
+}
+
+function readCounter(dir) {
+  try {
+    const doc = JSON.parse(readFileSync(join(dir, COUNTER_FILE), "utf8"));
+    return Number.isInteger(doc?.count) ? doc.count : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function writeCounter(dir, count) {
+  writeFileSync(
+    join(dir, COUNTER_FILE),
+    `${JSON.stringify({ count, at: new Date().toISOString() })}\n`,
+  );
+}
+
+function clearCounter(dir) {
+  rmSync(join(dir, COUNTER_FILE), { force: true });
+}
+
+async function recordHalt(statePath, state, blocks) {
+  const { updateState } = await import("./gate-ledger.mjs");
+  const cur = Number(state.currentPhase);
+  const cause = `${STOP_GUARD_HALT} the guard blocked ${blocks} consecutive stops before Phase ${cur} (${phaseName(cur)}) finished`;
+  await updateState(statePath, (s) => ({
+    ...s,
+    status: "paused",
+    haltReason: `${cur}:${cause}`,
+  }));
+  return cause;
+}
+
+const nonEmpty = (v) => Array.isArray(v) && v.length > 0;
+
+/**
+ * The hook's answer for one payload.
+ *
+ * @param {object} payload
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {Promise<object|null>} the JSON to print, or null for no output
+ */
+export async function decide(payload, env = process.env) {
+  if (globalPref("stopGuard.enabled", true, env) === false) return null;
+  if (!payload || typeof payload !== "object") return null;
+  const event = payload.hook_event_name || "Stop";
+  if (event !== "Stop") return null;
+  if (nonEmpty(payload.background_tasks) || nonEmpty(payload.session_crons)) return null;
+  if (asksTheUser(payload.last_assistant_message)) return null;
+  const run = findActiveRun({
+    sessionId: typeof payload.session_id === "string" ? payload.session_id : null,
+    cwd: typeof payload.cwd === "string" ? payload.cwd : null,
+    env,
+  });
+  if (!run || !SESSION_BOUND.has(run.matchedBy)) {
+    if (!run && findActiveRun.lastUnreadable > 0) {
+      logHookFailure(
+        HOOK,
+        `${findActiveRun.lastUnreadable} run state file(s) did not parse; allowed the stop`,
+        env,
+      );
+    }
+    return null;
+  }
+  const dir = runDirOf(run.statePath);
+  if (stopAllowedBecause(run.state) !== null) {
+    if (existsSync(join(dir, COUNTER_FILE))) clearCounter(dir);
+    return null;
+  }
+
+  const prior = payload.stop_hook_active === true ? readCounter(dir) : 0;
+  if (prior >= REPEAT_LIMIT) {
+    const cause = await recordHalt(run.statePath, run.state, prior);
+    clearCounter(dir);
+    return {
+      systemMessage: `run-stop-guard: recorded a halt on ${run.state.taskId || run.statePath} (${cause}). Resume it with /multi-agent:resume.`,
+    };
+  }
+  writeCounter(dir, prior + 1);
+  return { decision: "block", reason: blockReason(run.state, run.statePath) };
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = readFileSync(0, "utf8");
+  } catch {
+    raw = "";
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    logHookFailure(HOOK, "the hook payload is not JSON; allowed the stop");
+    return;
+  }
+  try {
+    const out = await decide(payload);
+    if (out) process.stdout.write(`${JSON.stringify(out)}\n`);
+  } catch (err) {
+    logHookFailure(HOOK, `${err?.message || err}; allowed the stop`);
+  }
+}
+
+const onFatal = (err) => logHookFailure(HOOK, `${err?.message || err}; allowed the stop`);
+
+// Exit 0 on every path: nothing above sets a non-zero code, and a failure
+// is logged and allowed.
+if (invokedDirectly(import.meta.url)) main().catch(onFatal);

package/pipeline/scripts/run-stop-guard.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# run-stop-guard.sh  -  Stop hook for the multi-agent pipeline.
+#
+# A session driving a pipeline run that tries to end its turn mid-run, with no
+# halt recorded, is told to continue or record the halt. The decision is in
+# run-stop-guard.mjs; this wrapper exists because every hook the pipeline
+# registers is a `bash "$HOME/.<host>/scripts/<name>"` command.
+#
+# Contract (Claude Code Stop hook):
+#   - Reads the hook JSON on stdin.
+#   - Prints {"decision":"block","reason":...} to keep the session going, or
+#     {"systemMessage":...} when it gives up and records the halt itself, or
+#     nothing.
+#   - Exits 0 on every path. A missing node or any internal error means no
+#     output: this is a completion aid, not a security gate.
+
+set -u
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+CORE="$HERE/run-stop-guard.mjs"
+[ -f "$CORE" ] || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+node "$CORE" 2>/dev/null || true
+exit 0

package/pipeline/scripts/service-read.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * @file service-read.mjs  -  read one thing from Confluence, Crashlytics or
+ * Figma through the clients the pipeline already ships, for a client that
+ * shows it next to a run:
+ *
+ *   confluence <page>        lib/fetch-confluence.sh: a page by id or by https
+ *                            URL, both only on the configured
+ *                            prefs.global.hosts.confluence; a URL on any other
+ *                            host, or any URL when no host is configured, is
+ *                            refused before the script runs; title, markdown
+ *                            body, API contracts count
+ *   crashlytics <issue-url>  lib/fetch-crashlytics.sh: one Crashlytics issue,
+ *                            title, occurrences, impacted users, top frames
+ *   figma <file-key> <node>  lib/figma-screenshot.sh (REST with the Figma
+ *                            token, tier 2): one PNG render of a frame. The
+ *                            Figma MCP is never called here; the pipeline
+ *                            keeps MCP access to the analysis phase.
+ *
+ * Search across Confluence, a per-version Crashlytics trend and a Figma file
+ * browser have no client in the pipeline, so none is offered; a client asks
+ * an agent instead.
+ *
+ * The scripts run as child processes without blocking the caller's event
+ * loop (contract-server.mjs serves other routes meanwhile).
+ *
+ * Credentials are read only by those scripts, through credential-store.sh.
+ * Every text that comes back is scrubbed and redacted; an image comes back as
+ * base64.
+ *
+ * Usage:
+ *   service-read.mjs confluence <page-id|https-url>
+ *   service-read.mjs crashlytics <https-issue-url>
+ *   service-read.mjs figma <file-key> <node-id>
+ *
+ * MA_FETCH_CONFLUENCE, MA_FETCH_CRASHLYTICS and MA_FIGMA_SCREENSHOT stand in
+ * for the scripts (tests).
+ *
+ * Exit: 0 printed, 1 refused or failed, 2 usage.
+ *
+ * @module pipeline/scripts/service-read
+ */
+
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRedactor } from "./transcript-index.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TIMEOUT_MS = 90_000;
+const MAX_TEXT = 100_000;
+const MAX_IMAGE_BYTES = 8 * 1024 * 1024;
+export const PAGE_ID = /^[0-9]{1,20}$/;
+export const FIGMA_KEY = /^[A-Za-z0-9]{10,64}$/;
+export const FIGMA_NODE = /^[0-9]{1,10}[:-][0-9]{1,10}$/;
+
+export class ServiceError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+const script = (env, name, override) =>
+  env[override] ||
+  [join(HERE, "..", "lib", name), join(HERE, "..", "..", "lib", name)].find((p) => existsSync(p));
+
+function httpsUrl(v, host = null) {
+  if (typeof v !== "string" || v.length > 2048) return null;
+  let u;
+  try {
+    u = new URL(v);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "https:" || u.username || u.password) return null;
+  if (host && u.hostname !== host) return null;
+  return u.toString();
+}
+
+async function run(env, file, args, failCodes) {
+  if (!file) throw new ServiceError("not-installed", "the service client is not installed");
+  const r = await spawnAsync("bash", [file, ...args], { env, timeoutMs: TIMEOUT_MS });
+  if (r.status !== 0) {
+    const why = failCodes[r.status] ?? "the service could not be read";
+    throw new ServiceError("service-failed", why);
+  }
+  try {
+    return JSON.parse(r.stdout);
+  } catch {
+    throw new ServiceError(
+      "service-failed",
+      "the service answered with something that is not JSON",
+    );
+  }
+}
+
+function confluenceHost(env) {
+  try {
+    const prefs = JSON.parse(
+      readFileSync(
+        env.MULTI_AGENT_PREFS ||
+          join(env.HOME || homedir(), ".claude", "multi-agent-preferences.json"),
+        "utf8",
+      ),
+    );
+    const h = prefs?.global?.hosts?.confluence;
+    return typeof h === "string" && h ? h.replace(/^https?:\/\//, "").replace(/\/.*$/, "") : null;
+  } catch {
+    return null;
+  }
+}
+
+/** One Confluence page, by id or by a URL on the configured host only. */
+export async function confluencePage(page, env = process.env) {
+  let args;
+  const host = confluenceHost(env);
+  if (PAGE_ID.test(String(page))) {
+    if (!host) throw new ServiceError("not-configured", "no Confluence host is configured");
+    args = ["--host", host, "--page-id", String(page)];
+  } else {
+    const url = httpsUrl(page);
+    if (!url) throw new ServiceError("bad-input", "a page id or an https URL is required");
+    if (!host) {
+      throw new ServiceError(
+        "host-not-allowed",
+        "no Confluence host is configured, so only a page id is accepted",
+      );
+    }
+    if (new URL(url).hostname !== host) {
+      throw new ServiceError("host-not-allowed", "that host is not the configured Confluence host");
+    }
+    args = [url];
+  }
+  const d = await run(env, script(env, "fetch-confluence.sh", "MA_FETCH_CONFLUENCE"), args, {
+    2: "the Confluence credential is missing or was refused",
+    3: "Confluence could not be reached",
+    6: "that host is not the configured Confluence host",
+  });
+  const R = createRedactor();
+  return {
+    contractVersion: CONTRACT_VERSION,
+    service: "confluence",
+    pageId: d?.source?.pageId ? String(d.source.pageId) : null,
+    title: R.excerpt(d?.title ?? "", 300),
+    body: R.clean(String(d?.bodyMarkdown ?? "").slice(0, MAX_TEXT)),
+    apiContracts: Array.isArray(d?.apiContracts) ? d.apiContracts.length : 0,
+  };
+}
+
+/** One Crashlytics issue. */
+export async function crashlyticsIssue(issueUrl, env = process.env) {
+  const url = httpsUrl(issueUrl, "console.firebase.google.com");
+  if (!url) throw new ServiceError("bad-input", "a Firebase console issue URL is required");
+  const d = await run(env, script(env, "fetch-crashlytics.sh", "MA_FETCH_CRASHLYTICS"), [url], {
+    2: "the Firebase credential is missing or was refused",
+    3: "Crashlytics could not be reached",
+  });
+  const R = createRedactor();
+  const i = d?.issue ?? {};
+  return {
+    contractVersion: CONTRACT_VERSION,
+    service: "crashlytics",
+    title: R.excerpt(i.title ?? "", 300),
+    type: i.type ? String(i.type) : null,
+    occurrences: Number.isFinite(i.occurrences) ? i.occurrences : null,
+    impactedUsers: Number.isFinite(i.impactedUsers) ? i.impactedUsers : null,
+    stackTrace: (Array.isArray(i.stackTrace) ? i.stackTrace : [])
+      .slice(0, 40)
+      .map((f) => R.excerpt(typeof f === "string" ? f : JSON.stringify(f), 300)),
+  };
+}
+
+/** One frame rendered as PNG. */
+export async function figmaFrame(fileKey, nodeId, env = process.env) {
+  if (!FIGMA_KEY.test(String(fileKey)) || !FIGMA_NODE.test(String(nodeId))) {
+    throw new ServiceError("bad-input", "a Figma file key and a node id (1:2) are required");
+  }
+  const out = mkdtempSync(join(tmpdir(), "ma-figma-"));
+  try {
+    const file = script(env, "figma-screenshot.sh", "MA_FIGMA_SCREENSHOT");
+    if (!file) throw new ServiceError("not-installed", "the service client is not installed");
+    const r = await spawnAsync(
+      "bash",
+      [file, "--file-key", fileKey, "--node-id", nodeId.replace("-", ":"), "--output-dir", out],
+      { env, timeoutMs: TIMEOUT_MS, maxBytes: 1024 * 1024 },
+    );
+    const why = {
+      2: "the Figma token is missing or was refused",
+      4: "no such frame",
+      5: "Figma is rate limiting; try again later",
+      6: "Figma could not be reached",
+    };
+    if (r.status !== 0)
+      throw new ServiceError("service-failed", why[r.status] ?? "the frame could not be rendered");
+    const png = readdirSync(out).find((f) => f.endsWith(".png"));
+    if (!png || statSync(join(out, png)).size > MAX_IMAGE_BYTES) {
+      throw new ServiceError("service-failed", "the frame could not be rendered");
+    }
+    return {
+      contractVersion: CONTRACT_VERSION,
+      service: "figma",
+      fileKey,
+      nodeId: nodeId.replace("-", ":"),
+      mime: "image/png",
+      data: readFileSync(join(out, png)).toString("base64"),
+    };
+  } finally {
+    rmSync(out, { recursive: true, force: true });
+  }
+}
+
+async function main(argv) {
+  const [svc, a, b, ...rest] = argv;
+  try {
+    let out;
+    if (svc === "confluence" && a && !b) out = await confluencePage(a);
+    else if (svc === "crashlytics" && a && !b) out = await crashlyticsIssue(a);
+    else if (svc === "figma" && a && b && !rest.length) out = await figmaFrame(a, b);
+    else {
+      process.stderr.write(
+        "usage: service-read.mjs confluence <page> | crashlytics <issue-url> | figma <file-key> <node-id>\n",
+      );
+      return 2;
+    }
+    process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+    return 0;
+  } catch (err) {
+    if (!(err instanceof ServiceError)) throw err;
+    process.stderr.write(`service-read: ${err.message}\n`);
+    return 1;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("service-read", async () => {
+    process.exitCode = await main(process.argv.slice(2));
+  });
+}