@mmerterden/multi-agent-pipeline 20.30.0 → 20.33.0

package/pipeline/scripts/system-status.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+/**
+ * @file system-status.mjs  -  what this machine has left: CPU load, memory,
+ * free disk, and what the pipeline itself is using (its sessions, the toolkit
+ * server, the log folder).
+ *
+ * Numbers only. No path, process argument, user name or host name leaves this
+ * script: a process is counted by what it is (a Claude Code session, the
+ * toolkit server), never listed, and a folder is reported by its size alone.
+ *
+ * CPU use is measured over a short window from two samples of the per-core
+ * counters, so a call takes about SAMPLE_MS. Folder sizes come from `du -sk`
+ * under a deadline; a folder too large to measure in time is null, not 0.
+ *
+ * Usage:
+ *   system-status.mjs [--json]
+ *
+ * LOGS_ROOT overrides ~/.claude/logs/multi-agent.
+ *
+ * Exit: 0 printed, 2 usage.
+ *
+ * @module pipeline/scripts/system-status
+ */
+
+import { statfsSync } from "node:fs";
+import { cpus, freemem, homedir, loadavg, totalmem } from "node:os";
+import { join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const SAMPLE_MS = 250;
+/** Free disk below this share of the disk turns the panel red. */
+export const DISK_LOW = 0.1;
+const DU_TIMEOUT_MS = 3000;
+const MB = 1024 * 1024;
+
+const logsRoot = (env) => env.LOGS_ROOT || join(homedir(), ".claude", "logs", "multi-agent");
+
+function cpuTimes() {
+  return cpus().map((c) => {
+    const t = c.times;
+    return {
+      busy: t.user + t.nice + t.sys + t.irq,
+      total: t.user + t.nice + t.sys + t.irq + t.idle,
+    };
+  });
+}
+
+/** Busy share of the CPU between two samples, 0..1, or null without counters. */
+export function cpuShare(a, b) {
+  let busy = 0;
+  let total = 0;
+  for (let i = 0; i < Math.min(a.length, b.length); i++) {
+    busy += b[i].busy - a[i].busy;
+    total += b[i].total - a[i].total;
+  }
+  return total > 0 ? Math.min(1, Math.max(0, busy / total)) : null;
+}
+
+function disk(path) {
+  try {
+    const s = statfsSync(path);
+    const total = s.blocks * s.bsize;
+    const free = s.bavail * s.bsize;
+    return { totalMb: Math.round(total / MB), freeMb: Math.round(free / MB), device: s.type };
+  } catch {
+    return null;
+  }
+}
+
+// The log folder's size changes slowly and du over a large tree is the
+// slowest part of the answer, so one measurement serves a minute of polls.
+const FOLDER_TTL_MS = 60_000;
+const folderCache = new Map();
+async function folderMb(path) {
+  const hit = folderCache.get(path);
+  if (hit && Date.now() - hit.at < FOLDER_TTL_MS) return hit.mb;
+  const r = await spawnAsync("du", ["-sk", path], { timeoutMs: DU_TIMEOUT_MS });
+  const kb = r.status === 0 ? Number(r.stdout.split(/\s+/)[0]) : NaN;
+  const mb = Number.isFinite(kb) ? Math.round(kb / 1024) : null;
+  folderCache.set(path, { at: Date.now(), mb });
+  return mb;
+}
+
+/**
+ * Pipeline processes from `ps`, counted and summed, never listed. A Claude Code
+ * session is a process whose executable is `claude`; the toolkit server is a
+ * node, npx or npm process whose command line names multi-agent-toolkit.
+ */
+export function countProcesses(psText) {
+  const out = { sessions: 0, toolkit: 0, rssMb: 0 };
+  for (const line of String(psText).split("\n")) {
+    const m = /^\s*(\d+)\s+(\S+)(?:\s+(.*))?$/.exec(line);
+    if (!m) continue;
+    const rssKb = Number(m[1]);
+    const exe = m[2].split("/").pop();
+    const rest = m[3] || "";
+    if (exe === "claude") out.sessions++;
+    // The server runs under node or npx; a grep or tail naming it is not it.
+    else if (/^(node|npx|npm)$/.test(exe) && /multi-agent-toolkit/.test(rest)) out.toolkit++;
+    else continue;
+    out.rssMb += rssKb / 1024;
+  }
+  out.rssMb = Math.round(out.rssMb);
+  return out;
+}
+
+async function processes() {
+  const r = await spawnAsync("ps", ["-A", "-o", "rss=", "-o", "args="], {
+    timeoutMs: 2000,
+    maxBytes: 8 * MB,
+  });
+  return r.status === 0 ? countProcesses(r.stdout) : null;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Bytes macOS can hand out right away: free pages plus the inactive,
+ * speculative and purgeable ones it reclaims on demand. os.freemem() counts
+ * free pages only, which reads as nearly full on any Mac that has run a while.
+ */
+export function availableFromVmStat(text) {
+  const page = Number((/page size of (\d+) bytes/.exec(text) || [])[1]);
+  if (!page) return null;
+  const pages = (name) => Number((new RegExp(`Pages ${name}:\\s+(\\d+)`).exec(text) || [])[1] || 0);
+  const n = pages("free") + pages("inactive") + pages("speculative") + pages("purgeable");
+  return n ? n * page : null;
+}
+
+async function availableMemory() {
+  if (process.platform !== "darwin") return freemem();
+  const r = await spawnAsync("vm_stat", [], { timeoutMs: 2000, maxBytes: MB });
+  return (r.status === 0 && availableFromVmStat(r.stdout)) || freemem();
+}
+
+export async function systemStatus(env = process.env) {
+  const a = cpuTimes();
+  await sleep(SAMPLE_MS);
+  const b = cpuTimes();
+  const cores = b.length;
+  const [l1, l5, l15] = loadavg();
+  const memTotal = totalmem();
+  const memFree = await availableMemory();
+  const root = logsRoot(env);
+  const home = disk(homedir());
+  const logs = disk(root);
+  const sameDisk = Boolean(
+    home && logs && home.device === logs.device && home.totalMb === logs.totalMb,
+  );
+  const strip = (d) => (d ? { totalMb: d.totalMb, freeMb: d.freeMb } : null);
+  const share = home && home.totalMb ? home.freeMb / home.totalMb : null;
+  const cpuUse = cpuShare(a, b);
+  const [procs, logsMb] = await Promise.all([processes(), folderMb(root)]);
+  return {
+    contractVersion: CONTRACT_VERSION,
+    generatedAt: new Date().toISOString(),
+    cpu: {
+      cores,
+      usage: cpuUse === null ? null : Math.round(cpuUse * 100) / 100,
+      load: [l1, l5, l15].map((x) => Math.round(x * 100) / 100),
+    },
+    memory: {
+      totalMb: Math.round(memTotal / MB),
+      usedMb: Math.round((memTotal - memFree) / MB),
+    },
+    disk: {
+      home: strip(home),
+      logs: sameDisk ? null : strip(logs),
+    },
+    pipeline: {
+      ...(procs ?? { sessions: null, toolkit: null, rssMb: null }),
+      logsMb,
+    },
+    warnings: [
+      ...(share !== null && share < DISK_LOW ? ["disk-low"] : []),
+      ...(cores && l5 > cores ? ["cpu-busy"] : []),
+    ],
+  };
+}
+
+if (invokedDirectly(import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.some((a) => a !== "--json")) {
+    console.error("usage: system-status.mjs [--json]");
+    process.exit(2);
+  }
+  const doc = await systemStatus();
+  process.stdout.write(
+    args.includes("--json")
+      ? JSON.stringify(doc) + "\n"
+      : `cpu ${doc.cpu.usage ?? "?"} of ${doc.cpu.cores} cores, memory ${doc.memory.usedMb}/${doc.memory.totalMb} MB, disk free ${doc.disk.home?.freeMb ?? "?"} MB\n`,
+  );
+}

package/pipeline/scripts/task-mirror.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * @file task-mirror.mjs  -  PostToolUse hook: the host's task list, mirrored
+ * into the run's tracker without the agent having to remember it.
+ *
+ * tracker-contract.md asks for one `phase-tracker.sh task` call per native
+ * TaskCreate / TaskUpdate so readers that are not the host (runs-index.mjs and
+ * the office panel behind the contract server) see the same list under the
+ * same phase. That call is an instruction, and an instruction can be skipped;
+ * this hook makes the mirror a side effect of the native call itself.
+ *
+ * Which run: _active-run.mjs findActiveRun, and only a run bound to this
+ * session by `sessionId` or `hostSessionId`, the same rule run-stop-guard.mjs
+ * uses. No bound run: nothing is written.
+ *
+ * What is mirrored:
+ *   - TaskCreate, unless its subject is a phase tile ("Phase 2 Dev"): the phase
+ *     list already is the state file (tracker-contract.md, "Mirroring").
+ *   - TaskUpdate of a task already mirrored, with its new status, subject or
+ *     active form. An update of a phase tile or of a task this hook never saw
+ *     is left alone.
+ * The task goes under the phase in progress when it was created.
+ *
+ * Exits 0 on every path and prints nothing: a mirror, not a gate. A failure is
+ * written to the hook failure log.
+ */
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { findActiveRun, logHookFailure, runDirOf } from "./_active-run.mjs";
+
+const HOOK = "task-mirror";
+const SESSION_BOUND = new Set(["session", "host-session"]);
+const STATUSES = new Set(["pending", "in_progress", "completed"]);
+const TILE = /^Phase \d+\b/;
+const MAX_INPUT = 256 * 1024;
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** The id TaskCreate returned, from its structured result or its text. */
+export function createdId(response) {
+  if (!response) return null;
+  if (typeof response === "object") {
+    const id = response.task?.id ?? response.id ?? response.taskId;
+    if (id !== undefined && id !== null && String(id) !== "") return String(id);
+  }
+  const text = typeof response === "string" ? response : JSON.stringify(response);
+  const m = /Task #(\w+)/.exec(text) || /"id"\s*:\s*"?(\w+)/.exec(text);
+  return m ? m[1] : null;
+}
+
+/**
+ * The `phase-tracker.sh task` arguments one native call maps to, or null when
+ * the call is not mirrored.
+ *
+ * @param {object} payload  the PostToolUse hook JSON
+ * @param {object} tracker  the run's tracker-state.json
+ */
+export function mirrorArgs(payload, tracker) {
+  const tool = payload?.tool_name;
+  const input = payload?.tool_input || {};
+  const phases = Array.isArray(tracker?.phases) ? tracker.phases : [];
+  if (tool === "TaskCreate") {
+    const subject = typeof input.subject === "string" ? input.subject.trim() : "";
+    if (!subject || TILE.test(subject)) return null;
+    const id = createdId(payload.tool_response);
+    // Between two phases the task belongs to the one about to start: the
+    // first pending phase after the last finished one, else the last phase.
+    const lastDone = phases.findLastIndex((p) => ["completed", "skipped"].includes(p.status));
+    const phase =
+      phases.find((p) => p.status === "in_progress") ??
+      phases.slice(lastDone + 1).find((p) => p.status === "pending") ??
+      phases.at(-1);
+    if (!id || !phase) return null;
+    const args = ["task", String(phase.id), id, "pending", "--subject", subject];
+    if (typeof input.activeForm === "string" && input.activeForm)
+      args.push("--active-form", input.activeForm);
+    return args;
+  }
+  if (tool === "TaskUpdate") {
+    const id = input.taskId === undefined || input.taskId === null ? "" : String(input.taskId);
+    if (!id) return null;
+    // A resumed run in a new session can number its tasks from 1 again, so
+    // the phase in progress is asked first, then the newest phases back.
+    const ordered = [...phases.filter((p) => p.status === "in_progress"), ...[...phases].reverse()];
+    const phase = ordered.find((p) => (p.tasks || []).some((t) => String(t.id) === id));
+    if (!phase) return null;
+    const task = phase.tasks.find((t) => String(t.id) === id);
+    if (input.status === "deleted") return ["task", String(phase.id), id, "deleted"];
+    const status = STATUSES.has(input.status) ? input.status : task.status;
+    if (!STATUSES.has(status)) return null;
+    const args = ["task", String(phase.id), id, status];
+    if (typeof input.subject === "string" && input.subject && !TILE.test(input.subject))
+      args.push("--subject", input.subject);
+    if (typeof input.activeForm === "string" && input.activeForm)
+      args.push("--active-form", input.activeForm);
+    return args;
+  }
+  return null;
+}
+
+export function mirror(payload, env = process.env) {
+  if (!payload || !["TaskCreate", "TaskUpdate"].includes(payload.tool_name)) 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) || !run.state?.taskId) return null;
+  // The tracker it read is the one it writes: phase-tracker.sh would pick
+  // the newest folder for the task id, which another copy could be.
+  const trackerPath = join(runDirOf(run.statePath), "tracker-state.json");
+  let tracker;
+  try {
+    tracker = JSON.parse(readFileSync(trackerPath, "utf8"));
+  } catch {
+    return null;
+  }
+  const args = mirrorArgs(payload, tracker);
+  if (!args) return null;
+  const r = spawnSync("bash", [join(HERE, "phase-tracker.sh"), ...args], {
+    env: {
+      ...env,
+      MULTI_AGENT_TASK_ID: run.state.taskId,
+      TRACKER_FILE: trackerPath,
+      TRACKER_QUIET: "1",
+    },
+    encoding: "utf8",
+    timeout: 8000,
+  });
+  if (r.status !== 0) logHookFailure(HOOK, `phase-tracker task exited ${r.status}`, env);
+  return args;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  try {
+    const raw = readFileSync(0, "utf8").slice(0, MAX_INPUT);
+    mirror(JSON.parse(raw));
+  } catch (e) {
+    try {
+      logHookFailure(HOOK, String(e?.message || e).slice(0, 200));
+    } catch {
+      /* the log is best effort */
+    }
+  }
+  process.exit(0);
+}

package/pipeline/scripts/task-mirror.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# task-mirror.sh  -  PostToolUse hook (TaskCreate|TaskUpdate) for the pipeline.
+#
+# Mirrors the host's native task list into the run's tracker-state.json, so the
+# office panel and every other reader see what the task widget shows. The
+# logic is in task-mirror.mjs; this wrapper exists because every hook the
+# pipeline registers is a `bash "$HOME/.<host>/scripts/<name>"` command.
+#
+# Exits 0 on every path and prints nothing: a missing node or any internal
+# error means no mirror, never a blocked tool call.
+
+set -u
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+CORE="$HERE/task-mirror.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/toolkit-tools.mjs

@@ -29,8 +29,9 @@
  * MCP_TOOLKIT_URL_POLICY=strict, set after the registration's own environment
  * so neither can be overridden. A registration whose package spec has no exact
  * version (bare, a dist-tag such as `@latest`, or a range) is pinned to
- * MA_TOOLKIT_VERSION or prefs.global.office.toolkitVersion, and refused when
- * neither is set.
+ * MA_TOOLKIT_VERSION, else prefs.global.office.toolkitVersion, else the
+ * version the release ships beside the office page (office/toolkit.json, the
+ * one it was checked against), and refused when none is set.
  *
  * No tool that is not read-only is allowed today. Opening one up means routing
  * it through the server's two-step confirm, never a direct call.
@@ -58,7 +59,7 @@
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { clearTimeout, setTimeout } from "node:timers";
 import { createRedactor } from "./transcript-index.mjs";
 import { runMain } from "../lib/fatal.mjs";
@@ -229,12 +230,15 @@ export function unpinned(entry) {
 /**
  * The registration with every unpinned spec set to `<name>@<version>`, or
  * null when it is unpinned and no exact version is known. The version comes
- * from MA_TOOLKIT_VERSION, else prefs.global.office.toolkitVersion.
+ * from MA_TOOLKIT_VERSION, else prefs.global.office.toolkitVersion, else
+ * office/toolkit.json beside the page (MA_OFFICE_PAGE's directory, or the
+ * office directory next to this script's).
  */
 export function pinnedEntry(entry, env = process.env) {
   if (!unpinned(entry)) return entry;
   const prefs = readJson(join(env.HOME || homedir(), ".claude", "multi-agent-preferences.json"));
-  const version = env.MA_TOOLKIT_VERSION || prefs?.global?.office?.toolkitVersion;
+  const version =
+    env.MA_TOOLKIT_VERSION || prefs?.global?.office?.toolkitVersion || shippedToolkitVersion(env);
   if (typeof version !== "string" || !SEMVER.test(version)) return null;
   const loose = new Set(packageSpecs(entry).filter((s) => !SEMVER.test(splitSpec(s)[1] ?? "")));
   const pin = (a) => {
@@ -248,6 +252,24 @@ export function pinnedEntry(entry, env = process.env) {
   return { ...entry, args: Array.isArray(entry.args) ? entry.args.map(pin) : entry.args };
 }
 
+/** The toolkit version the release ships beside the office page, or undefined. */
+export function shippedToolkitVersion(env = process.env) {
+  const dir = env.MA_OFFICE_PAGE
+    ? dirname(env.MA_OFFICE_PAGE)
+    : join(import.meta.dirname, "..", "office");
+  const v = readJson(join(dir, "toolkit.json"))?.toolkitVersion;
+  return typeof v === "string" && SEMVER.test(v) ? v : undefined;
+}
+
+/** The exact toolkit version the Tools window starts, or null when none is known. */
+export function activeToolkitVersion(env = process.env) {
+  const registered = toolkitEntry(env);
+  const entry = registered ? pinnedEntry(registered, env) : null;
+  const spec = entry ? packageSpecs(entry)[0] : null;
+  const v = spec ? splitSpec(spec)[1] : null;
+  return typeof v === "string" && SEMVER.test(v) ? v : null;
+}
+
 /** read, low or high, from the tool's own annotations. */
 export function riskOf(tool) {
   const a = tool?.annotations ?? {};
@@ -386,7 +408,7 @@ export function createToolkitClient({ env = process.env } = {}) {
       return Promise.reject(
         new ToolError(
           "unpinned",
-          "the toolkit registration starts a package without an exact version; register a pinned version or set prefs.global.office.toolkitVersion",
+          "no exact toolkit version is known: the release ships it in office/toolkit.json beside the page, which reinstalling (node install.js) restores; MA_TOOLKIT_VERSION or prefs.global.office.toolkitVersion override it",
         ),
       );
     }
@@ -565,7 +587,11 @@ async function main(argv) {
   try {
     let out;
     if (cmd === "list" && !name) {
-      out = { contractVersion: CONTRACT_VERSION, tools: await client.listTools() };
+      out = {
+        contractVersion: CONTRACT_VERSION,
+        version: activeToolkitVersion(),
+        tools: await client.listTools(),
+      };
     } else if (cmd === "call" && name) {
       let args = {};
       if (raw !== undefined) {

package/pipeline/scripts/transcript-index.mjs

@@ -139,9 +139,12 @@ const TOKEN_CHAR = /[A-Za-z0-9_\-./+=:@~%]/;
  * `text` cut to `limit` characters, backed off to the start of a token that
  * the cut would split, so no half-credential survives on the boundary.
  */
+// The " ..." ending counts toward the limit, so a cut text is never longer
+// than the field that holds it.
 function cut(text, limit) {
   if (text.length <= limit) return text;
-  let end = limit;
+  if (limit < 5) return text.slice(0, limit);
+  let end = limit - 4;
   while (end > 0 && TOKEN_CHAR.test(text[end]) && TOKEN_CHAR.test(text[end - 1])) end--;
   return `${text.slice(0, end).trimEnd()} ...`;
 }