@foldrun/core 2.5.0 → 2.6.0

package/src/frontmatter-text.ts

@@ -0,0 +1,109 @@
+// Frontmatter edited as text, where it is written: at the top or inside one
+// of the four job blocks. No node imports — the flow canvas (flow-patterns.ts)
+// runs in the browser and edits frontmatter with it too.
+
+/** A block header on its own line — an anchor and a trailing `# comment`
+ *  allowed. */
+const JOB_BLOCK = /^["']?(governance|guardrail|observability|evaluation)["']?\s*:\s*(&\S+\s*)?(#.*)?$/;
+/** Any other block header: an inline map, an alias, a tag — a form these
+ *  writers do not edit. */
+const JOB_OTHER = /^["']?(governance|guardrail|observability|evaluation)["']?\s*:\s*\S/;
+/** An inline map closed on its own line: `guardrail: {network: [a.com]}`. */
+const JOB_ONE_LINE = /^["']?(governance|guardrail|observability|evaluation)["']?\s*:\s*\{.*\}\s*(#.*)?$/;
+
+const indentOf = (l: string) => l.match(/^[ \t]*/)?.[0].length ?? 0;
+
+export interface KeySpan {
+  /** The key's line. */
+  at: number;
+  /** One past its last line. */
+  end: number;
+  /** What its line starts with. */
+  indent: string;
+  /** The block header's line, when it is inside one. */
+  block: number | null;
+}
+
+/** Thrown for a key a writer cannot edit in place: one that is, or may be,
+ *  inside a block not written one key per line (`guardrail: {…}`, an alias).
+ *  Rewriting it would mean re-serialising the person's YAML, and adding the
+ *  key at the top beside it would be a config/conflict — so the writer says
+ *  what to write instead. */
+export class InlineBlockError extends Error {
+  status = 409;
+  constructor(key: string, block: string) {
+    super(`\`${key}\` may be inside \`${block}:\`, which is not written one key per line — write \`${block}:\` one key per line to change it here, or edit the file`);
+  }
+}
+
+/** A comment or blank line: neither ends a block nor is one of its keys. */
+const filler = (l: string) => l.trim() === "" || /^\s*#/.test(l);
+
+/**
+ * Where a key is written in frontmatter lines: at the top, or a direct child
+ * of one of the four job blocks (`guardrail:` and so on). Every writer that
+ * edits a key as text reads it here, so a file written in blocks is edited
+ * where it is — never given a second, flat copy that check would refuse as
+ * config/conflict. A key inside an inline block map throws InlineBlockError.
+ */
+export function keySpan(lines: string[], key: string): KeySpan | null {
+  const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const span = (at: number, indent: string, block: number | null): KeySpan => {
+    let end = at + 1;
+    // The key continues while lines are indented deeper, are an item of its
+    // list written at its own indent (YAML allows `key:\n- a`), or are blank
+    // lines and comments inside it.
+    while (
+      end < lines.length &&
+      (filler(lines[end]) ||
+        indentOf(lines[end]) > indent.length ||
+        (indentOf(lines[end]) === indent.length && /^[ \t]*-(\s|$)/.test(lines[end])))
+    ) end++;
+    // Blank lines and comments at its foot, no deeper than the key, belong
+    // to what follows.
+    while (end > at + 1 && filler(lines[end - 1]) && (lines[end - 1].trim() === "" || indentOf(lines[end - 1]) <= indent.length)) end--;
+    return { at, end, indent, block };
+  };
+  // A key may be quoted: `"network": none`.
+  const named = `["']?${k}["']?\\s*:`;
+  const top = lines.findIndex((l) => new RegExp(`^${named}`).test(l));
+  if (top !== -1) return span(top, "", null);
+  for (let h = 0; h < lines.length; h++) {
+    const other = !JOB_BLOCK.test(lines[h]) && JOB_OTHER.exec(lines[h]);
+    if (other) {
+      // One closed line can be read: refuse only if the key is in it. Any
+      // other form (a map over several lines, an alias) cannot be, so any
+      // key not found at the top is refused rather than added beside it.
+      if (!JOB_ONE_LINE.test(lines[h]) || new RegExp(`[{,]\\s*${named}`).test(lines[h])) throw new InlineBlockError(key, other[1]!);
+      continue;
+    }
+    if (!JOB_BLOCK.test(lines[h])) continue;
+    // Its children sit at the indent of its first indented line; a deeper
+    // line of the same name belongs to one of them, not to the block.
+    // Comments and blank lines, indented or not, do not end it.
+    let child = -1;
+    let merged = false;
+    for (let n = h + 1; n < lines.length && (/^[ \t]/.test(lines[n]) || filler(lines[n])); n++) {
+      if (filler(lines[n])) continue;
+      if (child === -1) child = indentOf(lines[n]);
+      if (indentOf(lines[n]) !== child) continue;
+      const m = new RegExp(`^([ \t]+)${named}`).exec(lines[n]);
+      if (m) return span(n, m[1]!, h);
+      if (/^[ \t]+<<\s*:/.test(lines[n])) merged = true;
+    }
+    // `<<: *policy` may bring the key in from elsewhere: not one this text
+    // edit can see, so it is refused rather than added beside it.
+    if (merged) throw new InlineBlockError(key, JOB_BLOCK.exec(lines[h])![1]!);
+  }
+  return null;
+}
+
+/** A block header left with nothing under it is removed with its last key.
+ *  Blank lines and comments between it and its next key do not count as
+ *  nothing: the header stays while any indented key follows them. */
+export function dropEmptyBlock(lines: string[], header: number): string[] {
+  let n = header + 1;
+  while (n < lines.length && filler(lines[n])) n++;
+  const next = lines[n];
+  return next === undefined || !/^[ \t]+\S/.test(next) ? [...lines.slice(0, header), ...lines.slice(header + 1)] : lines;
+}

package/src/judge-verdict.ts

@@ -0,0 +1,52 @@
+// What a judge said: the PASS or FAIL alone on its last line, after its
+// reasoning. Shared by the eval judge (evals.ts) and a flow step's
+// `verify: judge:` (step-exec.ts), which ask for the same shape.
+//
+// The word comes last because, asked for it first, a judge commits before
+// it has looked and then argues the other way — "FAIL … which meets the
+// criterion" (vaza evals, 21 Oct 2026).
+
+import { EFFORT_LEVELS } from "./frontmatter-fields.ts";
+
+/** The line to end a judge prompt with. */
+export const JUDGE_VERDICT_INSTRUCTION =
+  "Check each part against the text in a few short sentences. Then, on the last line and alone, write exactly PASS or FAIL — PASS only if every part holds.";
+
+/**
+ * The judge's verdict: the PASS or FAIL alone on its last line, with the
+ * reasoning before it as the detail. An answer in the old shape (the word
+ * first) still reads; one with no verdict at all is a FAIL that says so.
+ */
+export function judgeVerdict(text: string): { passed: boolean; detail: string } {
+  const lines = text.trim().split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const word = (l: string | undefined) => /^[*_`#\s]*(PASS|FAIL)[*_`.\s]*$/i.exec(l ?? "")?.[1]?.toUpperCase();
+  let verdict = word(lines[lines.length - 1]);
+  let reason = lines.slice(0, -1).join(" ");
+  if (!verdict) {
+    const first = /^[*_`#\s]*(PASS|FAIL)\b[*_`:.\s-]*(.*)$/i.exec(lines[0] ?? "");
+    if (first) {
+      verdict = first[1]!.toUpperCase();
+      reason = [first[2], ...lines.slice(1)].join(" ").trim();
+    }
+  }
+  if (!verdict) return { passed: false, detail: `judge gave no PASS or FAIL: ${text.trim().slice(0, 300) || "nothing"}` };
+  // The end of the reasoning is the part that decided it.
+  const why = reason.length > 400 ? `…${reason.slice(-400)}` : reason;
+  return { passed: verdict === "PASS", detail: `${verdict}${why ? ` — ${why}` : ""}` };
+}
+
+/** `judge:` in AGENTS.md — the model and effort every judge in the workspace
+ *  grades with, unless an eval names its own. `model` is a tier or alias as
+ *  anywhere else; what is wrong with the block, in words, for check. */
+export function parseJudge(raw: unknown): { model?: string; effort?: string; problems: string[] } {
+  if (raw === undefined || raw === null) return { problems: [] };
+  if (typeof raw !== "object" || Array.isArray(raw)) return { problems: ["judge: is a block — {model: fast | default | max, effort: low…max}"] };
+  const o = raw as Record<string, unknown>;
+  const problems: string[] = [];
+  for (const k of Object.keys(o)) if (k !== "model" && k !== "effort") problems.push(`judge: ${k} — not a key; the keys are model and effort`);
+  const model = typeof o.model === "string" && o.model.trim() ? o.model.trim() : undefined;
+  if (o.model !== undefined && !model) problems.push("judge: model — a tier (fast, default, max), an alias or a model id");
+  const effort = typeof o.effort === "string" && (EFFORT_LEVELS as readonly string[]).includes(o.effort.trim()) ? o.effort.trim() : undefined;
+  if (o.effort !== undefined && !effort) problems.push(`judge: effort ${String(o.effort)} — low, medium, high, xhigh or max`);
+  return { ...(model ? { model } : {}), ...(effort ? { effort } : {}), problems };
+}

package/src/matter.ts

@@ -21,13 +21,125 @@
 // it.
 
 import grayMatter from "gray-matter";
+import { JOBS, FOLDABLE, type Job } from "./frontmatter-fields.ts";
 
 type Options = NonNullable<Parameters<typeof grayMatter>[1]>;
 
+/** Where the four job blocks put things, on the parsed data — out of sight
+ *  of every reader that spreads it or writes it out as JSON. */
+const FOLD = Symbol.for("foldrun.jobBlocks");
+
+export interface JobFold {
+  /** A key lifted out of a block, and the block it was in. */
+  folded: Map<string, Job>;
+  /** A key set both at the top and inside a block: the top one is kept, and
+   *  check refuses the file (config/conflict). */
+  conflicts: Map<string, Job>;
+}
+
+/** What the fold did to this data, or null when it had no blocks. */
+export function jobFold(data: unknown): JobFold | null {
+  return data && typeof data === "object" ? ((data as Record<symbol, JobFold | undefined>)[FOLD] ?? null) : null;
+}
+
+/**
+ * The four job blocks (`governance:`, `guardrail:`, `observability:`,
+ * `evaluation:`) read as the flat keys they hold (frontmatter-fields.ts
+ * JOB_FIELDS). Only a key some config kind lets that block hold is lifted;
+ * anything else stays in the block for check to report. A key set both ways
+ * keeps its top-level value and is recorded. Nothing parsed is changed: new
+ * objects are built (YAML aliases share nodes — deleting from one would
+ * delete from the other).
+ */
+function foldJobs(data: Record<string, unknown>): Record<string, unknown> {
+  let fold: JobFold | null = null;
+  let out: Record<string, unknown> | null = null;
+  for (const { name } of JOBS) {
+    const block = data[name];
+    if (!block || typeof block !== "object" || Array.isArray(block) || block instanceof Date) continue;
+    const inner = block as Record<string, unknown>;
+    const lift = Object.keys(inner).filter((k) => FOLDABLE[name].has(k));
+    if (!lift.length) continue;
+    out ??= { ...data };
+    fold ??= { folded: new Map(), conflicts: new Map() };
+    const rest: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(inner)) if (!lift.includes(k)) rest[k] = v;
+    for (const k of lift) {
+      if (Object.prototype.hasOwnProperty.call(data, k)) fold.conflicts.set(k, name);
+      else {
+        out[k] = inner[k];
+        fold.folded.set(k, name);
+      }
+    }
+    if (Object.keys(rest).length) out[name] = rest;
+    else delete out[name];
+  }
+  if (!out || !fold) return data;
+  Object.defineProperty(out, FOLD, { value: fold, enumerable: false });
+  return out;
+}
+
 function matter(input: string, options?: Options) {
   return grayMatter(input, options ?? {});
 }
 matter.stringify = grayMatter.stringify;
 matter.test = grayMatter.test;
 
+/**
+ * matter(), for the three files that hold configuration — an agent, a flow,
+ * AGENTS.md — with the four job blocks read as flat keys. Every reader of
+ * those files goes through this (tests/jobs.test.ts holds them to it);
+ * knowledge, memory, skills and every other document keep matter(), so a
+ * note's own `governance:` is its own (Codex debate, 21 Oct 2026).
+ */
+export function configMatter(input: string, options?: Options) {
+  const file = grayMatter(input, options ?? {});
+  if (file.data && typeof file.data === "object" && !Array.isArray(file.data)) {
+    (file as { data: Record<string, unknown> }).data = foldJobs(file.data as Record<string, unknown>);
+  }
+  return file;
+}
+
 export default matter;
+
+/** The first line of a YAML parse error, with where it is: what a person
+ *  needs to fix the file, without the parser's excerpt. */
+export function frontmatterErrorText(err: unknown): string {
+  const msg = err instanceof Error ? err.message : String(err);
+  return `frontmatter does not parse — ${msg.split("\n")[0].trim().replace(/:$/, "")}. Quote a value that contains a colon followed by a space.`;
+}
+
+/** The 1-based file line a YAML parse error points at, when it says. The
+ *  text gray-matter hands the parser starts with the newline after the
+ *  opening `---`, so the parser's 0-based line is the file's 1-based one. */
+export function frontmatterErrorLine(err: unknown): number | undefined {
+  const line = (err as { mark?: { line?: unknown } } | null)?.mark?.line;
+  return typeof line === "number" ? line + 1 : undefined;
+}
+
+/** Frontmatter as the runtime reads a skill: strictly first, then once more
+ *  with every unquoted value that holds a colon quoted (the commonest way a
+ *  hand-written SKILL.md breaks, and one other skills clients forgive), and
+ *  empty when even that fails. `lenient` says the second read was needed. */
+export function parseLenient(raw: string): { data: Record<string, unknown>; lenient: boolean; failed: boolean } {
+  try {
+    return { data: matter(raw).data as Record<string, unknown>, lenient: false, failed: false };
+  } catch {
+    const fm = raw.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---/);
+    if (fm) {
+      const fixed = fm[1].replace(
+        /^([A-Za-z0-9_-]+):[ \t]+(?!["'>|])(.*:.*)$/gm,
+        (_m, k: string, v: string) => `${k}: ${JSON.stringify(v)}`,
+      );
+      try {
+        // A function replacer, not a string: a fixed block containing `$&` or
+        // `$$` (a value with those in it) would otherwise be treated as a
+        // replacement pattern and splice the whole frontmatter into itself.
+        return { data: matter(raw.replace(fm[1], () => fixed)).data as Record<string, unknown>, lenient: true, failed: false };
+      } catch {
+        /* fall through */
+      }
+    }
+    return { data: {}, lenient: false, failed: true };
+  }
+}

package/src/network.ts

@@ -28,6 +28,8 @@
 // proxy (foldrun-platform egress-proxy.ts) holds the rule per request.
 
 /** How wide a step's network is. */
+import { keySpan, dropEmptyBlock } from "./frontmatter-text.ts";
+
 export type NetworkLevel = "open" | "trusted" | "none";
 
 export const NETWORK_LEVELS: readonly NetworkLevel[] = ["open", "trusted", "none"];
@@ -402,13 +404,15 @@ export function setNetworkSetting(raw: string, setting: { level?: NetworkLevel;
   if (lines[0]?.trim() !== "---") return line ? ["---", line, "---", ...lines].join(eol) : raw;
   const close = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
   if (close < 0) return raw;
-  const at = lines.findIndex((l, i) => i > 0 && i < close && /^network\s*:/.test(l));
-  if (at < 0) {
+  // Where network: is written — at the top or inside `guardrail:` — is
+  // where it is set (frontmatter-text.ts); written nowhere, it goes last.
+  const where = keySpan(lines.slice(1, close), "network");
+  if (!where) {
     if (line) lines.splice(close, 0, line);
     return lines.join(eol);
   }
-  let end = at + 1;
-  while (end < close && (/^\s+\S/.test(lines[end]) || /^\s*-\s/.test(lines[end]))) end++;
-  lines.splice(at, end - at, ...(line ? [line] : []));
-  return lines.join(eol);
+  const front = lines.slice(1, close);
+  front.splice(where.at, where.end - where.at, ...(line ? [`${where.indent}${line}`] : []));
+  const edited = !line && where.block !== null ? dropEmptyBlock(front, where.block) : front;
+  return [lines[0], ...edited, ...lines.slice(close)].join(eol);
 }

package/src/package.ts

@@ -26,7 +26,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import matter from "./matter.ts";
+import matter, { configMatter } from "./matter.ts";
 import {
   assertSafeName,
   isEditablePath,
@@ -592,7 +592,13 @@ interface AgentFront {
 }
 
 function frontOf(content: string): AgentFront {
-  const d = safeFront(content);
+  // An agent's secrets: and tools: may sit in its guardrail: block.
+  let d: Record<string, unknown>;
+  try {
+    d = configMatter(content).data as Record<string, unknown>;
+  } catch {
+    d = {};
+  }
   const apis = Array.isArray(d.apis) ? d.apis.map((a) => (a && typeof a === "object" ? String((a as { name?: unknown }).name ?? "") : "")) : [];
   const mcp = d.mcpServers && typeof d.mcpServers === "object" ? Object.keys(d.mcpServers) : [];
   const scripts = list(d.scripts);

package/src/provider-health.ts

@@ -21,7 +21,7 @@
 import { accountModelBlock } from "./model-credential.ts";
 import fs from "node:fs";
 import path from "node:path";
-import matter from "./matter.ts";
+import { configMatter } from "./matter.ts";
 import { getSecret } from "./secrets.ts";
 import { noteSecretUse, healthKey } from "./secret-health.ts";
 import { accountDir, workspaceDir, listWorkspaces, listAgents, parseProvider, type ProviderSpec } from "./store.ts";
@@ -205,7 +205,7 @@ function cheapestModel(spec: ProviderSpec): string {
 
 function frontmatterOf(file: string): Record<string, unknown> {
   try {
-    return (matter(fs.readFileSync(file, "utf8")).data ?? {}) as Record<string, unknown>;
+    return (configMatter(fs.readFileSync(file, "utf8")).data ?? {}) as Record<string, unknown>;
   } catch {
     return {};
   }

package/src/run-container.ts

@@ -73,6 +73,9 @@ export interface ContainerStepInput {
   budgetNote?: string;
   price?: TokenPrice | null;
   verify?: string;
+  /** The model `verify: judge:` grades with (the workspace's `judge:`). */
+  judgeModel?: string;
+  judgeEffort?: string;
   /** `output: json` — checked inside, where the reply is. */
   output?: "json";
   /** `schema:` and `max_turns:`, resolved host-side — see ExecOptions. */
@@ -556,7 +559,8 @@ export function runtimeCacheMount(
 
 // ---------- the runner image ----------
 
-const DRIVER = `// The runner container's entrypoint. Reads one step, executes it with the
+/** The runner container's entrypoint, as JS text: written into the image as driver.mjs, so it must be plain JS — a TypeScript cast here broke every step on v2026.10.21.5 (tests/run-container.test.ts checks it). */
+export const DRIVER = `// The runner container's entrypoint. Reads one step, executes it with the
 // same core the server uses, speaks JSONL on stdout, exits.
 import fs from "node:fs";
 const input = JSON.parse(fs.readFileSync("/opt/runner/job/input.json", "utf8"));
@@ -754,6 +758,8 @@ try {
     price: input.price,
     verify: input.verify,
     verifyEnv: toolEnv,
+    ...(typeof input.judgeModel === "string" ? { judgeModel: input.judgeModel } : {}),
+    ...(typeof input.judgeEffort === "string" ? { judgeEffort: input.judgeEffort } : {}),
     output: input.output,
     schema: input.schema,
     maxTurns: input.maxTurns,
@@ -1358,6 +1364,10 @@ export interface RunInContainerArgs {
    *  without it, "stop" could only mean "stop after this step", and a
    *  browser step has fifteen minutes left to spend. */
   runId?: string;
+  /** Whether a person has stopped the run, read from the record. A step that
+   *  waits for room before its sandbox exists asks this, since there is no
+   *  sandbox yet for the stop to destroy. */
+  stopRequested?: () => boolean;
   /** The reservation class — which limits this step's sandbox holds. */
   size?: "small" | "large" | "heavy";
   /** Re-attach to a sandbox a previous driver started, instead of creating