@foldrun/core 2.4.0 → 2.6.0

package/dist/src/matter.js

@@ -0,0 +1,132 @@
+// 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 } from "./frontmatter-fields.js";
+/** 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");
+/** What the fold did to this data, or null when it had no blocks. */
+export function jobFold(data) {
+    return data && typeof data === "object" ? (data[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) {
+    let fold = null;
+    let out = 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;
+        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 = {};
+        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, 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, options) {
+    const file = grayMatter(input, options ?? {});
+    if (file.data && typeof file.data === "object" && !Array.isArray(file.data)) {
+        file.data = foldJobs(file.data);
+    }
+    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) {
+    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) {
+    const line = err?.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) {
+    try {
+        return { data: matter(raw).data, 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, v) => `${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, lenient: true, failed: false };
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        return { data: {}, lenient: false, failed: true };
+    }
+}

package/dist/src/model-credential.d.ts

@@ -28,3 +28,17 @@ export declare function accountModelBlock(read: (name: string) => string | null)
  *  claude.ai logins, so on a hosted platform only the operator's own
  *  accounts may; a customer's key must be an API key. */
 export declare function isClaudeLoginToken(value: string | null | undefined): boolean;
+/**
+ * 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 declare const MODEL_ENV_NAMES: readonly string[];
+/** How such a secret crosses into the sandbox instead; the driver maps it
+ *  back for the agent's own tools (run-container.ts). */
+export declare const DECLARED_ENV_PREFIX = "FOLDRUN_DECLARED_";
+export declare function isModelEnvName(name: string): boolean;
+/** Why a `secrets:` list names a model variable, or null. */
+export declare function modelSecretCollision(names: unknown): string | null;

package/dist/src/model-credential.js

@@ -96,3 +96,43 @@ export function accountModelBlock(read) {
 export function isClaudeLoginToken(value) {
     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 = [
+    "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) {
+    return MODEL_ENV_NAMES.includes(name.trim());
+}
+/** Why a `secrets:` list names a model variable, or null. */
+export function modelSecretCollision(names) {
+    const list = (Array.isArray(names) ? names : typeof names === "string" ? names.split(",") : [])
+        .filter((n) => 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/dist/src/network.d.ts

@@ -1,4 +1,3 @@
-/** How wide a step's network is. */
 export type NetworkLevel = "open" | "trusted" | "none";
 export declare const NETWORK_LEVELS: readonly NetworkLevel[];
 /** One level's `network:` line, read. Absent fields inherit. */
@@ -74,6 +73,18 @@ export declare function resolveNetwork(args: {
     implied?: Iterable<string>;
 }): NetworkPolicy;
 /** 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 declare function hostsInTrail(events: {
+    type?: string;
+    text?: string;
+}[]): string[];
+/** `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 declare function networkEnforceWanted(account: unknown, workspace: unknown): boolean;
 export declare function networkLine(policy: NetworkPolicy, enforced: boolean | null): string;
 /** What the proxy says when it refuses a site. */
 export declare function refusalText(policy: Pick<NetworkPolicy, "level">, host: string): string;

package/dist/src/network.js

@@ -26,6 +26,8 @@
 // proxy and DNS and nothing else, so a program that ignores the proxy
 // variables fails instead of going round. This file is the vocabulary; the
 // proxy (foldrun-platform egress-proxy.ts) holds the rule per request.
+/** How wide a step's network is. */
+import { keySpan, dropEmptyBlock } from "./frontmatter-text.js";
 export const NETWORK_LEVELS = ["open", "trusted", "none"];
 /**
  * The trusted list: the domains Anthropic's Claude Code cloud environments
@@ -233,12 +235,36 @@ export function resolveNetwork(args) {
     return { level, hosts, from, defaults, added, implied };
 }
 /** 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) {
+    const hosts = new Set();
+    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, workspace) {
+    return account === true || workspace === true;
+}
 export function networkLine(policy, enforced) {
     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 = [];
@@ -346,15 +372,16 @@ export function setNetworkSetting(raw, setting) {
     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/dist/src/notify.d.ts

@@ -171,6 +171,22 @@ export declare function sendPlainNotification(tenant: string, workspace: string,
     flow?: string;
     runId?: string;
 }): Promise<boolean>;
+/**
+ * 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 declare function sendPlainNotificationOutcome(tenant: string, workspace: string, msg: {
+    event: string;
+    headline: string;
+    detail: string;
+    flow?: string;
+    runId?: string;
+}): Promise<{
+    ok: boolean;
+    retrying: boolean;
+}>;
 /**
  * Prove the notification path works, now, while someone is looking.
  *

package/dist/src/notify.js

@@ -305,16 +305,26 @@ export function isQuietFlow(flow) {
  * of it. They are on by default: an alert nobody opted into is the point.
  */
 export async function sendPlainNotification(tenant, workspace, msg) {
+    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, workspace, msg) {
+    const no = { ok: false, retrying: false };
     const config = notifyConfig(tenant, workspace);
     if (!config)
-        return false;
+        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;
+        return no;
     const body = {
         text: `${msg.headline} — ${msg.detail} · ${workspace}`,
         workspace,
@@ -327,7 +337,7 @@ export async function sendPlainNotification(tenant, workspace, msg) {
         if (config.email) {
             const mail = notifyMail(tenant);
             if (!mail)
-                return false;
+                return no;
             const r = await sendMail({
                 tenant,
                 mail,
@@ -337,16 +347,16 @@ export async function sendPlainNotification(tenant, workspace, msg) {
                 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;
+            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/dist/src/okf.js

@@ -21,7 +21,7 @@
 //     and `description:` stay exactly where they are.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.js";
 export const OKF_VERSION = "0.2";
 /** This producer's actor string, in the spec's `<producer>/<version>` form. */
 export const PRODUCER = "foldrun/0.1.0";

package/dist/src/online-checks.d.ts

@@ -0,0 +1,76 @@
+import { type ScanFile, type ScanFinding } from "./scan.ts";
+export declare const OSV_BATCH_URL = "https://api.osv.dev/v1/querybatch";
+export interface Pin {
+    ecosystem: "PyPI" | "npm";
+    name: string;
+    version: string;
+    /** As written, e.g. requests==2.19.0. */
+    spec: string;
+    file: string;
+    line?: number;
+}
+/** One source's outcome: checked (its findings are complete), or not. */
+export interface SourceResult {
+    /** "osv", or "mcp:<declaring file>#<server>" — two files may name a server alike. */
+    source: string;
+    /** True only when its findings are complete. */
+    checked: boolean;
+    /** Not complete, but what it did read is real (a cap, a paged answer). */
+    partial?: boolean;
+    /** Not reached because the caller's deadline ran out first. */
+    skipped?: boolean;
+    /** Why not, or what was incomplete. */
+    problem?: string;
+}
+/** An online finding, carrying the source it came from — the rescan's identity
+ *  for it, never parsed back out of the message (Codex review). */
+export type OnlineFinding = ScanFinding & {
+    source: string;
+};
+export interface OnlineResult {
+    findings: OnlineFinding[];
+    /** What could not be checked, in words. */
+    problems: string[];
+    sources: SourceResult[];
+}
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+/** An exact pin: pip `name==1.2.3` (extras allowed), npm `name@1.2.3` or `@scope/name@1.2.3`. */
+export declare function parsePin(spec: string): Omit<Pin, "file" | "line" | "spec"> | null;
+/** Every exact pin in the workspace's runtime: blocks (agents, AGENTS.md, tools). */
+export declare function exactPins(files: ScanFile[]): Pin[];
+/** Ask OSV about every exact pin, once each, in one batch; findings fan out to every file that declares it. */
+export declare function vulnerabilityFindings(files: ScanFile[], fetchImpl?: Fetch, deadline?: number): Promise<OnlineResult>;
+export interface RemoteMcp {
+    name: string;
+    url: string;
+    /** Configured headers or a URL that may carry a credential: never probed. */
+    needsCredential: boolean;
+    file: string;
+    line?: number;
+}
+/** MCP servers declared by URL — in an agent's mcpServers: or a tool with transport: mcp. */
+export declare function remoteMcpServers(files: ScanFile[]): RemoteMcp[];
+/** initialize → notifications/initialized → tools/list (every page, within limits), anonymously. */
+export declare function mcpTools(url: string, fetchImpl: Fetch, deadline?: number): Promise<{
+    tools: {
+        name: string;
+        text: string;
+    }[];
+    incomplete?: string;
+} | {
+    problem: string;
+}>;
+/** Every URL-reached MCP server's tool text, through the content rules as untrusted text. */
+export declare function mcpDescriptionFindings(files: ScanFile[], opts?: {
+    fetch?: Fetch;
+    deadline?: number;
+    order?: string[];
+}): Promise<OnlineResult>;
+/** Both, as one answer. */
+export declare function onlineFindings(files: ScanFile[], opts?: {
+    fetch?: Fetch;
+    osvFetch?: Fetch;
+    deadline?: number;
+    order?: string[];
+}): Promise<OnlineResult>;
+export {};