@mmerterden/multi-agent-pipeline 16.19.0 → 16.21.0

package/pipeline/scripts/_fingerprint.mjs

@@ -0,0 +1,173 @@
+/**
+ * Finding fingerprint: the stable, cross-round identity of a review finding.
+ *
+ * A finding is the same finding from one Phase 4 round to the next when it
+ * names the same file and the same problem. The line moves once the fix lands,
+ * the severity can be lowered by triage, the fix text and the reviewer vary per
+ * round, so none of those take part. What remains is (file, ruleId) when the
+ * finding cites a rule, else (file, normalized issue text).
+ *
+ * Computed by scripts, never by the model: an older triage JSON gets its
+ * fingerprints on the fly and a reviewer that echoes one is respected but not
+ * relied on. Same argument shortId() in _retrieval.mjs makes for corpus rows.
+ *
+ * @module pipeline/scripts/_fingerprint
+ */
+
+import { shortId } from "./_retrieval.mjs";
+
+export const FINGERPRINT_RE = /^F:[0-9a-f]{8}$/;
+
+const QUOTES = /[`'"‘’“”«»]/g;
+const DIFF_PREFIX = /^(?:\.\/|[ab]\/)+/;
+
+/**
+ * Strip diff and relative prefixes; keep a multi-repo `<repo>/` prefix because
+ * the same path in two repos is two findings.
+ * @param {unknown} file
+ * @returns {string}
+ */
+export function normalizeFile(file) {
+  return String(file ?? "")
+    .trim()
+    .replace(DIFF_PREFIX, "");
+}
+
+/**
+ * Lowercase, quote-free, path-free, number-free text. Every digit run becomes
+ * `#` so a line reference or a count changes nothing while "retry # times" and
+ * "retry times" stay distinct. Tokens with a `/` collapse to their basename so a
+ * reviewer that writes the full path and one that writes the file name agree.
+ * @param {unknown} issue
+ * @returns {string}
+ */
+export function normalizeIssue(issue) {
+  return String(issue ?? "")
+    .toLowerCase()
+    .replace(QUOTES, "")
+    .split(/\s+/)
+    .map((tok) => (tok.includes("/") ? tok.slice(tok.lastIndexOf("/") + 1) : tok))
+    .join(" ")
+    .replace(/\d+/g, "#")
+    .replace(/[^a-z0-9# ]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * @param {{file?: unknown, issue?: unknown, ruleId?: unknown}} finding
+ * @returns {string} e.g. "F:3fa9c21b"
+ */
+export function findingFingerprint(finding) {
+  const file = normalizeFile(finding?.file);
+  const ruleId = typeof finding?.ruleId === "string" ? finding.ruleId.trim() : "";
+  if (ruleId) return shortId("F", file, "rule", ruleId.toLowerCase());
+  return shortId("F", file, normalizeIssue(finding?.issue));
+}
+
+/**
+ * Which arrays hold findings for each document kind. Triage buckets that wrap
+ * the finding (`deferred[].finding`) are addressed through `wrap`.
+ */
+const SHAPES = {
+  reviewer: [{ bucket: "findings", wrap: null }],
+  "dev-critic": [{ bucket: "findings", wrap: null }],
+  triage: [
+    { bucket: "accepted", wrap: null },
+    { bucket: "deferred", wrap: "finding" },
+    { bucket: "rejected", wrap: "finding" },
+  ],
+};
+
+export const KINDS = Object.freeze(Object.keys(SHAPES));
+
+/**
+ * @param {unknown} doc
+ * @returns {"triage"|"reviewer"|"dev-critic"|null}
+ */
+export function sniffKind(doc) {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) return null;
+  if (Array.isArray(doc.accepted)) return "triage";
+  if (Array.isArray(doc.findings)) return "iteration" in doc ? "dev-critic" : "reviewer";
+  return null;
+}
+
+function resolveKind(doc, kind) {
+  if (kind && kind !== "auto") {
+    if (!SHAPES[kind]) throw new Error(`unknown kind "${kind}" (expected ${KINDS.join("|")})`);
+    return kind;
+  }
+  const sniffed = sniffKind(doc);
+  if (!sniffed) throw new Error("cannot infer document kind: no findings[] or accepted[]");
+  return sniffed;
+}
+
+/**
+ * Return every finding object in the document, with its container so callers
+ * can mutate a copy in place.
+ * @param {object} doc
+ * @param {string} kind resolved kind
+ * @param {string[]} [buckets] subset of the kind's buckets
+ * @returns {Array<{bucket: string, index: number, finding: object, holder: object}>}
+ */
+export function walkFindings(doc, kind, buckets) {
+  const out = [];
+  for (const shape of SHAPES[kind]) {
+    if (buckets && !buckets.includes(shape.bucket)) continue;
+    const list = doc?.[shape.bucket];
+    if (!Array.isArray(list)) continue;
+    list.forEach((entry, index) => {
+      const holder = shape.wrap ? entry?.[shape.wrap] : entry;
+      if (holder && typeof holder === "object") {
+        out.push({ bucket: shape.bucket, index, finding: holder, holder });
+      }
+    });
+  }
+  return out;
+}
+
+/**
+ * Deep-copy the document and set `fingerprint` on every finding that lacks a
+ * valid one. Pure: the input is not mutated.
+ * @param {object} doc
+ * @param {string} [kind="auto"]
+ * @returns {{doc: object, kind: string, computed: number, kept: number}}
+ */
+export function annotate(doc, kind = "auto") {
+  const resolved = resolveKind(doc, kind);
+  const copy = structuredClone(doc);
+  let computed = 0;
+  let kept = 0;
+  for (const { finding } of walkFindings(copy, resolved)) {
+    if (typeof finding.fingerprint === "string" && FINGERPRINT_RE.test(finding.fingerprint)) {
+      kept += 1;
+      continue;
+    }
+    finding.fingerprint = findingFingerprint(finding);
+    computed += 1;
+  }
+  return { doc: copy, kind: resolved, computed, kept };
+}
+
+/**
+ * Map of fingerprint to finding over the chosen buckets and severities of an
+ * already-annotated document. When two findings share a fingerprint the first
+ * wins; the delta report prints the issue text so a human can see the merge.
+ * @param {object} doc annotated document
+ * @param {{kind?: string, buckets?: string[], severities?: string[]|null}} [opts]
+ * @returns {Map<string, object>}
+ */
+export function collectFingerprints(doc, opts = {}) {
+  const kind = resolveKind(doc, opts.kind ?? "auto");
+  const buckets = opts.buckets ?? SHAPES[kind].map((s) => s.bucket);
+  const severities = opts.severities ? new Set(opts.severities) : null;
+  const map = new Map();
+  for (const { finding } of walkFindings(doc, kind, buckets)) {
+    if (severities && !severities.has(finding.severity)) continue;
+    const fp = FINGERPRINT_RE.test(finding.fingerprint ?? "")
+      ? finding.fingerprint
+      : findingFingerprint(finding);
+    if (!map.has(fp)) map.set(fp, finding);
+  }
+  return map;
+}

package/pipeline/scripts/bulk-read.sh

@@ -0,0 +1,277 @@
+#!/usr/bin/env bash
+# bulk-read.sh  -  read a large file on the cheap rung and return a summary.
+#
+# The worker behind `check-read-size.sh`. The gate says a file is too big to be
+# worth reading whole at this phase's rung; this is where that read goes instead.
+# The full text reaches a haiku-rung worker, the worker returns a structured
+# summary WITH LINE NUMBERS, and only the summary enters the caller's context.
+#
+# Line numbers are the whole design, not a nicety. A summary without them is a
+# dead end: the caller cannot edit from it, cannot verify it, and ends up reading
+# the file anyway - having now paid twice. With them, the intended next step is a
+# bounded `Read(file, offset:, limit:)` around the region that matters, which is
+# both cheap and exact, and which the gate lets through.
+#
+# Usage:
+#   bulk-read.sh --file <path> [--question "<what you need>"] [--phase N]
+#                [--model <rung>] [--timeout <seconds>] [--json]
+#
+# Output: a human-readable summary on stdout, plus the ref id that buys the full
+# text back. `--json` prints the worker's raw object instead, for a caller that
+# wants to parse it.
+#
+# Degradation is explicit and always safe. No CLI, no auth, a timeout, or a
+# non-JSON answer -> this prints WHY and tells the caller to fall back to a
+# bounded read. It never invents a summary, and it never silently succeeds: a
+# fabricated summary of a file nobody read is the one outcome worse than paying
+# full price for the file.
+#
+# Exit codes: 0 summary produced · 3 degraded (caller should read it directly)
+#             1 usage error.
+
+set -uo pipefail
+
+FILE=""
+QUESTION="Summarize this file so a reader can decide which regions to open."
+PHASE="${MULTI_AGENT_PHASE:-0}"
+MODEL=""
+TIMEOUT=""
+AS_JSON=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --file) FILE="${2:?--file needs a value}"; shift 2 ;;
+    --question) QUESTION="${2:?--question needs a value}"; shift 2 ;;
+    --phase) PHASE="${2:?--phase needs a value}"; shift 2 ;;
+    --model) MODEL="${2:?--model needs a value}"; shift 2 ;;
+    --timeout) TIMEOUT="${2:?--timeout needs a value}"; shift 2 ;;
+    --json) AS_JSON=1; shift ;;
+    -h|--help) sed -n '2,30p' "$0"; exit 0 ;;
+    *) echo "bulk-read: unknown argument '$1'" >&2; exit 1 ;;
+  esac
+done
+
+[ -n "$FILE" ] || { echo "bulk-read: --file is required" >&2; exit 1; }
+[ -f "$FILE" ] || { echo "bulk-read: not a readable file: $FILE" >&2; exit 1; }
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+
+degrade() {
+  echo "bulk-read: DEGRADED  -  $1" >&2
+  echo "Read the region you need directly instead: Read('$FILE', offset: <n>, limit: <n>)." >&2
+  [ -x "$HERE/log-metric.sh" ] && \
+    "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.degraded \
+      reason="$1" >/dev/null 2>&1
+  exit 3
+}
+
+# Resolve the three prefs this script honours - `bulkRead.model` (which rung the
+# delegated read runs on), `bulkRead.timeoutSeconds` (how long it may take) and
+# `bulkRead.maxBytes` (the ceiling past which delegation stops being a saving).
+# Same search order and the same positive-integer rule as offload-ref.sh: a zero
+# or a string takes the default rather than silently disabling the control.
+PREF_MODEL=""
+PREF_TIMEOUT=""
+PREF_MAX_BYTES=""
+if command -v jq >/dev/null 2>&1; then
+  for prefs in \
+    "$HOME/.claude/multi-agent-preferences.json" \
+    "$HOME/.config/multi-agent-pipeline/multi-agent-preferences.json" \
+    "$HOME/.claude/preferences.json" \
+    "$HOME/.config/multi-agent-pipeline/preferences.json"
+  do
+    [ -f "$prefs" ] || continue
+    values=$(jq -r '.global.bulkRead // {} | [(.model // ""), (.timeoutSeconds // ""), (.maxBytes // "")] | @tsv' \
+      "$prefs" 2>/dev/null) || true
+    PREF_MODEL=$(printf '%s' "$values" | cut -f1)
+    PREF_TIMEOUT=$(printf '%s' "$values" | cut -f2)
+    PREF_MAX_BYTES=$(printf '%s' "$values" | cut -f3)
+    break
+  done
+fi
+[ -n "$MODEL" ] || MODEL="${PREF_MODEL:-haiku}"
+case "$TIMEOUT" in "" ) TIMEOUT="$PREF_TIMEOUT" ;; esac
+case "$TIMEOUT" in ""|*[!0-9]*|0) TIMEOUT=60 ;; esac
+
+command -v claude >/dev/null 2>&1 || degrade "the claude CLI is not on PATH"
+
+LINES=$(wc -l < "$FILE" | tr -d ' ')
+BYTES=$(wc -c < "$FILE" | tr -d ' ')
+
+# A ceiling, because delegation is not free either. Past some size the worker's
+# own input bill approaches the read it replaced, and a file large enough to
+# strain the worker's window would come back truncated - a partial summary
+# presented as a whole one is exactly what this must never produce. Degrading
+# here hands the caller a cheaper move (grep for the symbol, then read around it)
+# instead of an expensive round trip to a worse answer.
+case "$PREF_MAX_BYTES" in ""|*[!0-9]*|0) MAX_BYTES=1048576 ;; *) MAX_BYTES="$PREF_MAX_BYTES" ;; esac
+if [ "$BYTES" -gt "$MAX_BYTES" ]; then
+  echo "bulk-read: DEGRADED  -  ${FILE} is ${BYTES} bytes, past the ${MAX_BYTES}-byte ceiling" >&2
+  echo "At this size the delegated read costs about what reading it would, and risks a truncated" >&2
+  echo "summary presented as a whole one. Narrow it first: grep for the symbol you need, then" >&2
+  echo "Read('${FILE}', offset: <n>, limit: <n>) around the hit." >&2
+  [ -x "$HERE/log-metric.sh" ] && \
+    "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.degraded \
+      reason=over-ceiling file_bytes="$BYTES" >/dev/null 2>&1
+  exit 3
+fi
+
+# Measured and accepted, so park the full text before asking anything: the
+# pointer in the summary is then a promise that is already kept. The caller buys the rest back by reading this file - the same
+# contract offload-ref.sh makes for build logs, and the same directory.
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || true)
+[ -n "$ROOT" ] || ROOT="$PWD"
+REFS_DIR="$ROOT/.multi-agent/refs"
+NODE_ID=""
+if mkdir -p "$REFS_DIR" 2>/dev/null; then
+  GITIGNORE="$ROOT/.multi-agent/.gitignore"
+  if [ ! -f "$GITIGNORE" ]; then
+    printf '# Local run artefacts  -  never commit.\nmemory/\nrefs/\n' > "$GITIGNORE"
+  elif ! grep -q '^refs/$' "$GITIGNORE" 2>/dev/null; then
+    printf 'refs/\n' >> "$GITIGNORE"
+  fi
+  if command -v shasum >/dev/null 2>&1; then
+    DIGEST=$(shasum -a 256 "$FILE" | awk '{print substr($1,1,8)}')
+  elif command -v sha256sum >/dev/null 2>&1; then
+    DIGEST=$(sha256sum "$FILE" | awk '{print substr($1,1,8)}')
+  else
+    DIGEST=$(cksum < "$FILE" | awk '{print $1}')
+  fi
+  SLUG=$(basename "$FILE" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed 's/-\{1,\}/-/g; s/^-//; s/-$//')
+  NODE_ID="p${PHASE}-read-${SLUG:-file}-${DIGEST}"
+  cp "$FILE" "$REFS_DIR/${NODE_ID}.txt" 2>/dev/null || NODE_ID=""
+fi
+
+PROMPT_FILE="$(mktemp -t bulk-read.XXXXXX)"
+OUT_FILE="$(mktemp -t bulk-read-out.XXXXXX)"
+trap 'rm -f "$PROMPT_FILE" "$OUT_FILE"' EXIT
+
+# The worker gets numbered lines because every claim it makes has to be
+# addressable afterwards. `nl -ba` numbers blank lines too, so the numbers match
+# the file's own and an offset computed from them is correct.
+# The worker's contract is the bulk-reader PERSONA, loaded from disk rather than
+# restated here. Two copies of the same prompt is the drift this repo keeps
+# catching elsewhere: the copy that gets edited is never the copy that runs.
+PERSONA=""
+for candidate in \
+  "$HOME/.claude/agents/bulk-reader.md" \
+  "$HERE/../agents/bulk-reader.md"
+do
+  [ -f "$candidate" ] && { PERSONA="$candidate"; break; }
+done
+[ -n "$PERSONA" ] || degrade "the bulk-reader persona is not installed"
+
+# The frontmatter is dispatch metadata for the Agent tool, not instruction text;
+# strip it and send the body.
+{
+  awk 'BEGIN{fm=0} /^---$/{fm++; next} fm>=2{print}' "$PERSONA"
+  printf '\n<question>\n%s\n</question>\n\n' "$QUESTION"
+  printf '<file path="%s" lines="%s">\n' "$FILE" "$LINES"
+  nl -ba "$FILE"
+  printf '\n</file>\n'
+} > "$PROMPT_FILE"
+
+START=$(date +%s)
+# `claude -p` reads the prompt from stdin; the model flag names the rung. A
+# non-zero exit, an empty answer and a non-JSON answer are all degradations, and
+# each one names itself rather than falling through to a generic failure.
+# macOS ships no `timeout`; coreutils installs it as `gtimeout`. Naming only the
+# GNU spelling would leave the budget silently unenforced on the platform most of
+# these runs happen on - a pref that does nothing, which is the class
+# smoke-prefs-consumed exists to catch.
+TIMEOUT_BIN=""
+for candidate in timeout gtimeout; do
+  command -v "$candidate" >/dev/null 2>&1 && { TIMEOUT_BIN="$candidate"; break; }
+done
+if [ -n "$TIMEOUT_BIN" ]; then
+  "$TIMEOUT_BIN" "$TIMEOUT" claude -p --model "$MODEL" < "$PROMPT_FILE" > "$OUT_FILE" 2>/dev/null
+  STATUS=$?
+else
+  # No timeout binary: the budget cannot be enforced, so say so rather than
+  # letting the caller believe timeoutSeconds is holding.
+  echo "bulk-read: no timeout binary found; bulkRead.timeoutSeconds is not enforced on this host" >&2
+  claude -p --model "$MODEL" < "$PROMPT_FILE" > "$OUT_FILE" 2>/dev/null
+  STATUS=$?
+fi
+ELAPSED=$(( $(date +%s) - START ))
+
+[ "$STATUS" -eq 124 ] && degrade "the worker did not answer within ${TIMEOUT}s"
+[ "$STATUS" -ne 0 ] && degrade "the worker exited $STATUS"
+[ -s "$OUT_FILE" ] || degrade "the worker returned nothing"
+
+RENDER=$(FILE="$FILE" LINES="$LINES" BYTES="$BYTES" NODE_ID="$NODE_ID" \
+         MODEL="$MODEL" ELAPSED="$ELAPSED" AS_JSON="$AS_JSON" \
+         python3 - "$OUT_FILE" <<'PYEOF'
+import json, os, re, sys
+
+raw = open(sys.argv[1], encoding="utf-8", errors="replace").read()
+try:
+    data = json.loads(raw)
+except Exception:
+    # A worker that wrapped its object in prose or a fence is still usable; a
+    # worker that answered in prose is not, and falls through to the degrade path.
+    m = re.search(r"\{[\s\S]*\}", raw)
+    if not m:
+        sys.exit(7)
+    try:
+        data = json.loads(m.group(0))
+    except Exception:
+        sys.exit(7)
+
+if not isinstance(data, dict) or "summary" not in data:
+    sys.exit(7)
+
+if os.environ.get("AS_JSON") == "1":
+    print(json.dumps(data, indent=2))
+    sys.exit(0)
+
+out = []
+out.append("bulk-read: %s (%s lines, %s bytes) via %s in %ss"
+           % (os.environ["FILE"], os.environ["LINES"], os.environ["BYTES"],
+              os.environ["MODEL"], os.environ["ELAPSED"]))
+answer = (data.get("answer") or "").strip()
+if answer:
+    out.append("")
+    out.append("ANSWER: " + answer)
+out.append("")
+out.append((data.get("summary") or "").strip())
+
+symbols = [s for s in (data.get("symbols") or []) if isinstance(s, dict)]
+if symbols:
+    out.append("")
+    out.append("Symbols:")
+    for s in symbols[:40]:
+        out.append("  %-6s %s  (line %s)" % (s.get("kind", "?"), s.get("name", "?"), s.get("line", "?")))
+
+regions = [r for r in (data.get("regions") or []) if isinstance(r, dict)]
+if regions:
+    out.append("")
+    out.append("Read next (bounded, and this gate allows it):")
+    for r in regions[:8]:
+        start, end = r.get("start"), r.get("end")
+        span = ""
+        try:
+            span = "  Read(offset: %d, limit: %d)" % (int(start), int(end) - int(start) + 1)
+        except Exception:
+            pass
+        out.append("  %s-%s  %s%s" % (start, end, r.get("why", ""), span))
+
+node = os.environ.get("NODE_ID") or ""
+if node:
+    out.append("")
+    out.append("Full text: .multi-agent/refs/%s.txt  [[ref:%s]]" % (node, node))
+if data.get("truncated"):
+    out.append("")
+    out.append("NOTE: the worker reports it did not see the whole file.")
+print("\n".join(out))
+PYEOF
+) || degrade "the worker's answer was not the requested JSON object"
+
+printf '%s\n' "$RENDER"
+
+[ -x "$HERE/log-metric.sh" ] && \
+  "$HERE/log-metric.sh" "${MULTI_AGENT_TASK_ID:-unknown}" "$PHASE" bulk_read.delegated \
+    file_lines="$LINES" file_bytes="$BYTES" model="$MODEL" duration_ms="$(( ELAPSED * 1000 ))" \
+    >/dev/null 2>&1
+
+exit 0