@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/answer-question.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * @file answer-question.mjs  -  record the answer to the question a run
+ * stopped on, and clear the question in the same write.
+ *
+ * A step that needs a person and has nobody to ask writes
+ * `state.pendingQuestion` ({id, stepId, text, kind, options[]}) with
+ * `waitingFor: "question"` and stops. `/multi-agent:resume <id> --answer
+ * <optionId>` calls this before re-entering `stepId`; the step then reads
+ * `state.lastAnswer` instead of asking again. This is the general form of the
+ * `waitingFor` re-entry resume already performs for maturity and channels.
+ *
+ * The answer is data. It must be one of `options[].id` - a free-text reply, an
+ * id the question never offered, or a second id on a single-select question is
+ * refused and nothing is written. That is what keeps a reply from becoming an
+ * instruction: the step can only ever see an option it wrote itself.
+ *
+ * The write is a compare-and-swap on `rev` through write-state.mjs, so an
+ * answer to a question the run has since replaced is refused (exit 5) instead
+ * of merged over newer state.
+ *
+ * `--question <id>` names the question the caller saw. When the run has since
+ * moved on to another question the answer is refused even if the option ids
+ * happen to match, because they would be answering something nobody read.
+ * contract-server.mjs always passes it (answer-request.schema.json requires it).
+ *
+ * Usage:
+ *   node answer-question.mjs <agent-state.json> [--question <id>] --answer <optionId>[,<optionId>...]
+ *
+ * Exit: 0 recorded, 1 refused (no pending question, another question, or not
+ * one of its options), 2 usage, 5 the state moved underneath and nothing was
+ * written.
+ *
+ * @module pipeline/scripts/answer-question
+ */
+
+import { readRegularFile, RegularFileError } from "../lib/regular-file.mjs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+
+const STATE_MAX_BYTES = 16 * 1024 * 1024;
+
+/**
+ * The state after the answer, or the reason there is none. Pure.
+ *
+ * `reason` is a fixed code for the refusal - not-waiting, wrong-question,
+ * no-answer, arity or not-an-option - so a caller can map it without parsing
+ * the message.
+ *
+ * @param {object} state
+ * @param {string[]} optionIds
+ * @param {Date} [now]
+ * @param {{questionId?: string|null}} [opts]
+ * @returns {{state: object} | {error: string, reason: string}}
+ */
+export function applyAnswer(state, optionIds, now = new Date(), { questionId = null } = {}) {
+  const q = state?.pendingQuestion;
+  if (state?.waitingFor !== "question" || !q || typeof q !== "object") {
+    return { error: "this run is not waiting on a question", reason: "not-waiting" };
+  }
+  if (questionId !== null && questionId !== q.id) {
+    return {
+      error: `the run is asking ${q.id}, not ${questionId}`,
+      reason: "wrong-question",
+    };
+  }
+  const offered = Array.isArray(q.options) ? q.options.map((o) => o.id) : [];
+  if (!optionIds.length) return { error: "no answer given", reason: "no-answer" };
+  if (q.kind !== "multi-select" && optionIds.length !== 1) {
+    return { error: `question ${q.id} takes exactly one answer`, reason: "arity" };
+  }
+  const unknown = optionIds.filter((id) => !offered.includes(id));
+  if (unknown.length) {
+    return {
+      error: `"${unknown.join(", ")}" is not an option of ${q.id} (${offered.join(", ")})`,
+      reason: "not-an-option",
+    };
+  }
+  const next = { ...state };
+  delete next.waitingFor;
+  next.pendingQuestion = null;
+  next.lastAnswer = {
+    questionId: q.id,
+    stepId: q.stepId,
+    optionIds: [...new Set(optionIds)],
+    answeredAt: now.toISOString(),
+  };
+  return { state: next };
+}
+
+/**
+ * Read, answer and write one state file. The CLI and contract-server.mjs both
+ * call this, so an answer is refused for the same reasons on either carrier.
+ *
+ * @param {string} file
+ * @param {string[]} optionIds
+ * @param {{questionId?: string|null}} [opts]
+ * @returns {{code: 0, out: object} | {code: 1|5, reason: string, error: string}}
+ */
+export function answerStateFile(file, optionIds, { questionId = null } = {}) {
+  let text;
+  try {
+    text = readRegularFile(file, { maxBytes: STATE_MAX_BYTES });
+  } catch (err) {
+    if (err instanceof RegularFileError && err.code === "missing") {
+      return { code: 1, reason: "no-state", error: "no state file" };
+    }
+    return { code: 1, reason: "no-state", error: "the state file is not a readable regular file" };
+  }
+  let state;
+  try {
+    state = JSON.parse(text);
+  } catch {
+    return { code: 1, reason: "no-state", error: "the state file does not parse" };
+  }
+  const result = applyAnswer(state, optionIds, new Date(), { questionId });
+  if (result.error) return { code: 1, reason: result.reason, error: result.error };
+  const writer = fileURLToPath(new URL("./write-state.mjs", import.meta.url));
+  const rev = Number.isInteger(state.rev) ? state.rev : 0;
+  const w = spawnSync(process.execPath, [writer, "--replace", `--if-rev=${rev}`, file], {
+    input: JSON.stringify(result.state),
+    encoding: "utf8",
+    timeout: 30000,
+  });
+  if (w.status !== 0) {
+    return w.status === 5
+      ? { code: 5, reason: "state-moved", error: "the run's state changed; nothing written" }
+      : {
+          code: 1,
+          reason: "write-failed",
+          error: `write-state exited ${w.status}`,
+          detail: w.stderr ?? "",
+        };
+  }
+  return { code: 0, out: { contractVersion: CONTRACT_VERSION, answered: result.state.lastAnswer } };
+}
+
+function main(argv) {
+  let file = null;
+  let answer = null;
+  let questionId = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--answer") answer = argv[++i] ?? "";
+    else if (argv[i].startsWith("--answer=")) answer = argv[i].slice(9);
+    else if (argv[i] === "--question") questionId = argv[++i] ?? "";
+    else if (!file) file = argv[i];
+    else {
+      process.stderr.write(`answer-question: unknown argument ${argv[i]}\n`);
+      return 2;
+    }
+  }
+  if (!file || answer === null) {
+    process.stderr.write(
+      "usage: answer-question.mjs <agent-state.json> [--question <id>] --answer <optionId>\n",
+    );
+    return 2;
+  }
+  const ids = answer
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const r = answerStateFile(file, ids, { questionId });
+  if (r.code !== 0) {
+    if (r.detail) process.stderr.write(r.detail);
+    const where = r.reason === "no-state" ? ` at ${file}` : "";
+    process.stderr.write(`answer-question: ${r.error}${where}; nothing written\n`);
+    return r.code;
+  }
+  process.stdout.write(JSON.stringify(r.out) + "\n");
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("answer-question", () => {
+    process.exitCode = main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/audit-log-rotate.sh

@@ -4,7 +4,7 @@
 # Per section18.2.4 of REFACTOR_PLAN_v3.7.md: audit log rotates daily, keeps 30 days
 # of compressed history, drops anything older.
 #
-# Install via launchd on macOS (preferred) or cron on Linux:
+# Install via launchd:
 #
 #   macOS launchd plist (~/Library/LaunchAgents/com.claude.audit-rotate.plist):
 #     <plist version="1.0"><dict>
@@ -19,9 +19,6 @@
 #     </dict></plist>
 #   Then: launchctl load ~/Library/LaunchAgents/com.claude.audit-rotate.plist
 #
-#   Linux cron (crontab -e):
-#     0 3 * * * bash $HOME/.claude/scripts/audit-log-rotate.sh
-#
 # Run manually anytime: bash audit-log-rotate.sh
 
 set -uo pipefail

package/pipeline/scripts/audit-log.sh

@@ -2,7 +2,7 @@
 # audit-log.sh  -  append a single PAT-lookup audit event.
 #
 # Per section18 of REFACTOR_PLAN_v3.7.md: every PAT lookup writes a structured event
-# to ~/.claude/logs/multi-agent/audit.jsonl. Repo URLs are SHA-256 hashed
+# to $LOGS_ROOT/audit.jsonl (default ~/.claude/logs/multi-agent). Repo URLs are SHA-256 hashed
 # (corporate paths are sensitive). Identity is logged by name (user's own debug).
 #
 # Usage:
@@ -36,7 +36,7 @@ case "$SUCCESS" in
   *) SUCCESS=true ;;
 esac
 
-AUDIT_FILE="${AUDIT_FILE:-$HOME/.claude/logs/multi-agent/audit.jsonl}"
+AUDIT_FILE="${AUDIT_FILE:-${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/audit.jsonl}"
 mkdir -p "$(dirname "$AUDIT_FILE")" 2>/dev/null || exit 0
 
 # Escape a string for embedding inside a JSON double-quoted value.
@@ -48,8 +48,8 @@ json_escape() {
 hash_url() {
   local url="$1"
   [ -z "$url" ] && { echo ""; return; }
-  # sha256sum first: it is the coreutils tool, present on Linux and in slim containers
-  # where `shasum` (a perl script) is not.
+  # sha256sum first: it is the coreutils tool, present where `shasum` (a perl
+  # script) may not be.
   if command -v sha256sum >/dev/null 2>&1; then
     printf '%s' "$url" | sha256sum | awk '{print $1}'
   elif command -v shasum >/dev/null 2>&1; then