@foldrun/core 2.4.0 → 2.6.0

package/src/matter.ts

@@ -0,0 +1,145 @@
+// gray-matter, without its cache.
+//
+// gray-matter keeps every input it is handed in a module-level cache keyed by
+// the text, and it stores the entry BEFORE it parses. When the YAML does not
+// parse, the first call throws — and the entry stays, unparsed. The next call
+// with the same text returns it: no error, `data` empty. So in any process
+// that read a file twice, a broken frontmatter was an error once and valid
+// forever after.
+//
+// That is how one agent file took the worker down on 20 Oct 2026. The source
+// API's save check parsed it first (and threw, caught), the write's own
+// "reject files whose frontmatter doesn't parse" then hit the cache and let it
+// through, and the worker, parsing it fresh at boot, threw on it out of
+// listWorkspaces and never came up — for every account on the box.
+//
+// Passing an options object skips the cache entirely (gray-matter only reads
+// and writes it when there are none), so every call here parses the text it
+// was given. The cost is a parse per call, which is what every caller already
+// believed it was paying. Import this, never "gray-matter" itself: a test in
+// tests/matter.test.ts and foldrun-web's consistency test hold every repo to
+// 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/model-credential.ts

@@ -110,3 +110,48 @@ export function accountModelBlock(read: (name: string) => string | null): Record
 export function isClaudeLoginToken(value: string | null | undefined): boolean {
   return typeof value === "string" && /^sk-ant-oat\d*-/.test(value.trim());
 }
+
+/**
+ * The variables a step's own model call is made with: the credential, the
+ * endpoint, the tier names a provider renames and its headers, and the
+ * egress proxy's name for the key. A declared secret with one of these
+ * names would replace the step's model settings in the sandbox, so `check`
+ * warns about it and the runner leaves it out (FOL-19).
+ */
+export const MODEL_ENV_NAMES: readonly string[] = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "ANTHROPIC_BASE_URL",
+  "ANTHROPIC_CUSTOM_HEADERS",
+  "ANTHROPIC_MODEL",
+  "ANTHROPIC_SMALL_FAST_MODEL",
+  "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+  "ANTHROPIC_DEFAULT_SONNET_MODEL",
+  "ANTHROPIC_DEFAULT_OPUS_MODEL",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "FOLDRUN_MODEL_KEY",
+  "FOLDRUN_MODEL_KEY_FALLBACK",
+];
+
+/** How such a secret crosses into the sandbox instead; the driver maps it
+ *  back for the agent's own tools (run-container.ts). */
+export const DECLARED_ENV_PREFIX = "FOLDRUN_DECLARED_";
+
+export function isModelEnvName(name: string): boolean {
+  return MODEL_ENV_NAMES.includes(name.trim());
+}
+
+/** Why a `secrets:` list names a model variable, or null. */
+export function modelSecretCollision(names: unknown): string | null {
+  const list = (Array.isArray(names) ? names : typeof names === "string" ? names.split(",") : [])
+    .filter((n): n is string => typeof n === "string")
+    .map((n) => n.trim())
+    .filter(isModelEnvName);
+  if (!list.length) return null;
+  const which = list.map((n) => `\`${n}\``).join(", ");
+  return (
+    `${which} ${list.length === 1 ? "is a name" : "are names"} the step's own model call uses, so the model keeps its own value: ` +
+    "its script and API tools and `verify:` get the declared one, but its own shell sees the model's — " +
+    "give the secret another name (MY_ANTHROPIC_KEY), or run the model on it with `provider:` or `foldrun account model set`"
+  );
+}

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"];
@@ -268,13 +270,37 @@ export function resolveNetwork(args: {
 }
 
 /** One line for the run's trace. */
+/** The sites a step reached, read from the egress lines on its trail
+ *  (egress-proxy.ts formatDrain): `egress: CONNECT host:port …` and
+ *  `egress: GET host/path → 200 …`. Lower-cased, port dropped, sorted. */
+export function hostsInTrail(events: { type?: string; text?: string }[]): string[] {
+  const hosts = new Set<string>();
+  for (const e of events) {
+    // A refused or unreachable call reached nothing: the proxy says so on
+    // the same line (`… refused — …`, `… → unreachable: …`).
+    if (typeof e.text === "string" && /^egress: \S+ \S+ (?:refused|unreachable|→ unreachable)\b/.test(e.text)) continue;
+    const m = typeof e.text === "string" ? /^egress: (?:CONNECT ([^\s:]+)|[A-Z]+ ([^\s/:]+))/.exec(e.text) : null;
+    const host = (m?.[1] ?? m?.[2])?.toLowerCase();
+    if (host) hosts.add(host);
+  }
+  return [...hosts].sort();
+}
+
+/** `network_enforce: true` in the account's or the workspace's AGENTS.md:
+ *  the steps here have a site off their list refused rather than only named.
+ *  Either level switches it on; neither can switch off what the other, or the
+ *  install (FOLDRUN_NETWORK_ENFORCE=1), switched on. */
+export function networkEnforceWanted(account: unknown, workspace: unknown): boolean {
+  return account === true || workspace === true;
+}
+
 export function networkLine(policy: NetworkPolicy, enforced: boolean | null): string {
   const how =
     enforced === null
       ? " — not enforced here (no sandbox network)"
       : enforced
         ? ""
-        : " — report only on this install: a site off the list is allowed and named in the trace";
+        : " — report only: a site off the list is allowed and named in the trace (network_enforce: true in AGENTS.md refuses it)";
   if (policy.level === "open") return `network: open (${policy.from}) — any public site${how}`;
   const parts: string[] = [];
   if (policy.defaults) parts.push(`the trusted list (${TRUSTED_SITES.length} sites)`);
@@ -378,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/notify.ts

@@ -372,14 +372,29 @@ export async function sendPlainNotification(
   workspace: string,
   msg: { event: string; headline: string; detail: string; flow?: string; runId?: string },
 ): Promise<boolean> {
+  return (await sendPlainNotificationOutcome(tenant, workspace, msg)).ok;
+}
+
+/**
+ * The same send, saying what became of it: `ok` when it arrived, `retrying`
+ * when a webhook's first attempt failed and the delivery log holds it for
+ * another (FOL-58 — a caller that would retry on its own must not start a
+ * second chain).
+ */
+export async function sendPlainNotificationOutcome(
+  tenant: string,
+  workspace: string,
+  msg: { event: string; headline: string; detail: string; flow?: string; runId?: string },
+): Promise<{ ok: boolean; retrying: boolean }> {
+  const no = { ok: false, retrying: false };
   const config = notifyConfig(tenant, workspace);
-  if (!config) return false;
+  if (!config) return no;
   // These follow `failed`. Each one IS a failure — a flow that stopped
   // running, a run that has stalled, a budget about to refuse work — that
   // happens to produce no failed run for the normal path to report. A
   // destination hearing about failures hears about these; naming one
   // explicitly also turns it on; leaving `failed` out silences them.
-  if (!config.events.includes(msg.event) && !config.events.includes("failed")) return false;
+  if (!config.events.includes(msg.event) && !config.events.includes("failed")) return no;
 
   const body = {
     text: `${msg.headline} — ${msg.detail} · ${workspace}`,
@@ -392,7 +407,7 @@ export async function sendPlainNotification(
   try {
     if (config.email) {
       const mail = notifyMail(tenant);
-      if (!mail) return false;
+      if (!mail) return no;
       const r = await sendMail({
         tenant,
         mail,
@@ -402,14 +417,14 @@ export async function sendPlainNotification(
         subject: `${msg.headline}`.slice(0, 160),
         text: `${msg.headline}\n\n${msg.detail}\n\nworkspace: ${workspace}\n${msg.flow ? `flow: ${msg.flow}\n` : ""}${msg.runId ? `run: ${msg.runId}\n` : ""}`,
       });
-      return r.ok;
+      return { ok: r.ok, retrying: false };
     }
-    if (!webhookTarget(tenant, workspace, config).url) return false;
+    if (!webhookTarget(tenant, workspace, config).url) return no;
     const r = await platform.deliverWebhook(tenant, workspace, { event: msg.event, body: JSON.stringify(body), retry: true });
-    return r.ok;
+    return { ok: r.ok, retrying: r.retrying === true };
   } catch (err) {
     console.error(`[foldrun] notify (${msg.event}): ${tenant}/${workspace} →`, err instanceof Error ? err.message : err);
-    return false;
+    return no;
   }
 }
 

package/src/okf.ts

@@ -22,7 +22,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.ts";
 
 export const OKF_VERSION = "0.2";