foldrun 2.6.0 → 2.8.0

package/src/commands.mjs

@@ -1889,13 +1889,23 @@ async function probeCmd(modelArg) {
 async function runEvals(name, flags = {}) {
   assertCredentials();
   await useGallery(flags);
-  const { listEvals, runEval } = await core();
+  const { listEvals, runEval, workspaceDir } = await core();
   const T = "default";
   const P = "workspace";
+  // Where this workspace's evals are, for telling a grader by its file when
+  // the installed core predates graders — the workspace chosen, not the cwd.
+  const evalsDir = path.join(workspaceDir(T, P), "evals");
   // An `inputs: true` file is a flow's saved inputs, not a test: it has
   // nothing to assert, so it is never run as one (see evals.md).
-  const all = listEvals(T, P).filter((e) => (!name || e.name === name) && !e.inputs);
+  const named = listEvals(T, P).filter((e) => (!name || e.name === name) && !e.inputs);
+  // A grader (`trigger: runs`) grades real runs; it has no cases to run here.
+  const all = named.filter((e) => !isGrader(e, evalsDir));
+  for (const g of named.filter((e) => isGrader(e, evalsDir))) {
+    console.log(`\n  ${c.bold(g.name)} ${c.dim(`grades live runs — \`foldrun eval grades ${g.name} --to <workspace>\` shows what it found`)}`);
+  }
   if (all.length === 0) {
+    // Only graders here (or the one named is a grader): listed above, nothing to run — not an error.
+    if (named.length) return 0;
     if (name && listEvals(T, P).some((e) => e.name === name)) {
       throw new Error(`"${name}" is a file of saved inputs, not an eval — \`foldrun invoke <flow> --inputs <set>\` runs one`);
     }
@@ -5581,16 +5591,12 @@ async function billingCmd(flags) {
   const entries = body.entries ?? [];
 
   console.log(`\n  ${balance > 0 ? c.green("✓") : c.red("✗")} balance ${c.bold(`$${balance.toFixed(2)}`)}  ${c.dim(body.enabled ? "billing on" : "billing off — nothing is charged on this install")}`);
-  if (body.enabled && balance <= 0) {
-    console.log(`  ${c.red("the wallet is empty")} ${c.dim("— the account is in overdraft; top it up before anything is expected to run")}`);
-  }
-
-  // What the platform is waiving says more than the balance does: a run
-  // charged $0 with models waived is a run whose model credit is being
-  // absorbed, and that is the state people mistake for "it is working".
-  const waived = [...new Set(entries.flatMap((e) => e.waived ?? []))];
-  if (waived.length) {
-    console.log(`  ${c.amber("⏸")} ${c.dim(`${waived.join(", ")} ${waived.length === 1 ? "is" : "are"} being waived on recent runs — those lines are charged $0`)}`);
+  // What the account should be told — an empty wallet, an overdraft, a
+  // waiver — as the platform words it: it knows the gate, the overdraft and
+  // the waivers; the numbers here do not say enough to guess.
+  for (const notice of Array.isArray(body.notices) ? body.notices : []) {
+    const empty = /wallet is empty/.test(notice);
+    console.log(`  ${empty ? c.red("✗") : c.amber("⏸")} ${empty ? notice : c.dim(notice)}`);
   }
 
   const limit = Number(flags.limit) > 0 ? Math.floor(Number(flags.limit)) : 15;
@@ -6324,6 +6330,57 @@ function issueDoctor(issue) {
  *  on one — the dashboard's Issues page and its buttons, same route.
  *  `foldrun issues doctor <id>` is the card's Doctor: the run doctor on the
  *  issue's newest run, in that run's workspace. */
+/**
+ * `foldrun inbox` — what is waiting on you across your workspaces (GET
+ * /api/me/inbox): gates, questions agents ask, open issues, proposed fixes,
+ * your runs that went wrong this week. Assigned to you and started by you by
+ * default; `--team` for the rest of what waits in your workspaces, `--all`
+ * for every bucket, `--dismissed` for what you set aside, `--kind
+ * approval|question|issue|proposal|run`, `--unread`, `--json`. `read`,
+ * `unread`, `dismiss` (set aside — it still waits where it lives) and
+ * `restore` take item ids. A key reads the inbox of the person who minted it.
+ * The dashboard's Inbox. Exit 1 when anything assigned to you is unread.
+ */
+async function inboxCmd(positional, flags) {
+  const url = platformFor(flags, "inbox");
+  const [verb, ...ids] = positional;
+  const ACTIONS = { read: "read", unread: "unread", dismiss: "dismiss", restore: "restore" };
+  if (verb) {
+    const action = ACTIONS[verb];
+    if (!action) throw new Error(`\`foldrun inbox\` lists what waits on you; its verbs are read, unread, dismiss and restore — not ${verb}`);
+    if (!ids.length) throw new Error(`\`foldrun inbox ${verb} <id>…\` — the ids are the first column of \`foldrun inbox\``);
+    await remoteCall(url, flags, "/api/me/inbox", { method: "POST", body: JSON.stringify({ ids, action }) });
+    console.log(`\n  ${c.green(action === "dismiss" ? "set aside" : action === "restore" ? "put back" : `marked ${action}`)} ${ids.length} item${ids.length === 1 ? "" : "s"}\n`);
+    return 0;
+  }
+  const q = new URLSearchParams();
+  if (flags.all === true) q.set("bucket", "all");
+  else if (flags.team === true) q.set("bucket", "team");
+  else if (flags.started === true) q.set("bucket", "started");
+  else if (flags.mine === true) q.set("bucket", "mine");
+  if (flags.dismissed === true) q.set("dismissed", "1");
+  if (typeof flags.kind === "string") q.set("kind", flags.kind);
+  if (typeof flags.workspace === "string") q.set("workspace", flags.workspace);
+  const view = await remoteCall(url, flags, `/api/me/inbox${q.size ? `?${q}` : ""}`);
+  const items = (view.items ?? []).filter((i) => (flags.unread === true ? !i.read : true));
+  if (flags.json) {
+    console.log(JSON.stringify({ ...view, items }, null, 2));
+    return view.counts?.unread ? 1 : 0;
+  }
+  const k = view.counts ?? {};
+  console.log(`\n  ${c.bold(`inbox of ${view.person}`)} ${c.dim(`· for you ${k.mine ?? 0} · started by you ${k.started ?? 0} · team ${k.team ?? 0} · ${k.unread ?? 0} unread`)}`);
+  if (!items.length) console.log(`\n  ${c.dim(flags.dismissed ? "nothing set aside" : "nothing waiting")}`);
+  const BUCKET = { mine: "for you", started: "yours", team: "team" };
+  for (const i of items) {
+    const dot = i.read ? " " : c.amber("•");
+    console.log(`\n  ${dot} ${c.bold(i.title)} ${c.dim(`· ${i.kind} · ${BUCKET[i.bucket] ?? i.bucket} · ${i.workspace} · ${String(i.at).slice(0, 16).replace("T", " ")}`)}`);
+    if (i.detail) console.log(`    ${i.detail}`);
+    console.log(`    ${c.dim(`${i.id} — ${i.why}`)}`);
+  }
+  console.log("");
+  return k.unread ? 1 : 0;
+}
+
 async function issuesCmd(positional, flags, layout) {
   const url = platformFor(flags, "issues");
   const [verb, id] = positional;
@@ -8189,14 +8246,22 @@ function ownSandboxOf(agent) {
   return /** @type {{ sandbox?: string } | undefined} */ (agent)?.sandbox === "own";
 }
 
-/** An agent file's frontmatter as a run reads it (core's configMatter, which
- *  folds the job blocks), from its text. {} when it does not parse. */
+/** An agent file's frontmatter as a run reads it, from its text. A run folds
+ *  the four job blocks' keys up to the top (core's configMatter, kept private
+ *  — not in @foldrun/core's publicApi), so `guardrail: { sandbox: own }` reads
+ *  as `sandbox: own`. The CLI reads only two foldable keys off this — `sandbox`
+ *  and `network`, both in an agent's `guardrail:` block — so it lifts just
+ *  those, the same way a run does: a top-level value wins, else the block's is
+ *  lifted. {} when it does not parse. */
 async function effectiveFront(raw) {
   const { readFrontmatter } = await core();
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "foldrun-front-"));
   try {
     fs.writeFileSync(path.join(dir, "agent.md"), raw);
-    return readFrontmatter(path.join(dir, "agent.md")) ?? {};
+    const front = /** @type {Record<string, any>} */ (readFrontmatter(path.join(dir, "agent.md")) ?? {});
+    const guardrail = front.guardrail && typeof front.guardrail === "object" ? front.guardrail : {};
+    for (const key of ["sandbox", "network"]) if (!(key in front) && key in guardrail) front[key] = guardrail[key];
+    return front;
   } catch {
     return {};
   } finally {
@@ -8443,10 +8508,12 @@ async function agentNetworkCmd(positional, flags, layout) {
   }
   const resolve = (files) =>
     inTree(desk, files, async (dir) => {
-      const { listAgents, readFrontmatter } = await core();
+      const { listAgents } = await core();
+      // The folded view a run reads: `network` set inside a `guardrail:` block
+      // counts the same as a top-level one (effectiveFront lifts it).
       return {
         info: listAgents("default", "workspace").find((a) => a.name === name),
-        own: net.readNetwork(readFrontmatter(path.join(dir, rel)).network).setting,
+        own: net.readNetwork((await effectiveFront(fs.readFileSync(path.join(dir, rel), "utf8"))).network).setting,
       };
     });
   const show = (info) => {
@@ -8717,10 +8784,16 @@ async function remoteEvalsCmd(name, flags, layout) {
     if (!name) throw new Error("--run reads one eval's run — name it: `foldrun eval <name> --to <ws> --run <id>`");
   }
   const { evals = [] } = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals`);
-  const all = evals.filter((e) => !name || e.name === name);
-  if (!all.length) {
+  const named = evals.filter((e) => !name || e.name === name);
+  if (!named.length) {
     throw new Error(name ? `no eval "${name}" in ${ws} — it has ${evals.map((e) => e.name).join(", ") || "none"}` : `no evals in ${ws} on ${url}`);
   }
+  // Graders grade real runs; `eval grades` shows what they found.
+  const all = named.filter((e) => e.trigger !== "runs");
+  for (const g of named.filter((e) => e.trigger === "runs")) {
+    console.log(`\n  ${c.bold(g.name)} ${c.dim(`grades live runs — \`foldrun eval grades ${g.name} --to ${ws}\``)}`);
+  }
+  if (!all.length) return 0;
   let failed = 0;
   for (const info of all) {
     console.log(`\n  ${c.bold(info.name)} ${c.dim(`${info.cases?.length ?? "?"} cases · ${ws}`)}`);
@@ -8761,6 +8834,341 @@ async function remoteEvalsCmd(name, flags, layout) {
   return failed ? 1 : 0;
 }
 
+/** Is this eval a grader (`trigger: runs`)? A core that predates graders
+ *  reads the trigger as `deploy`, so the file is asked too. */
+function isGrader(info, dir) {
+  if (info.trigger === "runs") return true;
+  try {
+    const raw = fs.readFileSync(path.join(dir, info.file), "utf8");
+    const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw)?.[1] ?? "";
+    return /^trigger:\s*["']?runs["']?\s*$/m.test(front);
+  } catch {
+    return false;
+  }
+}
+
+/** One grade, the way `eval grades` and `eval grade` print it. */
+function printGrade(g) {
+  const mark = g.status === "pass" ? c.green("✓ pass") : g.status === "fail" ? c.red("✗ fail") : c.amber("? not decided");
+  const miss = (g.checks ?? []).find((x) => !x.passed);
+  const why = miss ? ` — ${miss.name}: ${miss.error ?? (miss.assertions ?? []).find((a) => !a.passed)?.detail ?? "failed"}` : "";
+  console.log(`  ${mark}  ${c.bold(g.runId)} ${c.dim(String(g.at ?? "").slice(0, 16).replace("T", " "))}${why}`);
+}
+
+/**
+ * `foldrun eval grades <eval> --to <workspace>` — what a grader (an eval with
+ * `trigger: runs`) found in the real runs it graded: the pass rate over
+ * `--days` (default 30), then each graded run, newest first (`--status
+ * fail` for the failures alone, `--limit`). GET …/evals/<e>/grades — the
+ * Evals page's grader card. Exit 1 when any graded run in the window failed.
+ */
+async function evalGradesCmd(name, flags, layout) {
+  if (!name) throw new Error("which grader? `foldrun eval grades <eval> --to <workspace>`");
+  const url = platformFor(flags, "eval grades");
+  const ws = platformWorkspace(flags, layout, `eval grades ${name}`);
+  const q = new URLSearchParams();
+  if (flags.days !== undefined) q.set("days", String(flags.days));
+  if (typeof flags.status === "string") q.set("status", flags.status);
+  if (flags.limit !== undefined) q.set("limit", String(flags.limit));
+  const r = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals/${enc(name)}/grades${q.size ? `?${q}` : ""}`);
+  if (flags.json) {
+    console.log(JSON.stringify(r, null, 2));
+    return r.summary?.failed ? 1 : 0;
+  }
+  const s = r.summary ?? {};
+  const rate = s.rate === null || s.rate === undefined ? "—" : `${Math.round(s.rate * 100)}%`;
+  console.log(`\n  ${c.bold(r.eval)} ${c.dim(`grades ${r.sample}% of ${r.flow ? `flow ${r.flow}` : `agent ${r.agent}`} runs · ${ws}`)}`);
+  console.log(`  ${rate} passing over ${r.days} days — ${s.graded ?? 0} graded, ${s.passed ?? 0} passed, ${s.failed ?? 0} failed${s.errors ? `, ${s.errors} not decided` : ""} · judges $${Number(s.costUsd ?? 0).toFixed(4)}\n`);
+  for (const g of r.grades ?? []) printGrade(g);
+  if (!(r.grades ?? []).length) console.log(`  ${c.dim("no graded runs in the window")}`);
+  console.log("");
+  return s.failed ? 1 : 0;
+}
+
+/**
+ * `foldrun eval grade <eval> --run <id> --to <workspace>` — grade one finished
+ * run now, sampled or not (POST …/evals/<e>/grade { run }). The grade is kept
+ * like any other; a run graded again shows its newer grade. Exit 1 unless it
+ * passed.
+ */
+async function evalGradeCmd(name, flags, layout) {
+  if (!name || typeof flags.run !== "string" || !flags.run.trim()) {
+    throw new Error("`foldrun eval grade <eval> --run <run-id> --to <workspace>`");
+  }
+  const url = platformFor(flags, "eval grade");
+  const ws = platformWorkspace(flags, layout, `eval grade ${name}`);
+  const g = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals/${enc(name)}/grade`, { method: "POST", body: JSON.stringify({ run: flags.run.trim() }) });
+  if (flags.json) console.log(JSON.stringify(g, null, 2));
+  else {
+    console.log("");
+    printGrade(g);
+    for (const ch of g.checks ?? []) {
+      console.log(`    ${ch.passed ? c.green("✓") : ch.error ? c.amber("?") : c.red("✗")} ${ch.name}${ch.error ? c.dim(` — ${ch.error}`) : ""}`);
+      for (const a of ch.assertions ?? []) if (!a.passed) console.log(`        ${c.dim(`${a.type}: ${a.value}`)} — ${a.detail}`);
+    }
+    console.log(`  ${c.dim(`judges $${Number(g.costUsd ?? 0).toFixed(4)}`)}\n`);
+  }
+  return g.status === "pass" ? 0 : 1;
+}
+
+/** One comparison, as a table on a terminal. */
+function printComparison(r) {
+  const pct = (x) => (x === null || x === undefined ? "—" : `${Math.round(x * 100)}%`);
+  const w = Math.max(...(r.configs ?? []).map((x) => String(x.label).length), 7);
+  console.log(`\n  ${c.bold(r.eval)} ${c.dim(`judge ${r.judge?.model ?? "?"} · spent $${Number(r.spentUsd ?? 0).toFixed(2)} of $${Number(r.maxUsd ?? 0).toFixed(2)}${r.repeat > 1 ? ` · ${r.repeat}× each` : ""}`)}`);
+  if (r.stopped) console.log(`  ${c.amber(`stopped early: ${r.stopped}`)}`);
+  console.log(`\n  ${c.dim(`${"setting".padEnd(w)}  passing      cost     per run  time`)}`);
+  for (const x of r.configs ?? []) {
+    const decided = x.trials - (x.notRun ?? 0);
+    console.log(`  ${String(x.label).padEnd(w)}  ${pct(x.rate).padStart(4)} ${`${x.passed}/${decided}`.padEnd(7)} ${`$${Number(x.costUsd).toFixed(4)}`.padStart(9)}  ${x.avgCostUsd === null ? "      —" : `$${Number(x.avgCostUsd).toFixed(4)}`.padStart(8)}  ${x.avgSecs === null ? "—" : `${x.avgSecs}s`}${x.notRun ? c.dim(` (${x.notRun} not run)`) : ""}`);
+  }
+  const differ = (r.cases ?? []).filter((row) => new Set(row.passed.map((p, i) => p / (row.trials[i] || 1))).size > 1);
+  if (differ.length) {
+    console.log(`\n  ${c.dim("where they differ:")}`);
+    for (const row of differ) console.log(`  ${row.case}: ${row.passed.map((p, i) => `${r.configs[i].label} ${p}/${row.trials[i]}`).join(" · ")}`);
+  }
+  console.log("");
+}
+
+/**
+ * `foldrun eval compare <eval> --models fast,default,max --to <workspace>` —
+ * an eval's cases under two to four models, side by side (POST
+ * …/evals/<e>/compare, then polled). `--models` takes model[:effort] items
+ * (`fast:low,max:high`); `--effort` is the effort for the items that name
+ * none; `--agent <name>` compares only that agent's steps of a flow eval;
+ * `--repeat` (1–5) runs each case more than once; `--max-usd` is the spend
+ * limit (default 5). Every run is a test run. Waits for the result
+ * (`--timeout <s>`, default 3600; past it, the id to read it with).
+ * `--run <id>` reads one comparison; `--list` the kept ones. The Evals
+ * page's Compare models.
+ */
+async function evalCompareCmd(name, flags, layout) {
+  if (!name) throw new Error("which eval? `foldrun eval compare <eval> --models fast,default --to <workspace>`");
+  const url = platformFor(flags, "eval compare");
+  const ws = platformWorkspace(flags, layout, `eval compare ${name}`);
+  const base = `/api/workspaces/${enc(ws)}/evals/${enc(name)}/compare`;
+  if (flags.list === true) {
+    const r = await remoteCall(url, flags, base);
+    if (flags.json) return console.log(JSON.stringify(r, null, 2)), 0;
+    if (r.running) console.log(`\n  ${c.dim(`running: ${r.runId}, since ${r.startedAt}${r.progress ? ` — ${r.progress.done}/${r.progress.total} runs` : ""}`)}`);
+    for (const p of r.comparisons ?? []) {
+      const line = p.status === "done" && p.result ? p.result.configs.map((x) => `${x.label} ${x.rate === null ? "—" : `${Math.round(x.rate * 100)}%`}`).join(" · ") : c.red(p.error ?? "failed");
+      console.log(`  ${c.bold(p.runId)} ${c.dim(String(p.startedAt).slice(0, 16).replace("T", " "))}  ${line}`);
+    }
+    if (!(r.comparisons ?? []).length && !r.running) console.log(`\n  ${c.dim(`no comparisons of ${name} yet`)}`);
+    console.log("");
+    return 0;
+  }
+  const finish = (view) => {
+    if (view.state === "done" && view.result) {
+      if (flags.json) console.log(JSON.stringify(view.result, null, 2));
+      else printComparison(view.result);
+      return 0;
+    }
+    throw new Error(view.error ?? `the comparison ended as ${view.state ?? "unknown"}, with no result`);
+  };
+  // --run reads one comparison and starts nothing: a bare --run (an empty
+  // variable in a script) is refused, never read as "start a new one".
+  if (flags.run !== undefined && (typeof flags.run !== "string" || !flags.run.trim())) {
+    throw new Error("--run takes the comparison id it printed — `foldrun eval compare <eval> --to <ws> --run <id>`");
+  }
+  if (typeof flags.run === "string") {
+    const view = await remoteCall(url, flags, `${base}?run=${encodeURIComponent(flags.run)}`);
+    if (view.state === "running") {
+      if (flags.json) console.log(JSON.stringify(view, null, 2));
+      else console.log(`\n  ${c.dim(`still running, since ${view.startedAt}${view.progress ? ` — ${view.progress.done}/${view.progress.total} runs` : ""}`)}\n`);
+      return 1;
+    }
+    return finish(view);
+  }
+  if (typeof flags.models !== "string" || !flags.models.trim()) {
+    throw new Error("--models takes two to four settings, e.g. --models fast,default or --models fast:low,max:high");
+  }
+  const effort = typeof flags.effort === "string" ? flags.effort : undefined;
+  const agent = typeof flags.agent === "string" ? flags.agent : undefined;
+  const configs = flags.models.split(",").map((item) => item.trim()).filter(Boolean).map((item) => {
+    // Only a trailing known effort is an effort: llama3.2:3b stays one model id.
+    const m = /^(.*):(low|medium|high|xhigh|max)$/.exec(item);
+    const model = m ? m[1] : item;
+    const e = m ? m[2] : undefined;
+    return { model, ...((e ?? effort) ? { effort: e ?? effort } : {}), ...(agent ? { agent } : {}) };
+  });
+  const body = { configs, ...(flags.repeat !== undefined ? { repeat: Number(flags.repeat) } : {}), ...(flags["max-usd"] !== undefined ? { maxUsd: Number(flags["max-usd"]) } : {}) };
+  const started = await remoteCall(url, flags, base, { method: "POST", body: JSON.stringify(body) });
+  // --json is one JSON document on stdout; what happens on the way goes to stderr.
+  const say = flags.json ? (s) => console.error(s) : (s) => console.log(s);
+  say(`\n  ${c.dim(`comparison ${started.runId}: ${started.trials} test runs, at most $${Number(started.maxUsd).toFixed(2)}`)}`);
+  const wait = explicitTimeout(flags) ?? 3600;
+  const deadline = Date.now() + wait * 1000;
+  let said = -1;
+  for (;;) {
+    if (Date.now() > deadline) {
+      throw new Error(`still running after ${wait}s — \`foldrun eval compare ${name} --to ${ws} --run ${started.runId}\` reads it when it is done`);
+    }
+    await new Promise((r) => setTimeout(r, Number(process.env.FOLDRUN_EVAL_POLL_MS) || 5000));
+    const view = await remoteCall(url, flags, `${base}?run=${encodeURIComponent(started.runId)}`);
+    if (view.state === "running") {
+      if (view.progress && view.progress.done !== said) {
+        said = view.progress.done;
+        say(`  ${c.dim(`${view.progress.done}/${view.progress.total} runs done`)}`);
+      }
+      continue;
+    }
+    return finish(view);
+  }
+}
+
+// ------------------------------------------------------------- proposals
+
+/**
+ * A file's change, as ordered -/+ lines with a little context — the same
+ * reading the dashboard's diff gives. An LCS over the lines, so a reordered
+ * step or a removed duplicate shows; a file too long for that (over 2,000
+ * lines a side) is shown whole as removed and added rather than guessed at.
+ */
+function lineChanges(before, after) {
+  const a = before === null || before === undefined ? [] : String(before).split("\n");
+  const b = String(after ?? "").split("\n");
+  if (a.length > 2000 || b.length > 2000) return [...a.map((l) => ["-", l]), ...b.map((l) => ["+", l])];
+  const n = a.length;
+  const m = b.length;
+  const lcs = Array.from({ length: n + 1 }, () => new Uint16Array(m + 1));
+  for (let i = n - 1; i >= 0; i--) for (let j = m - 1; j >= 0; j--) lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < n || j < m) {
+    if (i < n && j < m && a[i] === b[j]) {
+      out.push([" ", a[i]]);
+      i++;
+      j++;
+    } else if (j < m && (i === n || lcs[i][j + 1] >= lcs[i + 1][j])) out.push(["+", b[j++]]);
+    else out.push(["-", a[i++]]);
+  }
+  return out;
+}
+
+function printFileChange(f) {
+  console.log(`\n  ${c.bold(f.path)}${f.before === null ? c.dim(" (new)") : ""}`);
+  const ops = lineChanges(f.before, f.content);
+  const near = (k) => ops.slice(Math.max(0, k - 2), k + 3).some(([op]) => op !== " ");
+  let skipped = false;
+  ops.forEach(([op, line], k) => {
+    if (op === " " && !near(k)) {
+      if (!skipped) console.log(`  ${c.dim("  …")}`);
+      skipped = true;
+      return;
+    }
+    skipped = false;
+    console.log(`  ${op === "+" ? c.green(`+ ${line}`) : op === "-" ? c.red(`- ${line}`) : c.dim(`  ${line}`)}`);
+  });
+}
+
+const PROPOSAL_LABEL = { drafting: "being drafted", ready: "ready to review", applying: "applying", applied: "applied", partial: "partly applied", failed: "draft failed", dismissed: "dismissed" };
+
+/**
+ * `foldrun proposals --to <workspace>` — the proposed fixes in a workspace
+ * (GET …/proposals), newest first: status, the eval, how many failures each
+ * covers. `--status ready` for the ones waiting on a person, `--eval <name>`,
+ * `--json`. `show <id>` prints one (the assistant's reasoning, the failures,
+ * the change per file); `apply <id>` writes its files after asking (`--yes`
+ * without a terminal); `dismiss <id>` sets it aside. The Evals page's
+ * Proposed fixes.
+ */
+async function proposalsCmd(positional, flags, layout) {
+  const url = platformFor(flags, "proposals");
+  const ws = platformWorkspace(flags, layout, "proposals");
+  const verb = positional[0];
+  const id = positional[1];
+  if (verb === "show" || verb === "apply" || verb === "dismiss") {
+    if (!id) throw new Error(`which proposal? \`foldrun proposals ${verb} <id> --to ${ws}\``);
+    const p = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/proposals/${enc(id)}`);
+    if (verb === "show") {
+      if (flags.json) return console.log(JSON.stringify(p, null, 2)), 0;
+      console.log(`\n  ${c.bold(p.id)} ${PROPOSAL_LABEL[p.status] ?? p.status} · ${p.eval} · ${c.dim(`${String(p.createdAt).slice(0, 16).replace("T", " ")} · ${p.by === "auto" ? "opened after repeated failures" : `asked by ${p.by}`}`)}`);
+      if (p.error) console.log(`  ${c.red(p.error)}`);
+      for (const n of p.notes ?? []) console.log(`  ${c.amber(n)}`);
+      console.log(`\n  ${c.dim("covers:")}`);
+      for (const f of p.failures ?? []) console.log(`  · ${f.runId ?? f.case} — ${f.check}: ${f.detail}`);
+      if (p.reply) console.log(`\n${p.reply.split("\n").map((l) => `  ${l}`).join("\n")}`);
+      for (const f of p.files ?? []) printFileChange(f);
+      for (const i of p.issues ?? []) console.log(`  ${i.level === "error" ? c.red("✗") : c.amber("!")} ${i.where}: ${i.message}`);
+      console.log("");
+      return 0;
+    }
+    if (verb === "apply") {
+      if (p.status !== "ready") throw new Error(`${id} is ${p.status} — only a ready proposal can be applied`);
+      // With --json the change is still shown before the yes — on stderr, so stdout stays one document.
+      if (flags.json) {
+        const log = console.log;
+        console.log = (...a) => console.error(...a);
+        try {
+          for (const f of p.files ?? []) printFileChange(f);
+        } finally {
+          console.log = log;
+        }
+      } else for (const f of p.files ?? []) printFileChange(f);
+      const files = (p.files ?? []).map((f) => f.path).join(", ");
+      if (!(await confirmed(flags, "proposals apply", `\n  Write ${files} in ${ws}? [y/N] `))) {
+        console.log(`\n  ${c.dim("nothing written")}\n`);
+        return 1;
+      }
+    }
+    const r = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/proposals/${enc(id)}`, { method: "POST", body: JSON.stringify({ action: verb }) });
+    if (flags.json) console.log(JSON.stringify(r, null, 2));
+    else console.log(`\n  ${c.green(PROPOSAL_LABEL[r.status] ?? r.status)} ${r.id}${r.applied?.length ? c.dim(` — wrote ${r.applied.join(", ")}`) : ""}\n`);
+    return 0;
+  }
+  if (verb && verb !== "ls" && verb !== "list") throw new Error(`\`foldrun proposals\` lists them; show, apply and dismiss take an id — not "${verb}"`);
+  const q = new URLSearchParams();
+  if (typeof flags.status === "string") q.set("status", flags.status);
+  if (typeof flags.eval === "string") q.set("eval", flags.eval);
+  const { proposals = [] } = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/proposals${q.size ? `?${q}` : ""}`);
+  if (flags.json) return console.log(JSON.stringify(proposals, null, 2)), 0;
+  if (!proposals.length) {
+    console.log(`\n  ${c.dim(`no proposed fixes in ${ws}`)}\n`);
+    return 0;
+  }
+  console.log("");
+  for (const p of proposals) {
+    const tone = p.status === "ready" ? c.amber : p.status === "applied" ? c.green : p.status === "failed" || p.status === "partial" ? c.red : c.dim;
+    console.log(`  ${c.bold(p.id)}  ${tone((PROPOSAL_LABEL[p.status] ?? p.status).padEnd(15))} ${p.eval} ${c.dim(`· ${p.failures?.length ?? 0} failure(s) · ${(p.files ?? []).map((f) => f.path).join(", ") || "no files"} · ${String(p.createdAt).slice(0, 10)}`)}`);
+  }
+  console.log("");
+  return 0;
+}
+
+/**
+ * `foldrun eval improve <eval> --to <workspace>` — ask for a proposed fix now
+ * (POST …/evals/<e>/improve): from a grader's failed grades no proposal has
+ * covered, or an eval's last failed cases. Waits for the draft (`--timeout`,
+ * default 300) and prints it; `--no-wait` returns at once with the id.
+ */
+async function evalImproveCmd(name, flags, layout) {
+  if (!name) throw new Error("which eval? `foldrun eval improve <eval> --to <workspace>`");
+  const url = platformFor(flags, "eval improve");
+  const ws = platformWorkspace(flags, layout, `eval improve ${name}`);
+  const p = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/evals/${enc(name)}/improve`, { method: "POST", body: "{}" });
+  const say = flags.json ? (s) => console.error(s) : (s) => console.log(s);
+  say(`\n  ${c.dim(`proposal ${p.id} — the assistant is drafting it from ${p.failures?.length ?? 0} failure(s)`)}`);
+  if (flags.wait === false || flags["no-wait"] === true) {
+    if (flags.json) console.log(JSON.stringify(p, null, 2));
+    else say(`  ${c.dim(`\`foldrun proposals show ${p.id} --to ${ws}\` when it is ready`)}\n`);
+    return 0;
+  }
+  const deadline = Date.now() + (explicitTimeout(flags) ?? 300) * 1000;
+  for (;;) {
+    await new Promise((r) => setTimeout(r, Number(process.env.FOLDRUN_EVAL_POLL_MS) || 4000));
+    const now = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/proposals/${enc(p.id)}`);
+    if (now.status !== "drafting") return proposalsCmd(["show", p.id], flags, layout).then(() => (now.status === "ready" ? 0 : 1));
+    if (Date.now() > deadline) {
+      if (flags.json) console.log(JSON.stringify(now, null, 2));
+      else say(`  ${c.dim(`still drafting — \`foldrun proposals show ${p.id} --to ${ws}\` later`)}\n`);
+      return 1;
+    }
+  }
+}
+
 /**
  * `foldrun promote <run-id>` — a finished run, kept as a regression case:
  * its task, and what the next run must still say.
@@ -9980,6 +10388,54 @@ async function flowTriggerCmd(positional, flags, layout) {
   });
 }
 
+/**
+ * `foldrun flow filter <flow> --payload <file|-|json> [--to <workspace>]` —
+ * would this delivery start the flow? Its `filter:` (core trigger-filter.ts)
+ * against a payload: a webhook's JSON body, an email's { from, to, subject,
+ * text }, a chained run's { run, flow, status, ending, verdict, summary }, a
+ * storage event's { by, paths }. With --to, the deployed flow answers (POST
+ * …/flows/<flow>/filter — the Triggers page's Test box); without, the local
+ * file. Nothing starts. Exit 0 when it would start a run, 1 when not.
+ */
+async function flowFilterCmd(positional, flags, layout) {
+  const flow = positional[1];
+  if (!flow || flags.payload === undefined || flags.payload === true) {
+    throw new Error("`foldrun flow filter <flow> --payload <file.json|->` (or inline JSON); --to <workspace> tests the deployed flow");
+  }
+  const spec = String(flags.payload);
+  const text = spec === "-" ? fs.readFileSync(0, "utf8") : /^\s*[{[]/.test(spec) ? spec : fs.readFileSync(spec, "utf8");
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    payload = text; // read as a webhook body: not JSON, so no filter matches
+  }
+  let answer;
+  if (namesPlatform(flags)) {
+    const url = platformFor(flags, "flow filter");
+    const ws = platformWorkspace(flags, layout, "flow filter");
+    answer = await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/flows/${enc(flow)}/filter`, { method: "POST", body: JSON.stringify({ payload }) });
+  } else {
+    const desk = await openDesk(flags, layout, `flow filter ${flow}`, flow);
+    const rel = await flowFileOf(desk, flow);
+    const lib = /** @type {any} */ (await core());
+    if (typeof lib.matchFilter !== "function") {
+      throw new Error("this install's @foldrun/core predates filter: — update foldrun, or test the deployed flow with --to <workspace>");
+    }
+    const f = lib.parseFlow(path.basename(rel), desk.files.get(rel));
+    const read = typeof payload === "string" ? lib.webhookFilterPayload(payload) : payload;
+    answer = { flow: f.name, trigger: f.trigger, filter: f.filter, applies: lib.FILTERABLE_TRIGGERS.includes(f.trigger), ...(f.filter != null ? lib.matchFilter(f.filter, read) : { match: true, reason: "this flow has no filter: — every delivery starts it" }) };
+  }
+  if (flags.json) {
+    console.log(JSON.stringify(answer, null, 2));
+  } else {
+    console.log(`\n  ${answer.match ? c.green("would start a run") : c.amber("would not start a run")} — ${answer.reason}`);
+    if (answer.applies === false) console.log(`  ${c.dim(`trigger: ${answer.trigger} delivers no payload, so its filter never applies`)}`);
+    console.log("");
+  }
+  return answer.match ? 0 : 1;
+}
+
 /**
  * `foldrun flow move-step <flow> --step <n|agent> --group <g> | --after <g>`
  * — dragging a card on the board: into group g, in parallel with what is
@@ -11290,6 +11746,13 @@ export async function run(command, positional, flags, workspace, layout) {
       // `eval new <name>` makes one on the platform; an eval called "new"
       // still runs as `foldrun eval new` with nothing after it.
       if (positional[0] === "new" && positional[1]) return evalNewCmd(positional[1], flags, layout);
+      // `eval grades <name>` / `eval grade <name> --run <id>`: a grader's
+      // findings, or one run graded now (an eval called "grades" or "grade"
+      // still runs as `foldrun eval grades` with nothing after it).
+      if (positional[0] === "grades" && positional[1]) return evalGradesCmd(positional[1], flags, layout);
+      if (positional[0] === "grade" && positional[1]) return evalGradeCmd(positional[1], flags, layout);
+      if (positional[0] === "compare" && positional[1]) return evalCompareCmd(positional[1], flags, layout);
+      if (positional[0] === "improve" && positional[1]) return evalImproveCmd(positional[1], flags, layout);
       // --to names a deployed workspace: its evals run there.
       if (typeof flags.to === "string") return remoteEvalsCmd(positional[0], flags, layout);
       // --last reads the platform's results; a local eval has none to read,
@@ -11299,6 +11762,9 @@ export async function run(command, positional, flags, workspace, layout) {
       return runEvals(positional[0], flags);
     case "promote":
       return promoteCmd(positional[0], flags, layout);
+    case "proposals":
+    case "proposal":
+      return proposalsCmd(positional, flags, layout);
     case "observe":
       return observeCmd(flags, layout);
     case "usage":
@@ -11360,6 +11826,8 @@ export async function run(command, positional, flags, workspace, layout) {
       return approvalsCmd(flags, layout);
     case "issues":
       return issuesCmd(positional, flags, layout);
+    case "inbox":
+      return inboxCmd(positional, flags);
     case "insights":
       return insightsCmd(flags);
     case "approve":
@@ -11437,6 +11905,7 @@ export async function run(command, positional, flags, workspace, layout) {
       if (positional[0] === "hook") return flowHookCmd(positional, flags, layout);
       if (positional[0] === "set") return flowSetCmd(positional, flags, layout);
       if (positional[0] === "trigger") return flowTriggerCmd(positional, flags, layout);
+      if (positional[0] === "filter") return flowFilterCmd(positional, flags, layout);
       if (positional[0] === "move-step") return flowMoveStepCmd(positional, flags, layout);
       if (positional[0] === "copy-step") return flowCopyStepCmd(positional, flags, layout);
       if (positional[0] === "paste") return flowPasteCmd(positional, flags, layout);

package/src/guide.mjs

@@ -30,7 +30,7 @@ export function agentRulesBlock() {
 
 # Read foldrun's docs before you edit this folder
 
-This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply reaches the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value.
+This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`).
 
 This block is for coding tools. It is written and re-added by the foldrun CLI, and the runtime strips it, so the agents that run here never see it; the rest of this file is the account's own context, which they do read. Committing the block with your work keeps the tree clean.