@mmerterden/multi-agent-pipeline 20.29.0 → 20.33.0

package/pipeline/scripts/office-prune.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * @file office-prune.mjs  -  old run logs, cleared from the restroom.
+ *
+ * A thin wrapper over prune-logs.sh, the same script /multi-agent:prune-logs
+ * runs: its dry run is the preview (which task log folders would go and the
+ * space freed). On the office's route (pruneApply) the confirmed step lists
+ * the folders again, refuses with code "changed" when they differ from the
+ * preview, and then prunes only that list (prune-logs.sh --only-from); the
+ * CLI's `apply` prunes the age directly, as /multi-agent:prune-logs does.
+ * Everything prune-logs.sh guarantees holds here: the audit trail,
+ * the metrics corpus and the task counters are never touched, the log root is
+ * refused when it is /, the home folder or a git checkout, a folder written
+ * in the last minutes is spared so a live run keeps its log, and so is a run
+ * that can still be resumed.
+ *
+ * The age is one of a fixed set of days; nothing else reaches the script.
+ *
+ * Usage:
+ *   office-prune.mjs preview <days> [--json]
+ *   office-prune.mjs apply <days> [--json]
+ *
+ * PRUNE_LOG_ROOT overrides the log root, as for prune-logs.sh.
+ *
+ * Exit: 0 printed, 1 prune-logs.sh refused, 2 usage.
+ *
+ * @module pipeline/scripts/office-prune
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const AGES = [7, 30, 90];
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAX_LISTED = 200;
+
+/** What a prune-logs.sh run printed: the folders and the space freed. */
+export function parsePrune(text) {
+  const lines = String(text).split("\n");
+  const head = lines.find((l) => /would remove|removed/i.test(l)) || "";
+  const removed = /removed (\d+)\/\d+ task log dir/.exec(head);
+  const n = Number(removed ? removed[1] : ((/(\d+) task log dir/.exec(head) || [])[1] ?? 0));
+  const size = /~(\d+(?:\.\d+)?) ?(KB|MB)/.exec(head);
+  const mb = size
+    ? size[2] === "KB"
+      ? Math.round((Number(size[1]) / 1024) * 10) / 10
+      : Number(size[1])
+    : 0;
+  const all = lines
+    .map((l) => /^\s{2}(\S(?:.*\S)?)\s*$/.exec(l))
+    .filter(Boolean)
+    .map((m) => m[1]);
+  return { count: n || all.length, freedMb: mb, folders: all.slice(0, MAX_LISTED), all };
+}
+
+// The page sees at most MAX_LISTED folders; the confirmation compares the
+// whole list.
+async function run(days, apply, env, { keepAll = false, only = null } = {}) {
+  if (!AGES.includes(days)) throw new Error(`age must be one of ${AGES.join(", ")}`);
+  const dir = only ? mkdtempSync(join(tmpdir(), "office-prune-")) : null;
+  const list = dir ? join(dir, "only.txt") : null;
+  if (list) writeFileSync(list, only.join("\n") + "\n", { mode: 0o600 });
+  const r = await spawnAsync(
+    "bash",
+    [
+      join(HERE, "prune-logs.sh"),
+      `--older-than=${days}`,
+      ...(list ? [`--only-from=${list}`] : []),
+      ...(apply ? ["--yes"] : []),
+    ],
+    { env, timeoutMs: 120_000 },
+  ).finally(() => dir && rmSync(dir, { recursive: true, force: true }));
+  if (r.status !== 0) throw new Error("prune-logs.sh refused (exit " + r.status + ")");
+  const { all, ...parsed } = parsePrune(r.stdout);
+  return {
+    contractVersion: CONTRACT_VERSION,
+    olderThanDays: days,
+    applied: apply,
+    ...parsed,
+    ...(keepAll ? { all } : {}),
+  };
+}
+
+export const prunePreview = (days, env = process.env, opts = {}) => run(days, false, env, opts);
+
+/**
+ * Prunes only what the preview showed: the folders are listed again and the
+ * prune runs only when they are the same set, and then only on that list, so
+ * a run that aged into the window or a folder that appeared since is never
+ * removed unseen.
+ */
+export async function pruneApply(days, env = process.env, expected = null) {
+  if (expected && Array.isArray(expected.all)) {
+    const now = await run(days, false, env, { keepAll: true });
+    const want = new Set(expected.all);
+    const same =
+      now.count === expected.count &&
+      now.all.length === want.size &&
+      now.all.every((f) => want.has(f));
+    if (!same) {
+      const e = new Error("the folders changed since the preview; preview again");
+      e.code = "changed";
+      throw e;
+    }
+    return run(days, true, env, { only: expected.all });
+  }
+  return run(days, true, env);
+}
+
+if (invokedDirectly(import.meta.url)) {
+  const [cmd, d, flag] = process.argv.slice(2);
+  const days = Number(d);
+  if (!["preview", "apply"].includes(cmd) || !AGES.includes(days) || (flag && flag !== "--json")) {
+    console.error(`usage: office-prune.mjs preview|apply <${AGES.join("|")}> [--json]`);
+    process.exit(2);
+  }
+  const doc = await run(days, cmd === "apply", process.env);
+  process.stdout.write(JSON.stringify(doc) + "\n");
+}

package/pipeline/scripts/office-settings.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * @file office-settings.mjs  -  the three switches the office can flip, read
+ * and changed through the same code the terminal commands use.
+ *
+ *   language  prefs.global.outputLanguage, en or tr, as /multi-agent:language
+ *             writes it (promptLanguage forced back to en in the same write),
+ *             then localize-commands.mjs swaps the installed picker text
+ *   model     the fable rung, through lib/model-rung.sh on|off
+ *   route     model routing, through lib/route-state.sh on|off; `on` keeps
+ *             the saved configuration, and anything that would widen it (a
+ *             free provider, new rules) stays in the terminal
+ *
+ * Every value is one of a fixed set; nothing else reaches a script.
+ *
+ * Usage:
+ *   office-settings.mjs [--json]
+ *   office-settings.mjs set <language|model|route> <value> [--json]
+ *
+ * MULTI_AGENT_PREFS overrides the preferences file, as for the scripts it calls.
+ *
+ * Exit: 0 printed or applied, 1 the change failed, 2 usage.
+ *
+ * @module pipeline/scripts/office-settings
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { updateJsonFileSync } from "../lib/json-file-lock.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const CHOICES = {
+  language: ["en", "tr"],
+  model: ["on", "off"],
+  route: ["on", "off"],
+};
+const STRATEGIES = ["manual", "task-fit", "cost-ceiling"];
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const prefsPath = (env) =>
+  env.MULTI_AGENT_PREFS || join(env.HOME || homedir(), ".claude", "multi-agent-preferences.json");
+
+function libScript(name) {
+  const p = join(HERE, "..", "lib", name);
+  return existsSync(p) ? p : null;
+}
+
+/** What the switches are set to now. */
+export function readSettings(env = process.env) {
+  const g = readRegularJson(prefsPath(env), {})?.global ?? {};
+  return {
+    contractVersion: CONTRACT_VERSION,
+    language: g.outputLanguage === "tr" ? "tr" : "en",
+    model: g.modelFallback?.fableEnabled === true ? "on" : "off",
+    route: g.modelRouting?.enabled === true ? "on" : "off",
+  };
+}
+
+/**
+ * The free provider chain a saved routing configuration keeps across `route
+ * off`, which `route on` brings back; null when none is saved.
+ */
+export function freeChainOf(env = process.env) {
+  const free = readRegularJson(prefsPath(env), {})?.global?.modelRouting?.free;
+  if (free?.enabled !== true) return null;
+  return { enabled: true, allowTraining: free.allowTraining === true };
+}
+
+export class SettingsError extends Error {}
+
+// route-state.sh on resets the strategy to manual unless told otherwise; the
+// saved one is passed back so `on` changes only the switch.
+function routeArgs(setting, value, env) {
+  if (setting !== "route" || value !== "on") return [];
+  const saved = readRegularJson(prefsPath(env), {})?.global?.modelRouting?.strategy;
+  return [`--strategy=${STRATEGIES.includes(saved) ? saved : "manual"}`];
+}
+
+/** Flip one switch to one of its values; returns the settings afterwards. */
+export async function applySetting(setting, value, env = process.env) {
+  if (!CHOICES[setting]?.includes(value)) throw new SettingsError(`${setting}: not a choice`);
+  if (setting === "language") {
+    const path = prefsPath(env);
+    if (!existsSync(path)) throw new SettingsError("no preferences file");
+    let written = false;
+    updateJsonFileSync(path, (cur) => {
+      if (!cur || typeof cur !== "object" || Array.isArray(cur)) return undefined;
+      written = true;
+      const global = { ...(cur.global ?? {}), promptLanguage: "en", outputLanguage: value };
+      return { ...cur, global };
+    });
+    if (!written)
+      throw new SettingsError("language: the preferences file is not an object, not written");
+    const loc = join(HERE, "localize-commands.mjs");
+    if (existsSync(loc)) {
+      const r = await spawnAsync(process.execPath, [loc, value === "tr" ? "apply" : "restore"], {
+        env,
+        timeoutMs: 30_000,
+      });
+      if (r.status !== 0)
+        throw new SettingsError(
+          `language: saved, but the command descriptions were not switched (exit ${r.status})`,
+        );
+    }
+  } else {
+    const script = libScript(setting === "model" ? "model-rung.sh" : "route-state.sh");
+    if (!script) throw new SettingsError(`${setting}: script not installed`);
+    const r = await spawnAsync("bash", [script, value, ...routeArgs(setting, value, env)], {
+      env,
+      timeoutMs: 30_000,
+    });
+    if (r.status !== 0)
+      throw new SettingsError(`${setting}: the script refused (exit ${r.status})`);
+  }
+  return readSettings(env);
+}
+
+if (invokedDirectly(import.meta.url)) {
+  const args = process.argv.slice(2).filter((a) => a !== "--json");
+  const json = process.argv.includes("--json");
+  const out = (doc) =>
+    process.stdout.write(
+      json
+        ? JSON.stringify(doc) + "\n"
+        : `language ${doc.language}, model ${doc.model}, route ${doc.route}\n`,
+    );
+  if (!args.length) out(readSettings());
+  else if (args[0] === "set" && args.length === 3) {
+    try {
+      out(await applySetting(args[1], args[2]));
+    } catch (e) {
+      console.error(String(e.message));
+      process.exit(1);
+    }
+  } else {
+    console.error("usage: office-settings.mjs [set <language|model|route> <value>] [--json]");
+    process.exit(2);
+  }
+}

package/pipeline/scripts/phase-tracker.sh

@@ -86,7 +86,7 @@ usage:
   phase-tracker.sh model  <phase_id> <model_name>
   phase-tracker.sh meta   <phase_id> <key> <value>
   phase-tracker.sh now    <phase_id> "<text>"
-  phase-tracker.sh task   <phase_id> <task_id> <pending|in_progress|completed> [--subject S] [--active-form A]
+  phase-tracker.sh task   <phase_id> <task_id> <pending|in_progress|completed|deleted> [--subject S] [--active-form A]
   phase-tracker.sh cost   <phase_id>|total
   phase-tracker.sh tiles
   phase-tracker.sh report
@@ -1427,11 +1427,11 @@ EOF
     # client behind it - sees the same list. Quiet like `now`: the host already
     # rendered the change, so this only records it.
     need_jq
-    [ "$#" -ge 3 ] || { echo "task needs <phase_id> <task_id> <status> [--subject S] [--active-form A]" >&2; exit 64; }
+    [ "$#" -ge 3 ] || { echo "task needs <phase_id> <task_id> <status|deleted> [--subject S] [--active-form A]" >&2; exit 64; }
     PID="$1"; TID="$2"; TSTATUS="$3"; shift 3
     case "$TSTATUS" in
-      pending|in_progress|completed) ;;
-      *) echo "task: status must be pending, in_progress or completed" >&2; exit 64 ;;
+      pending|in_progress|completed|deleted) ;;
+      *) echo "task: status must be pending, in_progress, completed or deleted" >&2; exit 64 ;;
     esac
     TSUBJECT=""; HAS_SUBJECT=0; TACTIVE=""; HAS_ACTIVE=0
     while [ "$#" -gt 0 ]; do
@@ -1452,6 +1452,11 @@ EOF
     fi
     EXISTS=$(printf '%s' "$state" | jq -r --arg pid "$PID" --arg tid "$TID" \
       'any(.phases[] | select(.id == $pid) | .tasks[]?; .id == $tid)')
+    # A deleted task leaves the list; one never recorded is nothing to delete.
+    if [ "$TSTATUS" = "deleted" ] && [ "$EXISTS" != "true" ]; then
+      release_state_lock
+      exit 0
+    fi
     if [ "$EXISTS" != "true" ] && [ "$HAS_SUBJECT" -eq 0 ]; then
       release_state_lock
       echo "task: a new task needs --subject" >&2
@@ -1463,7 +1468,9 @@ EOF
       --arg act "$TACTIVE" --argjson ha "$HAS_ACTIVE" '
       .phases |= map(
         if .id == $pid then
-          if any(.tasks[]?; .id == $tid) then
+          if $st == "deleted" then
+            .tasks |= map(select(.id != $tid))
+          elif any(.tasks[]?; .id == $tid) then
             .tasks |= map(if .id == $tid then
               .status = $st
               | (if $hs == 1 then .subject = $subj else . end)

package/pipeline/scripts/prune-logs.sh

@@ -23,6 +23,9 @@
 #     PRUNE_GRACE_MIN minutes (default 10) are spared, so pruning while a
 #     run is still writing its log dir cannot break resume. An explicit
 #     --task=ID bypasses the grace; PRUNE_GRACE_MIN=0 disables it.
+#   - resumable runs: a task dir whose agent-state.json status is not
+#     finished, abandoned or cancelled is spared however old it is
+#     (an unreadable status counts as resumable); --task bypasses this too.
 #
 # Usage:
 #   prune-logs.sh                       # dry-run: every idle task dir
@@ -31,6 +34,8 @@
 #   prune-logs.sh --project=my-ios-app  # only one project's task dirs
 #   prune-logs.sh --task=PROJ-123       # only one task dir
 #   prune-logs.sh --older-than=30 --yes
+#   prune-logs.sh --only-from=FILE      # only the folders FILE lists, one per
+#                                       # line as the dry run prints them
 #
 # Env:
 #   PRUNE_LOG_ROOT   override the log root (default $HOME/.claude/logs/multi-agent)
@@ -46,6 +51,7 @@ DELETE=0
 OLDER_DAYS=0
 PROJECT=""
 TASK=""
+ONLY_FROM=""
 
 usage() {
   grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'
@@ -82,6 +88,13 @@ for arg in "$@"; do
         exit 2
       fi
       ;;
+    --only-from=*)
+      ONLY_FROM="${arg#*=}"
+      if [ ! -f "$ONLY_FROM" ]; then
+        echo "prune-logs: --only-from needs a readable list file" >&2
+        exit 2
+      fi
+      ;;
     -h | --help)
       usage
       exit 0
@@ -132,6 +145,31 @@ is_reserved_name() {
   return 1
 }
 
+# A run that can still be resumed keeps its log however old it is: only a
+# finished, abandoned or cancelled run (or a dir with no recorded status) is
+# pruned; a failed run is one /multi-agent:resume picks up again. --task is
+# an explicit target and bypasses this too.
+run_status() {
+  local f="$1/agent-state.json"
+  [ -f "$f" ] || return 0
+  # A state that cannot be read is treated as resumable ("?"): pruning is
+  # the one step here that cannot be undone.
+  node -e 'try{const j=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));process.stdout.write(j&&typeof j==="object"&&typeof j.status==="string"?j.status:"")}catch{process.stdout.write("?")}' "$f" 2>/dev/null || printf '?'
+}
+is_resumable() {
+  case "$(run_status "$1")" in
+    "" | complete | completed | done | abandoned | cancelled) return 1 ;;
+  esac
+  return 0
+}
+
+# --only-from narrows the match to a confirmed list; every other check still
+# applies, so a listed folder that became active or resumable is spared.
+ONLY_LIST=""
+if [ -n "$ONLY_FROM" ]; then
+  ONLY_LIST=$'\n'"$(cat "$ONLY_FROM")"$'\n'
+fi
+
 MTIME_ARGS=()
 if [ "$OLDER_DAYS" -gt 0 ]; then
   MTIME_ARGS=(-mtime "+$OLDER_DAYS")
@@ -139,6 +177,7 @@ fi
 
 matches=()
 skipped_active=0
+skipped_resumable=0
 while IFS= read -r -d '' d; do
   base="$(basename "$d")"
   if is_reserved_name "$base"; then continue; fi
@@ -147,6 +186,12 @@ while IFS= read -r -d '' d; do
   if [ -n "$TASK" ] && [ "$base" != "$TASK" ]; then continue; fi
   # --project: the immediate parent dir name must equal the project
   if [ -n "$PROJECT" ] && [ "$(basename "$(dirname "$d")")" != "$PROJECT" ]; then continue; fi
+  if [ -n "$ONLY_FROM" ]; then
+    case "$ONLY_LIST" in
+      *$'\n'"${d#"$LOG_ROOT"/}"$'\n'*) ;;
+      *) continue ;;
+    esac
+  fi
   # Active-task grace: spare dirs a run touched in the last GRACE_MIN minutes
   # so a concurrent run keeps a resumable log dir. --task is an explicit,
   # deliberate target and bypasses the grace.
@@ -155,12 +200,16 @@ while IFS= read -r -d '' d; do
     skipped_active=$((skipped_active + 1))
     continue
   fi
+  if [ -z "$TASK" ] && is_resumable "$d"; then
+    skipped_resumable=$((skipped_resumable + 1))
+    continue
+  fi
   matches+=("$d")
 done < <(find "$LOG_ROOT" -mindepth 1 -maxdepth 2 -type d ${MTIME_ARGS[@]+"${MTIME_ARGS[@]}"} -print0 2>/dev/null)
 
 if [ "${#matches[@]}" -eq 0 ]; then
-  if [ "$skipped_active" -gt 0 ]; then
-    echo "prune-logs: only active task dirs matched (touched in the last ${GRACE_MIN}m)  -  spared, nothing to do"
+  if [ "$skipped_active" -gt 0 ] || [ "$skipped_resumable" -gt 0 ]; then
+    echo "prune-logs: only active or resumable task dirs matched ($skipped_active touched in the last ${GRACE_MIN}m, $skipped_resumable resumable)  -  spared, nothing to do"
   else
     echo "prune-logs: no task logs matched under $LOG_ROOT  -  nothing to do"
   fi
@@ -179,6 +228,7 @@ if [ "$DELETE" -eq 0 ]; then
   echo "DRY-RUN  -  would remove ${#matches[@]} task log dir(s) (frees ~${human}):"
   for d in "${matches[@]}"; do echo "  ${d#"$LOG_ROOT"/}"; done
   [ "$skipped_active" -gt 0 ] && echo "Spared $skipped_active active dir(s) touched in the last ${GRACE_MIN}m."
+  [ "$skipped_resumable" -gt 0 ] && echo "Spared $skipped_resumable run(s) that can still be resumed."
   echo "Audit trail + metrics corpus are preserved. Re-run with --yes to delete."
   exit 0
 fi
@@ -199,5 +249,6 @@ for d in "${matches[@]}"; do
 done
 spared_note=""
 [ "$skipped_active" -gt 0 ] && spared_note=", spared $skipped_active active"
+[ "$skipped_resumable" -gt 0 ] && spared_note="${spared_note}, spared $skipped_resumable resumable"
 echo "══ prune-logs: removed ${removed}/${#matches[@]} task log dir(s)${spared_note}, freed ~${human} (audit + metrics preserved) ══"
 exit 0

package/pipeline/scripts/routine-registry.mjs

@@ -24,11 +24,17 @@
 //   node routine-registry.mjs remove  --name <n> [--home <dir>]
 //
 // Exit: 0 ok, 1 error (validation / collision / not-found), 64 usage.
+//
+// listRoutines() and removeRoutine() are exported for contract-server.mjs
+// (GET /v1/routines, DELETE /v1/routines/{name}), so the panel and the
+// terminal commands run the same code; they throw RoutineError where the CLI
+// prints and exits 1.
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, renameSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { runMain } from "../lib/fatal.mjs";
 import { hostCommand } from "../lib/user-facing.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 const MAX_NAME = 40;
@@ -54,9 +60,10 @@ function parseArgs(argv) {
   return out;
 }
 
+export class RoutineError extends Error {}
+
 function fail(msg) {
-  console.error(`routine-registry: ${msg}`);
-  process.exit(1);
+  throw new RoutineError(msg);
 }
 
 function homeDir(args) {
@@ -184,8 +191,20 @@ function cmdAdd(home, args) {
   );
 }
 
-function cmdRemove(home, name) {
-  if (!name) fail("--name is required");
+/** The registered routines, as `list --json` prints them. */
+export function listRoutines(home) {
+  return getRoutines(readPrefs(home));
+}
+
+/**
+ * Remove a routine: its local-only command directory and its registry entry.
+ * A shipped command directory is refused, and so is a name that is neither
+ * registered nor on disk.
+ *
+ * @returns {{name: string, removedDir: boolean, removedEntry: boolean}}
+ */
+export function removeRoutine(home, name) {
+  if (!name || !NAME_RE.test(name) || name.length > MAX_NAME) fail(`invalid routine name: ${name}`);
   const prefs = readPrefs(home);
   const routines = getRoutines(prefs);
   const idx = routines.findIndex((r) => r.name === name);
@@ -195,12 +214,19 @@ function cmdRemove(home, name) {
     fail(`"${name}" is a shipped command, not a routine; refusing to remove`);
   }
   if (idx < 0 && !existsSync(dir)) fail(`no routine named "${name}"`);
-  if (existsSync(dir) && isLocalOnlyDir(dir)) rmSync(dir, { recursive: true, force: true });
+  const removedDir = existsSync(dir) && isLocalOnlyDir(dir);
+  if (removedDir) rmSync(dir, { recursive: true, force: true });
   if (idx >= 0) {
     routines.splice(idx, 1);
     prefs.global.routines = routines;
     writePrefs(home, prefs);
   }
+  return { name, removedDir, removedEntry: idx >= 0 };
+}
+
+function cmdRemove(home, name) {
+  if (!name) fail("--name is required");
+  removeRoutine(home, name);
   console.log(
     `routine-registry: removed "${name}" (clears from autocomplete on next session reload)`,
   );
@@ -226,4 +252,14 @@ function main() {
   }
 }
 
-runMain("routine-registry", main);
+if (invokedDirectly(import.meta.url)) {
+  runMain("routine-registry", () => {
+    try {
+      main();
+    } catch (err) {
+      if (!(err instanceof RoutineError)) throw err;
+      console.error(`routine-registry: ${err.message}`);
+      process.exit(1);
+    }
+  });
+}