@foldrun/core 2.4.0 → 2.5.0

package/dist/src/limits.js

@@ -6,6 +6,7 @@
 //     web: 150            # every web action together
 //     crm: 20             # an API, script or MCP tool, by the name it is granted as
 //     calls: 300          # every tool call in the step, whatever the tool
+//     repeat: 5           # the same call — one tool, the same input — at most this often
 //
 // Counted per step and enforced in step-exec.ts's PreToolUse hook — the one
 // place every call passes, the step's own and its sub-agents', on the
@@ -17,10 +18,27 @@
 //
 // Nearest wins per key: the account's AGENTS.md, then the workspace's, then
 // the agent's own `limits:`, then a flow step's `limits:` option.
+import crypto from "node:crypto";
 import { WEB_ACTIONS } from "./providers.js";
 import { DELEGATE_TOOLS } from "./subagents.js";
 /** The key that caps every call in the step. */
 export const TOTAL_KEY = "calls";
+/** The key that caps one identical call: a model asking the same tool the
+ *  same thing over and over is stuck, and every repeat is spend. Each call
+ *  also counts under `repeat:<hash of tool and input>`; `repeat: N` caps
+ *  every one of those. */
+export const REPEAT_KEY = "repeat";
+/** JSON with its keys sorted, so `{a,b}` and `{b,a}` are the same call. */
+function stable(v) {
+    if (Array.isArray(v))
+        return `[${v.map(stable).join(",")}]`;
+    if (v && typeof v === "object")
+        return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${stable(v[k])}`).join(",")}}`;
+    return JSON.stringify(v) ?? "null";
+}
+function repeatKey(toolName, input) {
+    return `${REPEAT_KEY}:${crypto.createHash("sha1").update(`${toolName}\0${stable(input ?? {})}`).digest("hex").slice(0, 16)}`;
+}
 /** SDK built-ins, counted under the foldrun group that grants them — and
  *  under their own SDK name, so `Bash: 5` works for a Claude Code file. */
 const BUILTIN_GROUP = {
@@ -36,6 +54,7 @@ const PLATFORM_SERVERS = {
     foldrun_history: "history",
     foldrun_desks: "desks",
     foldrun_ask: "ask",
+    foldrun_peers: "peers",
 };
 /** One spelling for comparing: `desk-email` and `desk_email` are the same
  *  tool (a script tool's SDK name has its dashes made underscores). */
@@ -72,7 +91,7 @@ export function readLimits(raw, where = "limits") {
     for (const [key, value] of flat) {
         const k = key.trim();
         if (!KEY_RE.test(k)) {
-            problems.push(`${where}: "${k}" is not a key — a tool's name, web.<action>, or calls.`);
+            problems.push(`${where}: "${k}" is not a key — a tool's name, web.<action>, calls, or repeat.`);
             continue;
         }
         if (k.includes(".")) {
@@ -169,6 +188,11 @@ export function limitKeysFor(toolName, input, owners = {}) {
     keys.push(toolName);
     return keys;
 }
+/** What step-exec counts one call under: limitKeysFor's keys and the
+ *  call's own `repeat:` key, for `limits: repeat`. */
+export function callKeysFor(toolName, input, owners = {}) {
+    return [...limitKeysFor(toolName, input, owners), repeatKey(toolName, input)];
+}
 /**
  * One step's counts. `take` checks every key the call counts under and
  * either refuses — counting nothing — or counts it under all of them.
@@ -187,7 +211,8 @@ export class CallCounter {
     take(keys) {
         const norm = [...new Set(keys.map(normKey))];
         for (const k of norm) {
-            const l = this.limits.get(k);
+            const repeat = k.startsWith(`${REPEAT_KEY}:`);
+            const l = this.limits.get(repeat ? REPEAT_KEY : k);
             if (!l)
                 continue;
             const used = this.used.get(k) ?? 0;
@@ -195,7 +220,9 @@ export class CallCounter {
                 this.refused++;
                 return {
                     key: l.key, used, limit: l.limit,
-                    message: `limit reached: ${l.key} ${used} of ${l.limit} in this step — work with what you have, or say what more you would need`,
+                    message: repeat
+                        ? `limit reached: this exact call (same tool, same input) ${used} of ${l.limit} times in this step — repeating it will not change the answer; try something different, or say what is stuck`
+                        : `limit reached: ${l.key} ${used} of ${l.limit} in this step — work with what you have, or say what more you would need`,
                 };
             }
         }
@@ -218,7 +245,11 @@ export class CallCounter {
     summary() {
         if (!this.active)
             return null;
-        const parts = [...this.limits.entries()].map(([k, l]) => `${l.key} ${this.used.get(k) ?? 0}/${l.limit}`);
+        // repeat: the most any one call was made, against its cap.
+        const most = (k) => k === REPEAT_KEY
+            ? Math.max(0, ...[...this.used.entries()].filter(([u]) => u.startsWith(`${REPEAT_KEY}:`)).map(([, n]) => n))
+            : this.used.get(k) ?? 0;
+        const parts = [...this.limits.entries()].map(([k, l]) => `${l.key} ${most(k)}/${l.limit}`);
         return `limits: ${parts.join(", ")}${this.refused ? ` — ${this.refused} call${this.refused === 1 ? "" : "s"} refused` : ""}`;
     }
 }
@@ -248,7 +279,7 @@ export function limitKeyProblems(limits, ctx) {
         return [n];
     }).map(normKey));
     for (const key of Object.keys(limits)) {
-        if (key === TOTAL_KEY)
+        if (key === TOTAL_KEY || key === REPEAT_KEY)
             continue;
         const base = key.startsWith("web.") ? "web" : key;
         const n = normKey(base);

package/dist/src/linkable.js

@@ -13,7 +13,7 @@
 // real workspace, so a future rename fails a test instead of a run.
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.js";
 import { STORAGE_DIR } from "./store.js";
 /** The directories a bare [[name]] may point at, matching the resolver. */
 export const LINKABLE_DIRS = [STORAGE_DIR, "state", "knowledge", "memory", "skills", "outputs"];

package/dist/src/matter.d.ts

@@ -0,0 +1,8 @@
+import grayMatter from "gray-matter";
+type Options = NonNullable<Parameters<typeof grayMatter>[1]>;
+declare function matter(input: string, options?: Options): grayMatter.GrayMatterFile<string>;
+declare namespace matter {
+    var stringify: typeof grayMatter.stringify;
+    var test: typeof grayMatter.test;
+}
+export default matter;

package/dist/src/matter.js

@@ -0,0 +1,28 @@
+// 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";
+function matter(input, options) {
+    return grayMatter(input, options ?? {});
+}
+matter.stringify = grayMatter.stringify;
+matter.test = grayMatter.test;
+export default matter;

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

@@ -74,6 +74,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

@@ -233,12 +233,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 = [];

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 {};