@foldrun/core 2.3.0 → 2.5.0

package/src/limits.ts

@@ -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
@@ -18,6 +19,7 @@
 // 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.ts";
 import { DELEGATE_TOOLS } from "./subagents.ts";
 
@@ -26,6 +28,23 @@ export type Limits = Record<string, number>;
 /** 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: unknown): string {
+  if (Array.isArray(v)) return `[${v.map(stable).join(",")}]`;
+  if (v && typeof v === "object") return `{${Object.keys(v as object).sort().map((k) => `${JSON.stringify(k)}:${stable((v as Record<string, unknown>)[k])}`).join(",")}}`;
+  return JSON.stringify(v) ?? "null";
+}
+
+function repeatKey(toolName: string, input: Record<string, unknown> | undefined): string {
+  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: Record<string, string> = {
@@ -43,6 +62,7 @@ const PLATFORM_SERVERS: Record<string, string> = {
   foldrun_history: "history",
   foldrun_desks: "desks",
   foldrun_ask: "ask",
+  foldrun_peers: "peers",
 };
 
 /** One spelling for comparing: `desk-email` and `desk_email` are the same
@@ -78,7 +98,7 @@ export function readLimits(raw: unknown, where = "limits"): { limits: Limits; pr
   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(".")) {
@@ -166,6 +186,12 @@ export function limitKeysFor(toolName: string, input: Record<string, unknown> |
   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: string, input: Record<string, unknown> | undefined, owners: Record<string, string> = {}): string[] {
+  return [...limitKeysFor(toolName, input, owners), repeatKey(toolName, input)];
+}
+
 export interface LimitRefusal {
   key: string;
   used: number;
@@ -193,14 +219,17 @@ export class CallCounter {
   take(keys: string[]): LimitRefusal | null {
     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;
       if (used >= l.limit) {
         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`,
         };
       }
     }
@@ -223,7 +252,11 @@ export class CallCounter {
   /** `limits: web.search 40/40, crm 3/20` — null when no limits are set. */
   summary(): string | null {
     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: string) => 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` : ""}`;
   }
 }
@@ -253,7 +286,7 @@ export function limitKeyProblems(
     return [n];
   }).map(normKey));
   for (const key of Object.keys(limits)) {
-    if (key === TOTAL_KEY) continue;
+    if (key === TOTAL_KEY || key === REPEAT_KEY) continue;
     const base = key.startsWith("web.") ? "web" : key;
     const n = normKey(base);
     if (!known.has(n)) {

package/src/linkable.ts

@@ -14,7 +14,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import matter from "gray-matter";
+import matter from "./matter.ts";
 
 import { STORAGE_DIR } from "./store.ts";
 

package/src/matter.ts

@@ -0,0 +1,33 @@
+// 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";
+
+type Options = NonNullable<Parameters<typeof grayMatter>[1]>;
+
+function matter(input: string, options?: Options) {
+  return grayMatter(input, options ?? {});
+}
+matter.stringify = grayMatter.stringify;
+matter.test = grayMatter.test;
+
+export default matter;

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/model-env.ts

@@ -11,6 +11,8 @@ import { readAgentsMd } from "./runner.ts";
 import { getSecret } from "./secrets.ts";
 import { platform } from "./platform.ts";
 import { accountModelBlock, isClaudeLoginToken } from "./model-credential.ts";
+import { providerPreset } from "./providers.ts";
+import { startTranslator, translatorSpecFor, type TranslatorSpec } from "./translator.ts";
 
 /** Refused for want of a usable key; `status` is what an HTTP layer answers. */
 export class ModelKeyError extends Error {
@@ -28,14 +30,20 @@ export const NO_MODEL_KEY =
 /**
  * `platform` is a function: the caller's own way to build the platform's env
  * (a step's, or the SDK's host env), called only when this account may use
- * it. `format` says what the endpoint speaks — a caller with no translator
- * refuses anything but anthropic.
+ * it. `format` says what the endpoint speaks; `translator` is set when it is
+ * not Anthropic's, and `withModelEnv` puts the step's translator in front of
+ * it, so a judge or a draft works on any key a run works on (FOL-16).
  */
 export function accountModelEnv(
   tenant: string,
   workspace: string,
   platformEnv: () => Record<string, string | undefined>,
-): { env: Record<string, string | undefined>; supply: "provider" | "platform"; format: string } {
+): {
+  env: Record<string, string | undefined>;
+  supply: "provider" | "platform";
+  format: string;
+  translator: TranslatorSpec | null;
+} {
   const raw =
     (readAgentsMd(workspaceDir(tenant, workspace))?.data?.provider as Record<string, unknown> | undefined) ??
     (readAgentsMd(accountDir(tenant))?.data?.provider as Record<string, unknown> | undefined) ??
@@ -43,7 +51,7 @@ export function accountModelEnv(
   const spec = parseProvider(raw);
   if (!spec?.baseUrl) {
     if (!platform.platformKeyAllowed(tenant)) throw new ModelKeyError(NO_MODEL_KEY);
-    return { env: platformEnv(), supply: "platform", format: "anthropic" };
+    return { env: platformEnv(), supply: "platform", format: "anthropic", translator: null };
   }
   const sub = (text: string) =>
     text.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => getSecret(tenant, name, workspace)?.value ?? whole);
@@ -52,15 +60,39 @@ export function accountModelEnv(
   if (!platform.platformKeyAllowed(tenant) && isClaudeLoginToken(token)) {
     throw new ModelKeyError("model key: a Claude login token (sk-ant-oat…) cannot be used here — use an API key from your provider", 422);
   }
+  const headers = Object.fromEntries(Object.entries(spec.headers).map(([k, v]) => [k, sub(v)]));
+  const preset = providerPreset(spec.name);
   return {
-    env: providerEnvFor({
+    env: providerEnvFor({ baseUrl: spec.baseUrl, token, auth: spec.auth, models: spec.models, headers }),
+    supply: "provider",
+    format: spec.format,
+    translator: translatorSpecFor({
+      format: spec.format,
       baseUrl: spec.baseUrl,
       token,
-      auth: spec.auth,
-      models: spec.models,
-      headers: Object.fromEntries(Object.entries(spec.headers).map(([k, v]) => [k, sub(v)])),
+      headers,
+      params: spec.params,
+      name: spec.name,
+      maxTokensParam: preset?.maxTokensParam,
+      reasoningEffort: preset?.reasoningEffort,
     }),
-    supply: "provider",
-    format: spec.format,
   };
 }
+
+/**
+ * Run `fn` with the model env, through a translator on this host when the
+ * provider speaks Chat Completions or Responses — the same one a step uses
+ * (runner.ts), started for this call and closed after it.
+ */
+export async function withModelEnv<T>(
+  m: { env: Record<string, string | undefined>; translator?: TranslatorSpec | null },
+  fn: (env: Record<string, string | undefined>) => Promise<T>,
+): Promise<T> {
+  if (!m.translator) return fn(m.env);
+  const t = await startTranslator(m.translator);
+  try {
+    return await fn({ ...m.env, ...t.env });
+  } finally {
+    await t.close();
+  }
+}

package/src/network.ts

@@ -268,13 +268,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)`);

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";