@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/usage-report.mjs

@@ -1,22 +1,28 @@
 /**
  * usage-report.mjs  -  optional, opt-in per-run operational reporting.
  *
- * Off by default; a no-op unless prefs.global.usageLog.enabled is true and a
- * token resolves. Emits one compact run record keyed by run id (`taskId`),
- * upserted per phase, fire-and-forget - never throws, never delays a run.
+ * Off by default; a no-op unless prefs.global.usageLog.enabled is true, a
+ * token resolves, and a logged-in GitHub account can read the pipeline
+ * repository (usage-identity.mjs). Emits one compact run record keyed by run
+ * id (`taskId`), upserted at every phase transition and at completion, halt
+ * and park, fire-and-forget - never throws, never delays a run.
  * Only coarse run metadata is included; never prompts, code, diffs, token
- * values, or absolute paths.
+ * values, or absolute paths. The task title and the PR URL are sent only when
+ * usageLog.includeTitle / usageLog.includePrUrl are true.
  *
  * Enable + configure via prefs.global.usageLog:
  *   { "enabled": true,
  *     "endpoint": "https://mmerterden.com/api/usage/ingest",
  *     "token": "<shared ingest token>" }         // token may instead come from
  *                                                 // env MULTI_AGENT_USAGE_TOKEN
- * Nothing is sent when enabled is not true or no token resolves.
+ * Nothing is sent when enabled is not true, no token resolves, or no account
+ * has access (one line on stderr says which).
  *
  * Usage:
- *   node usage-report.mjs --state /path/to/agent-state.json
- *   node usage-report.mjs --task-id PROJ-123      # resolves the state path
+ *   node usage-report.mjs --state /path/to/agent-state.json [--event <kind>]
+ *   node usage-report.mjs --task-id PROJ-123 [--phase N] [--event <kind>]
+ *
+ *   --event  phase | completed | halted | parked  (default: derived from state)
  *
  * @module pipeline/scripts/usage-report
  */
@@ -28,6 +34,7 @@ import { fileURLToPath, pathToFileURL } from "url";
 import { execFileSync } from "child_process";
 import { createHash } from "crypto";
 import { costUsd } from "./_cost.mjs";
+import { defaultPrefsPath, resolveReportingLogin } from "./usage-identity.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ENDPOINT_DEFAULT = "https://mmerterden.com/api/usage/ingest";
@@ -47,13 +54,21 @@ function hostFile(...parts) {
 }
 
 function parseArgs(argv) {
-  const out = { state: null, taskId: null, phase: null, status: null, dryRun: false };
+  const out = {
+    state: null,
+    taskId: null,
+    phase: null,
+    status: null,
+    event: null,
+    dryRun: false,
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === "--state") out.state = argv[++i];
     else if (a === "--task-id") out.taskId = argv[++i];
     else if (a === "--phase") out.phase = argv[++i];
     else if (a === "--status") out.status = argv[++i];
+    else if (a === "--event") out.event = argv[++i];
     else if (a === "--dry-run") out.dryRun = true;
   }
   return out;
@@ -68,9 +83,7 @@ function readJson(path) {
 }
 
 function resolveGlobalPrefs() {
-  const path =
-    process.env.MULTI_AGENT_PREFS || join(homedir(), ".claude", "multi-agent-preferences.json");
-  return readJson(path)?.global ?? {};
+  return readJson(defaultPrefsPath())?.global ?? {};
 }
 
 function resolvePrefs() {
@@ -269,16 +282,61 @@ function inputType(state) {
   return "free-text";
 }
 
-// The command that was actually invoked (`/multi-agent:analysis`, `:review`,
-// ...). This used to return `state.mode`, so every row read "full" or "local"
-// and the one question the panel exists to answer - which command did people
-// run - had no answer in the data. `mode` still ships separately as `m`.
-function commandOf(state) {
-  const c = state.command;
-  if (typeof c === "string" && c.trim()) return c.trim().slice(0, 60);
-  if (state.mode) return state.mode;
-  if (state.localMode) return "local";
-  return "full";
+// The mode set is read from phases.json, which ships next to this script in
+// every install tree (<root>/schemas/phases.json). A mode that file does not
+// declare is reported as "unknown", so a state written by an older version
+// cannot put a mode name on the panel that the pipeline no longer has.
+function allowedModes() {
+  const candidates = [
+    join(__dirname, "..", "schemas", "phases.json"),
+    hostFile("schemas", "phases.json"),
+  ];
+  for (const p of candidates) {
+    const modes = p ? readJson(p)?.modes : null;
+    if (modes && typeof modes === "object" && !Array.isArray(modes)) return modes;
+  }
+  return {};
+}
+
+export function modeNames() {
+  return Object.keys(allowedModes());
+}
+
+function commandName(state) {
+  const c = typeof state.command === "string" ? state.command.trim() : "";
+  const m = c.match(/^\/multi-agent:([a-z0-9-]+)$/);
+  return m ? m[1] : null;
+}
+
+/**
+ * The run's mode, always one of phases.json's modes or "unknown". Order: the
+ * invoked command when it names a mode, an explicit state.mode, the autopilot
+ * flag (the mode phases.json marks autopilot: true), then "full", which is
+ * what an absent mode means in agent-state.schema.json.
+ */
+export function modeOf(state, modes = allowedModes()) {
+  const names = Object.keys(modes);
+  const has = (n) => typeof n === "string" && names.includes(n);
+  const cmd = commandName(state);
+  if (has(cmd)) return cmd;
+  if (typeof state.mode === "string" && state.mode.trim()) {
+    return has(state.mode.trim()) ? state.mode.trim() : "unknown";
+  }
+  if (state.autopilot === true) {
+    const ap = names.find((n) => modes[n]?.autopilot === true);
+    if (ap) return ap;
+  }
+  return has("full") ? "full" : "unknown";
+}
+
+// The command that was invoked, when the state names one that still ships
+// (`<root>/commands/multi-agent/<name>/`); otherwise the run's mode.
+function commandOf(state, mode) {
+  const name = commandName(state);
+  if (name && existsSync(join(__dirname, "..", "commands", "multi-agent", name))) {
+    return `/multi-agent:${name}`;
+  }
+  return mode;
 }
 
 // A repository name is the user's, not ours. It put a corporate project into
@@ -322,6 +380,7 @@ function trackerSummary(state) {
     models: [],
     startedAt: null,
     endedAt: null,
+    current: null,
   };
   const path = resolveTracker(state);
   if (!path) return empty;
@@ -365,6 +424,11 @@ function trackerSummary(state) {
     });
   }
   phs.sort((a, b) => Number(a.p) - Number(b.p));
+  const numeric = phs.filter((p) => typeof p.p === "number");
+  const running = numeric.filter((p) => p.st === "in_progress");
+  const reached = numeric.filter((p) => ["completed", "failed"].includes(p.st));
+  const pick = running.length ? running : reached;
+  const current = pick.length ? pick[pick.length - 1].p : null;
 
   const total = tin + tout + tcache;
   // Price each phase at its OWN model's rate, matching phase-tracker.sh; a run
@@ -400,12 +464,14 @@ function trackerSummary(state) {
     models: Array.from(models).slice(0, 10),
     startedAt,
     endedAt,
+    current,
   };
 }
 
 function deriveErrors(state, failedPhases) {
   const errs = new Set();
-  if (state.haltReason) errs.add(String(state.haltReason));
+  const halt = reasonCode(state, "halted");
+  if (halt) errs.add(halt);
   for (const id of failedPhases ?? []) errs.add(`phase-${id}-failed`);
   const s = String(state.status || "").toLowerCase();
   if (s === "failed") errs.add("run-failed");
@@ -431,17 +497,108 @@ function runId(state) {
   return base == null ? null : String(base);
 }
 
-function eventTimestamp(state, spend) {
-  if (state.finishedAt) return state.finishedAt;
-  if (isTerminalStatus(state) && spend?.endedAt) return spend.endedAt;
-  return state.updatedAt || new Date().toISOString();
+export const EVENT_KINDS = ["phase", "completed", "halted", "parked"];
+
+/**
+ * The run status the panel shows, from the event that triggered the report or,
+ * without one, from the state file. Values: completed, halted, parked, failed,
+ * in_progress. A parked run is waiting on a person (awaiting_input, or a
+ * waitingFor step); a halted one stopped on an error and is resumable.
+ */
+function runStatus(state, event) {
+  if (event === "completed") return "completed";
+  if (event === "halted") return "halted";
+  if (event === "parked") return "parked";
+  const s = String(state.status || "").toLowerCase();
+  if (s === "failed" && !state.haltReason) return "failed";
+  if (state.haltReason || s === "paused" || s === "halted" || s === "failed") return "halted";
+  if (s === "awaiting_input" || state.waitingFor) return "parked";
+  if (s === "complete" || s === "completed") return "completed";
+  return "in_progress";
+}
+
+function codeOf(raw, max = 60) {
+  if (typeof raw !== "string") return null;
+  const c = raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9:_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, max);
+  return c || null;
 }
 
-const TERMINAL_STATUSES = ["complete", "completed", "failed", "paused", "halted", "error"];
+const ABSOLUTE_PATH = /(?:~|\/(?:Users|home|var|private|tmp|opt|etc|Volumes))\/\S*|[A-Za-z]:\\\S*/g;
 
-function isTerminalStatus(state) {
-  if (state.haltReason) return true;
-  return TERMINAL_STATUSES.includes(String(state.status || "").toLowerCase());
+/**
+ * A short machine-readable reason: the halt cause as `<phase>:<cause>` or the
+ * step a parked run waits at. Paths are removed before the text is reduced to
+ * [a-z0-9:_-], so a cause that quoted a file cannot carry a home directory.
+ */
+function reasonCode(state, status) {
+  if (status === "halted" || status === "failed") {
+    const hr =
+      typeof state.haltReason === "string" ? state.haltReason.replace(ABSOLUTE_PATH, " ") : "";
+    if (!hr.trim()) return status === "failed" ? "run-failed" : null;
+    const m = hr.match(/^\s*(\d+)\s*:(.*)$/);
+    if (m) {
+      const cause = codeOf(m[2], 40);
+      return cause ? `${m[1]}:${cause}` : m[1];
+    }
+    return codeOf(hr, 48);
+  }
+  if (status === "parked") {
+    return codeOf(state.waitingFor) || codeOf(state.status) || "awaiting-input";
+  }
+  return null;
+}
+
+/** Opt-in: a one-line task title with paths, markup and code spans removed. */
+export function titleSummary(state, prefs) {
+  if (prefs?.includeTitle !== true) return null;
+  const candidates = [
+    state.title,
+    state.jiraSummary,
+    state.jiraTitle,
+    state.jira?.summary,
+    state.issue?.title,
+    state.issue?.summary,
+    state.githubIssue?.title,
+  ];
+  const raw = candidates.find((c) => typeof c === "string" && c.trim());
+  if (!raw) return null;
+  const clean = raw
+    .replace(/`[^`]*`/g, " ")
+    .replace(ABSOLUTE_PATH, " ")
+    .replace(/[<>{}[\]`]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!clean) return null;
+  return clean.length > 80 ? `${clean.slice(0, 79)}...` : clean;
+}
+
+/** Opt-in: the PR URL, https only. */
+export function prUrlOf(state, prefs) {
+  if (prefs?.includePrUrl !== true) return null;
+  const url = typeof state.pr === "string" ? state.pr : state.pr?.url;
+  if (typeof url !== "string") return null;
+  try {
+    const u = new URL(url.trim());
+    return u.protocol === "https:" ? u.href.slice(0, 200) : null;
+  } catch {
+    return null;
+  }
+}
+
+function hasPr(state) {
+  if (typeof state.pr === "string") return Boolean(state.pr.trim());
+  return Boolean(state.pr && (state.pr.url || state.pr.number));
+}
+
+function eventTimestamp(state, status) {
+  if (status === "completed" && state.finishedAt) return state.finishedAt;
+  return new Date().toISOString();
 }
 
 function appendErrorLedger(event) {
@@ -464,49 +621,46 @@ function appendErrorLedger(event) {
   }
 }
 
-// Telemetry identity is the GitHub ACCOUNT NAME, never the git identity.name
-// (which can carry a full corporate title / brand text). Order: the username
-// stored on the run's identity (the gh login, from prefs identities), then the
-// active gh account's login resolved live, then null. The corporate `name` is
-// deliberately not a fallback.
-function resolveGithubLogin() {
-  try {
-    const out = execFileSync("gh", ["api", "user", "--jq", ".login"], {
-      encoding: "utf-8",
-      timeout: 3000,
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    if (out) return out;
-  } catch {
-    /* gh absent or not authenticated - stay silent */
-  }
-  return null;
+// Telemetry identity is the GitHub account that can read the pipeline
+// repository (usage-identity.mjs), never the git identity.name and never the
+// account gh merely has active. The server replaces it with the login pinned to
+// the ingest token, so this value is informational.
+function resolveUser(opts = {}) {
+  return resolveReportingLogin(opts).login;
 }
 
-function resolveUser(state) {
-  const fromIdentity = state.identity?.username;
-  if (typeof fromIdentity === "string" && fromIdentity.trim()) return fromIdentity.trim();
-  return resolveGithubLogin();
-}
-
-function buildEvent(state) {
+function buildEvent(state, { event = null, login = null } = {}) {
   const spend = trackerSummary(state);
   const ctx = deriveContext(state);
+  const prefs = resolvePrefs();
+  const st = runStatus(state, event);
+  const rc = reasonCode(state, st);
+  const mode = modeOf(state);
+  const phase =
+    typeof state.currentPhase === "number" && !Number.isNaN(state.currentPhase)
+      ? state.currentPhase
+      : null;
   return {
     id: runId(state),
-    t: eventTimestamp(state, spend),
-    u: resolveUser(state),
-    c: commandOf(state),
-    m: state.mode || null,
+    ev: EVENT_KINDS.includes(event) ? event : null,
+    t: eventTimestamp(state, st),
+    t0: state.startedAt || spend.startedAt || null,
+    u: login,
+    c: commandOf(state, mode),
+    m: mode,
+    tt: codeOf(state.taskType, 30),
     ap: Boolean(state.autopilot),
     lo: Boolean(state.localMode),
     in: inputType(state),
     rp: projectDigest(state.project),
-    ph: typeof state.currentPhase === "number" ? state.currentPhase : null,
-    st: state.status || null,
-    hr: state.haltReason || null,
+    ph: state._phaseOverride ?? spend.current ?? phase,
+    st,
+    hr: st === "halted" || st === "failed" ? rc : null,
+    rc,
     ri: Array.isArray(state.reviewIterations) ? state.reviewIterations.length : 0,
-    pr: Boolean(state.pr && (state.pr.url || state.pr.number)),
+    pr: hasPr(state),
+    pru: prUrlOf(state, prefs),
+    ti: titleSummary(state, prefs),
     du: durationSec(state, spend),
     tk: spend.tk,
     cost: spend.cost,
@@ -536,6 +690,7 @@ async function post(endpoint, token, event) {
         "X-Usage-Token": token,
       },
       body: JSON.stringify(event),
+      redirect: "error",
       signal: ctrl.signal,
     });
   } catch {
@@ -589,22 +744,29 @@ async function main() {
 
   if (args.phase != null) {
     const n = Number(args.phase);
-    state.currentPhase = Number.isNaN(n) ? args.phase : n;
+    if (!Number.isNaN(n)) state._phaseOverride = n;
   }
   if (args.status) state.status = args.status;
+  const kind = EVENT_KINDS.includes(args.event) ? args.event : null;
+
+  const who = resolveReportingLogin();
+  if (!who.login) {
+    process.stderr.write(`usage-report: not sent - ${who.reason}\n`);
+    if (!args.dryRun) return;
+  }
 
-  const event = buildEvent(state);
+  const event = buildEvent(state, { event: kind, login: who.login });
 
   if (args.dryRun) {
     process.stdout.write(JSON.stringify(event, null, 2) + "\n");
     return;
   }
 
-  if (isTerminalStatus(state)) appendErrorLedger(event);
+  if (event.st !== "in_progress") appendErrorLedger(event);
   await post(endpoint, token, event);
 }
 
-// Windows-safe entry-point check: compare file URLs, never string-split a path.
+// Entry-point check: compare file URLs, never string-split a path.
 const invokedDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (invokedDirectly) {
   // Exit 0 stays: usage telemetry must never be the reason a run fails, and a
@@ -629,4 +791,6 @@ export {
   trackerSummary,
   buildEvent,
   resolveUser,
+  runStatus,
+  reasonCode,
 };

package/pipeline/scripts/validate-complaint-doc.mjs

@@ -29,8 +29,8 @@
 //     section-sign / curly quotes anywhere.
 //   - Redaction leak scan: an email address or a 13-19 digit card-like run is
 //     an ERROR; a bare 11-digit run is a WARN (could be a numeric trx id); a
-//     PNR-shaped token (6-char uppercase letter+digit mix, or 6 uppercase
-//     letters right after a "PNR" keyword) is a WARN.
+//     reservation/order reference code (6-char uppercase letter+digit mix, or
+//     6 uppercase letters right after a reference-code label) is a WARN.
 //
 // Usage:
 //   node validate-complaint-doc.mjs complaints/complaints-20260810.md
@@ -79,12 +79,30 @@ const BANNED_PUNCT = [
 const EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/;
 const CARD_RE = /\b\d(?:[ -]?\d){12,18}\b/;
 const NATIONAL_ID_RE = /\b\d{11}\b/;
-// Same shape parse-complaints.sh redacts (6-char uppercase alnum with at least
-// one letter AND one digit), so a leak the parser should have caught fails
-// loudly here too. All-letter PNRs are only flaggable with context: a bare
-// 6-letter word is far too common, so those warn only right after "PNR".
-const PNR_MIXED_RE = /\b(?=[A-Z0-9]{6}\b)(?=[A-Z0-9]*\d)(?=\d*[A-Z])[A-Z0-9]{6}\b/;
-const PNR_CONTEXT_RE = /\bPNR\b[^A-Za-z0-9\n]{0,3}[A-Z]{6}\b/;
+// Same shapes parse-complaints.sh redacts (6-char uppercase alnum with at
+// least one letter AND one digit), so a leak the parser should have caught
+// fails loudly here too. An all-letter code is only flaggable with context: a
+// bare 6-letter word is far too common, so it warns only right after a
+// reference-code label (matched case-insensitively, as the parser does).
+const REF_CODE_MIXED_RE = /\b(?=[A-Z0-9]{6}\b)(?=[A-Z0-9]*\d)(?=\d*[A-Z])[A-Z0-9]{6}\b/;
+const REF_CODE_LABELLED_RE = new RegExp(
+  "(?<![\\p{L}\\p{N}])(?:" +
+    [
+      "reference (?:code|number|no)",
+      "ref (?:code|no)",
+      "(?:booking|reservation|order|confirmation) (?:code|number|no|ref|reference)",
+      "rezervasyon (?:kodu|no)",
+      "sipari[s\u015f] (?:kodu|no)",
+      "pnr",
+    ].join("|") +
+    ")[^A-Za-z0-9\\n]{0,3}([A-Za-z]{6})(?![\\p{L}\\p{N}])",
+  "giu",
+);
+
+function hasReferenceCode(line) {
+  if (REF_CODE_MIXED_RE.test(line)) return true;
+  return [...line.matchAll(REF_CODE_LABELLED_RE)].some((m) => /^[A-Z]{6}$/.test(m[1]));
+}
 
 function readInput() {
   const args = process.argv.slice(2).filter((a) => a !== "--strict");
@@ -240,9 +258,9 @@ function main() {
         `possible redaction leak: bare 11-digit run at line ${i + 1} (national-id-like; ignore if it is a numeric trx id)`,
       );
     }
-    if (PNR_MIXED_RE.test(bodyLines[i]) || PNR_CONTEXT_RE.test(bodyLines[i])) {
+    if (hasReferenceCode(bodyLines[i])) {
       warns.push(
-        `possible redaction leak: PNR-shaped token at line ${i + 1} (parse-complaints.sh should have redacted it)`,
+        `possible redaction leak: reference-code-shaped token at line ${i + 1} (parse-complaints.sh should have redacted it)`,
       );
     }
   }

package/pipeline/scripts/validate-planning.mjs

@@ -108,6 +108,12 @@ async function main() {
     if (t.acceptanceCriteria !== undefined && !Array.isArray(t.acceptanceCriteria)) {
       errors.push(`tasks[${i}].acceptanceCriteria: must be array if present`);
     }
+    if (
+      t.requirements !== undefined &&
+      !(Array.isArray(t.requirements) && t.requirements.every((r) => typeof r === "string"))
+    ) {
+      errors.push(`tasks[${i}].requirements: must be an array of requirement ids if present`);
+    }
   });
 
   // Validate dependsOn edges point to real ids and don't cycle