@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/scripts/office-ledger.mjs

@@ -0,0 +1,409 @@
+#!/usr/bin/env node
+/**
+ * @file office-ledger.mjs  -  what the agents on this machine cost: tokens and
+ * estimated USD for today, this week (from Monday) and this month, in local
+ * time, by run, repository, model and phase.
+ *
+ * Two sources, never added together for one run:
+ *
+ *   tracker-state  the pipeline's own ledger, `tokens_in/out/cached` per phase
+ *                  in a run's tracker-state.json, priced at the phase's rung;
+ *   transcript     the host's usage records (`message.usage` on each assistant
+ *                  record, counted once per message id) in
+ *                  ~/.claude/projects/<slug>/<session>.jsonl and its
+ *                  subagents/agent-*.jsonl, priced at the model id.
+ *
+ * A run whose tracker carries tokens is counted from the tracker and its
+ * transcripts are left out, so nothing is counted twice. A run without tracker
+ * tokens is counted from the transcripts tied to it (by the session id it
+ * recorded, else by working directory and branch, as activity-snapshot.mjs
+ * ties them). A run with neither is `not-measured`: its numbers are null and
+ * it is listed by task id, never folded in as 0. A session no run claims is
+ * counted apart as outside the pipeline.
+ *
+ * Prices come from cost-table.json (_cost.mjs does the arithmetic, a cache
+ * write at 1.25 times input). `verifiedAt` in the table dates them; past
+ * PRICE_STALE_DAYS the document carries a warning naming that date. These are
+ * estimates at list price, not an invoice.
+ *
+ * Read-only. Each transcript's usage rows are kept in memory keyed by the
+ * file's size and mtime, so a second call re-reads only files that changed.
+ *
+ * Usage:
+ *   office-ledger.mjs [--json]
+ *
+ * TRANSCRIPTS_ROOT overrides ~/.claude/projects.
+ *
+ * Exit: 0 printed, 2 usage.
+ *
+ * @module pipeline/scripts/office-ledger
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { costUsd, modelRateLookup, priceUsage } from "./_cost.mjs";
+import { readJsonl } from "./_jsonl.mjs";
+import { matchRun, modelLabel, phaseAt, repoName, runExtras } from "./activity-snapshot.mjs";
+import { defaultProjectsRoot } from "./transcript-index.mjs";
+import { buildIndex } from "./runs-index.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const PRICE_STALE_DAYS = 60;
+const OUTSIDE = "outside the pipeline";
+const UNKNOWN = "unknown";
+const TABLE = JSON.parse(readFileSync(new URL("./cost-table.json", import.meta.url), "utf8"));
+const rateFor = modelRateLookup(TABLE);
+const PHASE_NAMES = Object.fromEntries(
+  JSON.parse(readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf8")).phases.map(
+    (p) => [String(p.id), p.name],
+  ),
+);
+
+/**
+ * How old the price table is. Stale past PRICE_STALE_DAYS, and stale when it
+ * carries no date at all, since nothing then says the prices were checked.
+ */
+export function priceAge(verifiedAt, now = Date.now()) {
+  const t = Date.parse(verifiedAt ?? "");
+  if (!Number.isFinite(t)) {
+    return {
+      ageDays: null,
+      stale: true,
+      warning: "cost-table.json carries no verifiedAt date; the prices may be out of date",
+    };
+  }
+  const ageDays = Math.floor((now - t) / 86_400_000);
+  const stale = ageDays > PRICE_STALE_DAYS;
+  return {
+    ageDays,
+    stale,
+    warning: stale
+      ? `cost-table.json prices were last verified ${verifiedAt} (${ageDays} days ago); the estimates may be off`
+      : null,
+  };
+}
+
+/** Local-time starts of today, this week (Monday) and this month. */
+export function windowStarts(now) {
+  const d = new Date(now);
+  const today = new Date(d.getFullYear(), d.getMonth(), d.getDate()).getTime();
+  const dow = (d.getDay() + 6) % 7;
+  const week = new Date(d.getFullYear(), d.getMonth(), d.getDate() - dow).getTime();
+  const month = new Date(d.getFullYear(), d.getMonth(), 1).getTime();
+  return { today, week, month };
+}
+
+// ---------------------------------------------------------------------------
+// Transcript usage rows
+
+const fileCache = new Map();
+
+const listDir = (dir) => {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+};
+
+/** Every session file and its subagent files changed since `since`. */
+function transcriptFiles(projectsRoot, since) {
+  const out = [];
+  for (const slug of listDir(projectsRoot)) {
+    const dir = join(projectsRoot, slug);
+    for (const f of listDir(dir)) {
+      if (!f.endsWith(".jsonl")) continue;
+      const sessionId = f.slice(0, -6);
+      const files = [join(dir, f)];
+      const sub = join(dir, sessionId, "subagents");
+      for (const s of listDir(sub)) if (/^agent-.*\.jsonl$/.test(s)) files.push(join(sub, s));
+      for (const path of files) {
+        let st;
+        try {
+          st = statSync(path);
+        } catch {
+          continue;
+        }
+        if (st.isFile() && st.mtimeMs >= since)
+          out.push({ path, sessionId, size: st.size, mtime: st.mtimeMs });
+      }
+    }
+  }
+  return out;
+}
+
+/** The usage rows of one file, and the working directory and branch it ran in. */
+async function rowsOf(file) {
+  const hit = fileCache.get(file.path);
+  if (hit && hit.size === file.size && hit.mtime === file.mtime) return hit;
+  const rows = [];
+  let cwd = null;
+  let branch = null;
+  for await (const row of readJsonl(file.path, { maxBytes: Infinity })) {
+    // Only assistant records carry usage; every other type (api-request
+    // records included) is left as soon as its type is known.
+    if (!row.record) continue;
+    const rec = row.record;
+    if (rec.type !== "assistant") {
+      if (!cwd && typeof rec.cwd === "string") cwd = rec.cwd;
+      if (!branch && typeof rec.gitBranch === "string") branch = rec.gitBranch;
+      continue;
+    }
+    if (!cwd && typeof rec.cwd === "string") cwd = rec.cwd;
+    if (!branch && typeof rec.gitBranch === "string") branch = rec.gitBranch;
+    const u = rec.message?.usage;
+    const ts = Date.parse(rec.timestamp ?? "");
+    if (!u || !Number.isFinite(ts)) continue;
+    rows.push({
+      id: typeof rec.message?.id === "string" ? rec.message.id : null,
+      ts,
+      model: typeof rec.message?.model === "string" ? rec.message.model : null,
+      usage: {
+        input_tokens: Number(u.input_tokens || 0),
+        output_tokens: Number(u.output_tokens || 0),
+        cache_read_input_tokens: Number(u.cache_read_input_tokens || 0),
+        cache_creation_input_tokens: Number(u.cache_creation_input_tokens || 0),
+      },
+    });
+  }
+  const entry = { size: file.size, mtime: file.mtime, rows, cwd, branch };
+  fileCache.set(file.path, entry);
+  return entry;
+}
+
+// ---------------------------------------------------------------------------
+// Amounts
+
+const zeroTokens = () => ({ in: 0, out: 0, cacheRead: 0, cacheWrite: 0 });
+
+function newAmount() {
+  return { tokens: null, usd: null, sources: new Set(), unpriced: 0, measured: false };
+}
+
+function addTo(a, entry) {
+  a.measured = true;
+  a.sources.add(entry.source);
+  a.tokens ??= zeroTokens();
+  for (const k of ["in", "out", "cacheRead", "cacheWrite"]) a.tokens[k] += entry.tokens[k];
+  if (entry.usd === null) a.unpriced += 1;
+  else a.usd = (a.usd ?? 0) + entry.usd;
+}
+
+function finish(a, { measuredEmpty = false } = {}) {
+  if (!a.measured) {
+    return measuredEmpty
+      ? { tokens: zeroTokens(), usd: 0, source: "transcript", unpriced: 0 }
+      : { tokens: null, usd: null, source: "not-measured", unpriced: 0 };
+  }
+  const source = a.sources.size > 1 ? "mixed" : [...a.sources][0];
+  const usd = a.usd === null ? null : Number(a.usd.toFixed(6));
+  return { tokens: a.tokens, usd, source, unpriced: a.unpriced };
+}
+
+function readTracker(run) {
+  if (!run.dir) return null;
+  for (const p of [
+    join(run.dir, "tracker-state.json"),
+    join(run.dir, "artifacts", "tracker-state.json"),
+  ]) {
+    if (existsSync(p)) return readRegularJson(p, null);
+  }
+  return null;
+}
+
+/** One priced entry per tracker phase that carries tokens. */
+function trackerEntries(run, repo) {
+  const tracker = readTracker(run);
+  const out = [];
+  for (const p of Array.isArray(tracker?.phases) ? tracker.phases : []) {
+    const tin = Math.round(Number(p.tokens_in ?? 0) || 0);
+    const tout = Math.round(Number(p.tokens_out ?? 0) || 0);
+    const tc = Math.round(Number(p.tokens_cached ?? 0) || 0);
+    if (!tin && !tout && !tc) continue;
+    const at =
+      Date.parse(p.completed_at ?? "") ||
+      Date.parse(p.started_at ?? "") ||
+      Date.parse(tracker.started_at ?? "") ||
+      null;
+    const usd = costUsd(rateFor(p.model), tin, tout, tc);
+    out.push({
+      source: "tracker-state",
+      run: run.taskId,
+      repo,
+      model: modelLabel(p.model) ?? UNKNOWN,
+      phase: p.name || PHASE_NAMES[String(p.id)] || UNKNOWN,
+      at,
+      tokens: { in: tin, out: tout, cacheRead: tc, cacheWrite: 0 },
+      usd: usd === null ? null : usd,
+    });
+  }
+  return out;
+}
+
+/** Was the run doing anything after `since`? */
+function activeSince(run, since) {
+  const times = [Date.parse(run.startedAt ?? "")];
+  for (const p of run.phases ?? [])
+    times.push(Date.parse(p.startedAt ?? ""), Date.parse(p.completedAt ?? ""));
+  return times.some((t) => Number.isFinite(t) && t >= since);
+}
+
+// ---------------------------------------------------------------------------
+// The ledger
+
+/**
+ * @param {{runs?: object[], projectsRoot?: string, now?: number, verifiedAt?: string|null}} [opts]
+ */
+export async function officeLedger(opts = {}) {
+  const now = opts.now ?? Date.now();
+  const starts = windowStarts(now);
+  const since = Math.min(starts.week, starts.month);
+  const runs = (opts.runs ?? buildIndex()).map((r) => ({ ...r, extras: runExtras(r) }));
+  const projectsRoot = opts.projectsRoot ?? defaultProjectsRoot();
+  const transcriptsReadable = existsSync(projectsRoot);
+
+  const entries = [];
+  const trackerMeasured = new Set();
+  const repoOf = (run) => run.project ?? repoName(run.extras?.projectRoot) ?? UNKNOWN;
+  for (const run of runs) {
+    const list = trackerEntries(run, repoOf(run));
+    if (list.length) trackerMeasured.add(run.taskId);
+    entries.push(...list);
+  }
+
+  const seen = new Set();
+  const transcriptMeasured = new Set();
+  for (const file of transcriptFiles(projectsRoot, since)) {
+    const { rows, cwd, branch } = await rowsOf(file);
+    const hit = matchRun(file.sessionId, cwd, branch, runs);
+    const run = hit.run;
+    if (run && trackerMeasured.has(run.taskId)) continue;
+    for (const r of rows) {
+      if (r.ts < since) continue;
+      if (r.id) {
+        if (seen.has(r.id)) continue;
+        seen.add(r.id);
+      }
+      const rate = rateFor(r.model);
+      const phaseId = run ? phaseAt(run, r.ts) : null;
+      if (run) transcriptMeasured.add(run.taskId);
+      entries.push({
+        source: "transcript",
+        run: run ? run.taskId : null,
+        repo: run ? repoOf(run) : (repoName(cwd) ?? UNKNOWN),
+        model: modelLabel(r.model) ?? UNKNOWN,
+        phase: run
+          ? phaseId === null
+            ? UNKNOWN
+            : (PHASE_NAMES[String(phaseId)] ?? String(phaseId))
+          : OUTSIDE,
+        at: r.ts,
+        tokens: {
+          in: r.usage.input_tokens,
+          out: r.usage.output_tokens,
+          cacheRead: r.usage.cache_read_input_tokens,
+          cacheWrite: r.usage.cache_creation_input_tokens,
+        },
+        usd: rate ? priceUsage(rate, r.usage) : null,
+      });
+    }
+  }
+
+  const windows = {};
+  for (const [name, start] of Object.entries(starts)) {
+    const inWindow = entries.filter((e) => e.at !== null && e.at >= start && e.at <= now);
+    const total = newAmount();
+    const outside = newAmount();
+    const groups = { byRun: new Map(), byRepo: new Map(), byModel: new Map(), byPhase: new Map() };
+    const bump = (map, key, repo, e) => {
+      if (!map.has(key)) map.set(key, { amount: newAmount(), repo });
+      addTo(map.get(key).amount, e);
+    };
+    for (const e of inWindow) {
+      addTo(total, e);
+      if (!e.run) addTo(outside, e);
+      else bump(groups.byRun, e.run, e.repo, e);
+      bump(groups.byRepo, e.repo, null, e);
+      bump(groups.byModel, e.model, null, e);
+      bump(groups.byPhase, e.phase, null, e);
+    }
+    const notMeasured = runs
+      .filter(
+        (r) =>
+          !trackerMeasured.has(r.taskId) &&
+          !transcriptMeasured.has(r.taskId) &&
+          activeSince(r, start),
+      )
+      .map((r) => r.taskId)
+      .sort();
+    for (const id of notMeasured) {
+      const run = runs.find((r) => r.taskId === id);
+      groups.byRun.set(id, { amount: newAmount(), repo: repoOf(run) });
+    }
+    const rows = (map, withRepo) =>
+      [...map.entries()]
+        .map(([key, { amount, repo }]) => ({
+          key: String(key),
+          ...(withRepo ? { repo } : {}),
+          ...finish(amount),
+        }))
+        .sort((a, b) => (b.usd ?? -1) - (a.usd ?? -1) || (a.key < b.key ? -1 : 1));
+    windows[name] = {
+      since: new Date(start).toISOString(),
+      total: finish(total, { measuredEmpty: transcriptsReadable }),
+      outsidePipeline: finish(outside, { measuredEmpty: transcriptsReadable }),
+      notMeasured,
+      byRun: rows(groups.byRun, true),
+      byRepo: rows(groups.byRepo, false),
+      byModel: rows(groups.byModel, false),
+      byPhase: rows(groups.byPhase, false),
+    };
+  }
+
+  const verifiedAt = opts.verifiedAt === undefined ? (TABLE.verifiedAt ?? null) : opts.verifiedAt;
+  const age = priceAge(verifiedAt, now);
+  return {
+    contractVersion: CONTRACT_VERSION,
+    generatedAt: new Date(now).toISOString(),
+    prices: { table: "cost-table.json", verifiedAt, ...age },
+    windows,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+
+const money = (a) => (a.usd === null ? "not measured" : `$${a.usd.toFixed(2)}`);
+
+function renderHuman(doc) {
+  const L = [];
+  for (const [name, w] of Object.entries(doc.windows)) {
+    L.push(`${name}: ${money(w.total)} (${w.total.source})`);
+    for (const r of w.byRun) L.push(`  ${r.key}: ${money(r)} (${r.source})`);
+    L.push(`  ${OUTSIDE}: ${money(w.outsidePipeline)} (${w.outsidePipeline.source})`);
+  }
+  if (doc.prices.warning) L.push(`note: ${doc.prices.warning}`);
+  L.push("Estimated at list price from cost-table.json, not an invoice.");
+  return L.join("\n") + "\n";
+}
+
+async function main(argv) {
+  if (argv.some((a) => a !== "--json")) {
+    process.stderr.write("usage: office-ledger.mjs [--json]\n");
+    return 2;
+  }
+  const doc = await officeLedger();
+  process.stdout.write(
+    argv.includes("--json") ? JSON.stringify(doc, null, 2) + "\n" : renderHuman(doc),
+  );
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  runMain("office-ledger", async () => {
+    process.exitCode = await main(process.argv.slice(2));
+  });
+}

package/pipeline/scripts/plan-coverage-gate.mjs

@@ -220,15 +220,16 @@ async function main(args) {
   const UNREADABLE = gatesOn ? 3 : 2;
   const ZERO_STEPS = gatesOn ? 1 : 2;
 
+  // Recorded attended too (gate-ledger.mjs ATTENDED_RECORDED, marked
+  // `attended: true`): lib/run-completion.mjs reads the verdict before a run
+  // may write `status: complete`.
   const finish = async (code, result, detail = {}) => {
-    if (gatesOn) {
-      await recordQuietly(
-        "plan-coverage",
-        LEDGER[result.verdict] ?? "fail",
-        { verdict: result.verdict, ...detail },
-        { repo: root, statePath: statePath ?? null },
-      );
-    }
+    await recordQuietly(
+      "plan-coverage",
+      LEDGER[result.verdict] ?? "fail",
+      { verdict: result.verdict, ...detail },
+      { repo: root, statePath: statePath ?? null },
+    );
     return code;
   };
 

package/pipeline/scripts/pre-commit-check.sh

@@ -715,6 +715,18 @@ if [ "$IS_COMMIT_HOOK" = "1" ]; then
   owned_path_gate || exit 2
 fi
 
+# Attended commit inside a pipeline run: the run's gate ledger should hold a
+# passing build and test verdict for HEAD (evidence-gate.mjs records both in an
+# attended run too). prefs.global.attendedCommitGate.mode: warn (default) says so
+# on stderr and lets the commit through, block refuses it, off skips the check.
+# Outside a run gate-ledger.mjs says nothing; any error of its own is not a
+# reason to refuse a commit a person is watching.
+if [ "$IS_COMMIT_HOOK" = "1" ] && ! ma_unattended && command -v node >/dev/null 2>&1; then
+  printf '%s' "${HOOK_INPUT:-}" \
+    | node "$PRE_COMMIT_DIR/gate-ledger.mjs" evidence --repo "${REPO_ROOT:-$PWD}" --hook-input - >/dev/null
+  [ "$?" = "4" ] && exit 2
+fi
+
 # Unattended commit: the verification gates must have passed for this HEAD.
 # The environment is the hook's own, inherited from the process the launcher
 # started, so the run cannot talk its way past it by editing its state. An

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);
+    }
+  });
+}