@foldrun/core 2.4.0 → 2.6.0

package/src/runs-filter.ts

@@ -0,0 +1,88 @@
+// Search over runs (FOL-72 step 9): one filter for the runs API, the runs
+// pages and `foldrun runs`, read off the run index — the tools each step
+// called, its tool errors, its agent and model, tokens and how long it took.
+// Pure.
+
+export interface RunFilter {
+  /** A step called a tool whose name contains this (`web`, `crm_export`). */
+  tool?: string;
+  /** A tool call errored. */
+  toolError?: boolean;
+  /** A step was this agent. */
+  agent?: string;
+  /** A step ran a model whose name contains this (`haiku`, `opus`). */
+  model?: string;
+  /** The run read at least this many input tokens, all steps together. */
+  minTokens?: number;
+  /** The run took at least this many seconds. */
+  minSecs?: number;
+}
+
+/** The query parameters a filter comes from: tool, tool_error, agent,
+ *  model, min_tokens, min_secs. Unreadable numbers are refused in words. */
+export function parseRunFilter(q: { get(name: string): string | null }): { filter: RunFilter; problems: string[] } {
+  const filter: RunFilter = {};
+  const problems: string[] = [];
+  const text = (k: string) => q.get(k)?.trim() || undefined;
+  const tool = text("tool");
+  if (tool) filter.tool = tool.toLowerCase();
+  const te = text("tool_error");
+  if (te) filter.toolError = te === "1" || te === "true" || te === "yes";
+  const agent = text("agent");
+  if (agent) filter.agent = agent;
+  const model = text("model");
+  if (model) filter.model = model.toLowerCase();
+  for (const [k, field] of [["min_tokens", "minTokens"], ["min_secs", "minSecs"]] as const) {
+    const v = text(k);
+    if (v === undefined) continue;
+    // "50k" and "1.5k" are thousands (Codex review: "1.5k" read as 1.5).
+    const kilo = /^(\d+(?:\.\d+)?)k$/i.exec(v);
+    const n = kilo ? Number(kilo[1]) * 1000 : Number(v);
+    if (!Number.isFinite(n) || n < 0) problems.push(`${k} is a number (${k === "min_tokens" ? "50000 or 50k" : "seconds"}), not ${v}`);
+    else filter[field] = n;
+  }
+  return { filter, problems };
+}
+
+export const isEmptyFilter = (f: RunFilter) => Object.keys(f).length === 0;
+
+type FilterableStep = {
+  agent: string;
+  model?: string;
+  tools?: string[];
+  toolErrors?: number;
+  /** A whole record has events instead of the index's tools/toolErrors. */
+  events?: { type: string; text: string; ms?: number; err?: boolean }[];
+  tokens?: { input?: number } | null;
+  startedAt?: string;
+  finishedAt?: string;
+};
+type FilterableRun = { startedAt: string; finishedAt?: string | null; steps: FilterableStep[] };
+
+/** The index's facts, or worked out from a whole record's events (Codex
+ *  review: the workspace runs page reads whole records). */
+function factsOf(s: FilterableStep): { tools: string[]; toolErrors: number } {
+  if (s.tools !== undefined || s.toolErrors !== undefined || !s.events) return { tools: s.tools ?? [], toolErrors: s.toolErrors ?? 0 };
+  const tools = new Set<string>();
+  let errs = 0;
+  for (const e of s.events) {
+    if (e.type !== "tool") continue;
+    if (e.ms == null) tools.add(e.text);
+    else if (e.err) errs++;
+  }
+  return { tools: [...tools], toolErrors: errs };
+}
+
+export function matchesRunFilter(run: FilterableRun, f: RunFilter, now = Date.now()): boolean {
+  const steps = (run.steps ?? []).map((s) => ({ ...s, ...factsOf(s) }));
+  if (f.tool && !steps.some((s) => (s.tools ?? []).some((t) => t.toLowerCase().includes(f.tool!)))) return false;
+  if (f.toolError !== undefined && steps.some((s) => (s.toolErrors ?? 0) > 0) !== f.toolError) return false;
+  if (f.agent && !steps.some((s) => s.agent === f.agent)) return false;
+  if (f.model && !steps.some((s) => (s.model ?? "").toLowerCase().includes(f.model!))) return false;
+  if (f.minTokens !== undefined && steps.reduce((n, s) => n + (s.tokens?.input ?? 0), 0) < f.minTokens) return false;
+  if (f.minSecs !== undefined) {
+    const secs = ((run.finishedAt ? Date.parse(run.finishedAt) : now) - Date.parse(run.startedAt)) / 1000;
+    if (!(secs >= f.minSecs)) return false;
+  }
+  return true;
+}

package/src/scan.ts

@@ -27,7 +27,7 @@
 // reported, because "why is this allowed?" is the question a reviewer asks.
 
 import crypto from "node:crypto";
-import matter from "gray-matter";
+import matter, { frontmatterErrorLine, frontmatterErrorText, parseLenient, configMatter } from "./matter.ts";
 import { refNames } from "./refs.ts";
 import { resolveNetwork } from "./network.ts";
 import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.ts";
@@ -62,6 +62,10 @@ export interface ScanFinding {
   message: string;
   /** Stable across edits elsewhere in the file: rule + file + line text. */
   fingerprint: string;
+  /** This rule had more to say in this file than PER_FILE_RULE: this
+   *  finding counts the rest, so what is not listed is not resolved. Its
+   *  fingerprint is of everything it counts, so a change among them is new. */
+  truncated?: true;
 }
 
 export interface ScanOptions {
@@ -173,6 +177,26 @@ export const SCAN_RULES: readonly ScanRule[] = [
       "so a run tomorrow uses what was tested today.",
     owasp: ["ASI04"],
   },
+  {
+    id: "supply-chain/known-vulnerability",
+    category: "supply-chain",
+    level: "warn",
+    title: "A pinned runtime package with known vulnerabilities",
+    help:
+      "OSV.dev lists vulnerabilities for this exact version. Upgrade to a fixed one. An online check: `foldrun check --to <ws> --online`, " +
+      "Checks → Check online, and the daily rescan.",
+    owasp: ["ASI04"],
+  },
+  {
+    id: "content/mcp-tool-text",
+    category: "content",
+    level: "warn",
+    title: "An MCP server's tool text carries hidden or injected instructions",
+    help:
+      "What a remote MCP server says about its tools reaches the model as instructions. Hidden characters or an order in a tool " +
+      "description is a server steering your agent. An online check, for servers reached by URL; a command server is never run to check it.",
+    owasp: ["ASI01", "ASI04"],
+  },
   {
     id: "config/unknown-field",
     category: "config",
@@ -199,6 +223,35 @@ export const SCAN_RULES: readonly ScanRule[] = [
       "`effort: extreme`, `size: giant`, `trigger: sometimes`, a cron the scheduler cannot read: each is ignored or falls back, " +
       "so the agent or flow quietly does something else. The message lists what the field takes.",
   },
+  {
+    id: "config/conflict",
+    category: "config",
+    level: "error",
+    title: "A field set twice: at the top and inside its job block",
+    help:
+      "`limits:` at the top and `limits:` inside `guardrail:` cannot both be meant. The top one would be read and the other " +
+      "quietly ignored, so the file is refused until one is removed.",
+  },
+  {
+    id: "config/misplaced",
+    category: "config",
+    level: "error",
+    title: "A field inside the wrong job block",
+    help:
+      "Each of the four blocks (governance, guardrail, observability, evaluation) holds its own fields. A setting written in " +
+      "another block is not read — a guardrail under governance: guards nothing — so the file is refused until it is moved " +
+      "to the block the message names, or to the top. A word foldrun does not read at all is only a note.",
+  },
+  {
+    id: "config/invalid-frontmatter",
+    category: "config",
+    level: "warn",
+    title: "Frontmatter that YAML cannot read",
+    help:
+      "A value with a colon followed by a space (`description: the format (Markdown, ::: directives)`) ends the YAML. " +
+      "foldrun reads a skill like that by quoting the value, but the dashboard editor and the source API refuse to save it, " +
+      "and other tools that read the file may not. Quote the value: `description: \"…\"`.",
+  },
   {
     id: "config/missing-field",
     category: "config",
@@ -451,13 +504,15 @@ const INJECTION: RegExp[] = [
 
 const BLOB = /[A-Za-z0-9+/]{300,}={0,2}/g;
 
-function scanContent(file: ScanFile, lines: string[], push: Push) {
-  const md = /\.md$/i.test(file.path);
-  const data = isDataDoc(file.path);
+function scanContent(file: ScanFile, lines: string[], push: Push, untrusted = false) {
+  // Untrusted text (a remote server's) is read as data, every line: it
+  // cannot fence an order off as an "example" either.
+  const md = untrusted || /\.md$/i.test(file.path);
+  const data = untrusted || isDataDoc(file.path);
   let fenced = false;
   for (let i = 0; i < lines.length; i++) {
     const line = i === 0 ? lines[i]!.replace(/^/, "") : lines[i]!;
-    if (/^\s*(?:```|~~~)/.test(line)) fenced = !fenced;
+    if (!untrusted && /^\s*(?:```|~~~)/.test(line)) fenced = !fenced;
     HIDDEN.lastIndex = 0;
     if (HIDDEN.test(line)) {
       const kind = HIDDEN_NAMES.find(([re]) => re.test(line))?.[1] ?? "invisible characters";
@@ -481,6 +536,18 @@ function scanContent(file: ScanFile, lines: string[], push: Push) {
   }
 }
 
+/**
+ * Text from outside the workspace — what a remote MCP server says about its
+ * tools — through the content rules with nothing the text itself can turn
+ * off: no foldrun-ignore, no binary or vendored-path skip, no fences
+ * (FOL-58, Codex review: each of those let a server silence its own finding).
+ */
+export function untrustedTextFindings(text: string): { rule: string; line: number; message: string }[] {
+  const out: { rule: string; line: number; message: string }[] = [];
+  scanContent({ path: "untrusted", content: text }, text.split(/\r?\n/), (rule, _file, line, _text, message) => out.push({ rule, line: line ?? 0, message }), true);
+  return out;
+}
+
 /** The text hidden in tag characters: each is U+E0000 + an ASCII code. */
 function decodeTags(s: string): string {
   let out = "";
@@ -563,17 +630,31 @@ export function nearestField(key: string, known: readonly string[]): string | nu
 }
 
 function keyLine(lines: string[], key: string): number | undefined {
-  const re = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:`);
-  const i = lines.findIndex((l) => re.test(l));
-  return i >= 0 ? i + 1 : undefined;
+  const k = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const top = new RegExp(`^${k}\\s*:`);
+  const i = lines.findIndex((l) => top.test(l));
+  if (i >= 0) return i + 1;
+  // A key inside one of the four job blocks: indented, under its header.
+  const inner = new RegExp(`^\\s+${k}\\s*:`);
+  let inBlock = false;
+  for (let n = 0; n < lines.length; n++) {
+    const l = lines[n]!;
+    if (/^(governance|guardrail|observability|evaluation)\s*:\s*(#.*)?$/.test(l)) inBlock = true;
+    else if (/^\S/.test(l)) inBlock = false;
+    else if (inBlock && inner.test(l)) return n + 1;
+  }
+  return undefined;
 }
 
 /** Read-only: gray-matter caches by content, so two files with the same
  *  text share one object, and writing to it would leak between them. */
-function frontOf(content: string): Record<string, unknown> | null {
+function frontOf(content: string, filePath?: string): Record<string, unknown> | null {
   if (!/^?---\r?\n/.test(content)) return null;
   try {
-    return matter(content).data as Record<string, unknown>;
+    // An agent, a flow or AGENTS.md reads its job blocks as flat keys, as
+    // the runtime does; every other document is read as written.
+    const kind = filePath ? schemaKindOf(filePath) : null;
+    return (kind === "agent" || kind === "flow" || kind === "agents-md" ? configMatter(content) : matter(content)).data as Record<string, unknown>;
   } catch {
     return null; // a frontmatter YAML cannot read is check's finding, not ours
   }
@@ -735,6 +816,16 @@ const VENDORED = /(?:^|\/)(?:node_modules|\.venv|venv|site-packages|__pycache__|
  *  since a key in a log here is a key in the workspace (seen live on
  *  17 Oct 2026: zero-width characters in a CLI MCP log, reported as hidden
  *  text). */
+/** The definition files a deploy refuses outright when their frontmatter does
+ *  not parse (deploy.ts deployIssues): the workspace's own, by these paths.
+ *  Everything else the platform reads frontmatter from — skills, and the
+ *  account library's agents, tools and hooks — is the scanner's to report. */
+export const STRICT_FRONTMATTER_PATH = /^(AGENTS\.md|agents\/[^/]+\/agent\.md|flows\/[^/]+\.md|tools\/[^/]+\.md|tools\/[^/]+\/tool\.md|evals\/[^/]+\.md|hooks\/[^/]+\/hook\.md|\.claude\/agents\/[^/]+\.md)$/;
+
+/** A skill file in either layout the runtime discovers: <name>/SKILL.md, or
+ *  the flat <name>.md, under skills/ or .agents/skills/, in the library too. */
+const SKILL_FILE = /(?:^|\/)skills\/(?:[^/]+\/SKILL\.md|[^/]+\.md)$/;
+
 const RUNTIME_WRITTEN = /(?:^|\/)(?:\.cache|\.npm|\.local|\.pnpm-store|\.yarn|\.foldrun)\//;
 
 /** Text files only — a PNG read as UTF-8 is noise to every rule here. */
@@ -742,9 +833,13 @@ function isText(f: ScanFile): boolean {
   return !VENDORED.test(f.path) && !f.content.slice(0, 8000).includes("\u0000") && !/\.(?:png|jpe?g|gif|webp|ico|pdf|zip|gz|woff2?|ttf|mp[34]|mov|wasm)$/i.test(f.path);
 }
 
+/** How many times one rule is listed for one file before the rest are counted. */
+export const PER_FILE_RULE = 100;
+
 /**
  * Every finding in these files, ignores applied. Findings are sorted by file
- * then line, and one rule says one thing once per line.
+ * then line, and one rule says one thing once per line, and at most
+ * PER_FILE_RULE times in one file.
  */
 export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFinding[] {
   const want = options.only?.length ? new Set(options.only) : null;
@@ -752,6 +847,11 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
   const findings: ScanFinding[] = [];
   const seen = new Set<string>();
   const ignoresByFile = new Map<string, Ignores>();
+  // One rule in one file says it PER_FILE_RULE times, then counts the rest:
+  // a million lines of hidden characters is one problem, not a million
+  // findings held in memory (Codex review of the 20 Oct rescan outage).
+  const perFileRule = new Map<string, number>();
+  const more = new Map<string, { rule: string; file: string; level?: ScanFinding["level"]; n: number; hash: crypto.Hash }>();
 
   const push: Push = (rule, file, line, text, message, level) => {
     if (!enabled(rule)) return;
@@ -759,6 +859,16 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
     if (ig && ignored(ig, rule, line)) return;
     const key = `${rule}\0${file}\0${line ?? ""}\0${message}`;
     if (seen.has(key)) return;
+    const rf = `${rule}\0${file}`;
+    const said = perFileRule.get(rf) ?? 0;
+    if (said >= PER_FILE_RULE) {
+      const m = more.get(rf) ?? { rule, file, level, n: 0, hash: crypto.createHash("sha256") };
+      m.n++;
+      m.hash.update(`${findingFingerprint(rule, file, text)}\0`);
+      more.set(rf, m);
+      return;
+    }
+    perFileRule.set(rf, said + 1);
     seen.add(key);
     findings.push({ rule, level: level ?? scanRule(rule)?.level ?? "warn", file, ...(line ? { line } : {}), message, fingerprint: findingFingerprint(rule, file, text) });
   };
@@ -776,9 +886,34 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
     scanSupplyChain(f, lines, push);
 
     const schema = schemaKindOf(f.path);
+    // Frontmatter YAML cannot read. Until 2026-10-21 nothing reported it for
+    // a skill or a library file: frontOf below reads it as "no frontmatter"
+    // and moves on, and the deploy's own refusal covers only the workspace's
+    // definition files. A vaza.ai skill with `description: … (Markdown,
+    // frontmatter, ::: directives) …` deployed clean, ran (the runtime quotes
+    // the value and retries), and was refused by the source API on its next
+    // save.
+    if ((schema || SKILL_FILE.test(f.path)) && !STRICT_FRONTMATTER_PATH.test(f.path) && /^\uFEFF?---\r?\n/.test(f.content)) {
+      let err: unknown = null;
+      try {
+        matter(f.content);
+      } catch (e) {
+        err = e;
+      }
+      if (err) {
+        const isSkill = schema === "skill" || SKILL_FILE.test(f.path);
+        const read = parseLenient(f.content);
+        const what = isSkill && !read.failed
+          ? "foldrun reads this skill anyway by quoting the value, but the dashboard editor and the source API refuse to save it, and other skills clients may not load it"
+          : isSkill
+            ? "the runtime reads it as empty, so the skill has no name or description and is never loaded"
+            : "the runtime cannot read this file";
+        push("config/invalid-frontmatter", f.path, frontmatterErrorLine(err), `config/invalid-frontmatter ${frontmatterErrorText(err)}`, `${frontmatterErrorText(err)} ${what === "the runtime cannot read this file" ? "The runtime cannot read this file" : what.replace(/^foldrun/, "foldrun").replace(/^the/, "The")}.`);
+      }
+    }
     // A skill with no frontmatter at all is the clearest one that never
     // loads: read it as empty, so its required fields are reported.
-    const data = schema || docKind(f.path) ? (frontOf(f.content) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
+    const data = schema || docKind(f.path) ? (frontOf(f.content, f.path) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
     if (!data) continue;
     if (schema) {
       for (const p of frontmatterProblems(schema, data, nearestField)) {
@@ -800,8 +935,12 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
       toolDefs.set(f.path, { data, lines });
     }
   }
-  const workspaceMd = files.find((f) => f.path === "AGENTS.md");
-  scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content)?.network : undefined });
+  // project.md is the older name the runtime still reads (Codex review, FOL-58).
+  const workspaceMd = files.find((f) => f.path === "AGENTS.md") ?? files.find((f) => f.path === "project.md");
+  scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content, "AGENTS.md")?.network : undefined });
+  for (const m of more.values()) {
+    findings.push({ rule: m.rule, level: m.level ?? scanRule(m.rule)?.level ?? "warn", file: m.file, message: `and ${m.n} more like this in this file, not listed`, fingerprint: m.hash.digest("hex").slice(0, 16), truncated: true });
+  }
 
   return findings.sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule));
 }

package/src/starter.ts

@@ -62,6 +62,22 @@ foldrun_version: "0.1"
 #
 # The token is sent as a bearer credential. A gateway that wants it as a key
 # header asks for that by name: headers: { x-api-key: \${THE_SECRET} }.
+#
+# The four jobs of running agents, each a block — or write the same keys at
+# the top; one place or the other, never both:
+#
+# governance:          # who answers for it, what it may spend and ship
+#   owner: you@example.com
+#   budget: 60/month
+#   deploy_block: secrets
+# guardrail:           # what agents may reach and call
+#   limits: {calls: 300, repeat: 5}
+#   network: trusted
+# observability:       # what is recorded, and who is told
+#   notify: {email: you@example.com, events: [failed]}
+#   alerts: {failure_rate: 30%}
+# evaluation:          # how work is judged
+#   judge: {model: fast}
 ---
 
 # ${account}
@@ -373,7 +389,7 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/assistant\` | POST | ask the assistant, or have it write agents, flows, tools and skills — from the docs only; proposals come back, nothing is written |
 
 Account-level, outside \`/workspaces\`: \`/api/secrets\`, \`/api/keys\`, \`/api/schedule\`,
-\`/api/approvals\`, \`/api/usage\`, \`/api/library/<kind>\`, \`/api/team\`, \`/api/billing\`,
+\`/api/approvals\`, \`/api/issues\` (what went wrong, open until resolved), \`/api/usage\`, \`/api/library/<kind>\`, \`/api/team\`, \`/api/billing\`,
 \`/api/me/notifications\` (what mail you get; a key acts for whoever minted it),
 \`/api/account/backups\` (snapshots, restore requests), \`/api/me/onboarding\` (getting started),
 \`/api/healthz\` and \`/api/version\` (open), \`/api/changelog\` (release notes)
@@ -407,6 +423,7 @@ subflow), \`foldrun flow rm-step\` removes a step, and \`foldrun agent link
 trigger: manual          # manual | schedule | webhook
 schedule: "0 9 * * 1"    # cron, when trigger: schedule
 timezone: Australia/Sydney
+owner: ana@example.com   # who answers for it; else the workspace's, else the account's
 model: default           # a default for every step here
 effort: low
 overlap: skip            # skip | queue — what a second run does while one is live
@@ -464,10 +481,11 @@ by a model: what this role is for, what it must not do, what good looks like.
 ---
 name: researcher
 description: Finds and summarises sources.
+owner: ana@example.com      # who answers for it; else the workspace's, else the account's
 model: default              # fast | default | max
 effort: low                 # how hard to think about it
 size: large                 # small | large | heavy — the sandbox it rents
-tools: [web, read, ask, my-folder-tool]  # built-ins and your own tools/, one list; \`ask\` lets it ask you mid-step
+tools: [web, read, ask, peers, my-folder-tool]  # built-ins and your own tools/, one list; \`ask\` lets it ask you mid-step, \`peers\` lets it message the steps running beside it
 disallowedTools: [Bash]     # subtract from what it would otherwise have
 skills: [house-style]       # from skills/
 hooks: [no-force-push]      # from hooks/ or the library: code at every tool call
@@ -490,6 +508,13 @@ runtime:                    # only if scripts need packages
 You research a topic and report what you found...
 \`\`\`
 
+The fields that do one of the four jobs of running agents may be grouped
+under it — \`governance:\` (owner, budget), \`guardrail:\` (limits, network,
+hooks, disallowedTools, permissionMode, secrets), and in AGENTS.md also
+\`observability:\` (alerts, telemetry, notify, capture) and \`evaluation:\`
+(judge). A block reads exactly as the same keys at the top; a key written
+both ways is refused (\`config/conflict\`). \`foldrun docs four-jobs\`.
+
 Only \`name\` and the prose are required. Every other field widens or narrows
 what the agent can reach, and the default is narrow.