@foldrun/core 1.2.0 → 1.4.0

package/src/scan.ts

@@ -29,6 +29,8 @@
 import crypto from "node:crypto";
 import matter from "gray-matter";
 import { refNames } from "./refs.ts";
+import { resolveNetwork } from "./network.ts";
+import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.ts";
 
 export type ScanLevel = "error" | "warn" | "info";
 export type ScanCategory = "secret" | "security" | "content" | "supply-chain" | "config";
@@ -69,6 +71,9 @@ export interface ScanOptions {
   outwardTools?: Iterable<string>;
   /** Only these rule ids (or categories, `secret`, `security`, …). */
   only?: string[];
+  /** The account AGENTS.md's `network:` — the level above the workspace's,
+   *  which the files of one workspace do not carry. */
+  accountNetwork?: unknown;
 }
 
 export const OWASP_URL = "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026";
@@ -123,7 +128,8 @@ export const SCAN_RULES: readonly ScanRule[] = [
     title: "Reads untrusted content, holds private data and can send it out",
     help:
       "An agent with all three can be told — by any page it reads — to send what it holds anywhere it can reach. " +
-      "Take one leg away: narrow `network:` to the sites it needs, split the reading and the sending into two agents, " +
+      "Take one leg away: take it off the open network (`network: { level: trusted, allow: [the sites it needs] }` — a bare list only adds sites, " +
+      "and an agent that reads the web stays open), split the reading and the sending into two agents, " +
       "or guard its calls with a `hooks:` gate. An approval (`!`) on every outward step is the other answer.",
     owasp: ["ASI01", "ASI02", "ASI03"],
   },
@@ -171,10 +177,34 @@ export const SCAN_RULES: readonly ScanRule[] = [
     id: "config/unknown-field",
     category: "config",
     level: "warn",
-    title: "A frontmatter field foldrun does not read — likely a typo",
+    title: "A frontmatter field foldrun does not read here",
     help:
       "A misspelt field is not an error to YAML, so it is silently ignored: `tolls: [web]` leaves the agent with no tools. " +
-      "Use the field the message suggests.",
+      "A near-miss names the field it meant; a field read in another kind of file says where it belongs (warnings). " +
+      "A field like nothing foldrun reads is a note, since another tool may own it.",
+  },
+  {
+    id: "config/wrong-type",
+    category: "config",
+    level: "warn",
+    title: "A frontmatter field holding the wrong kind of value",
+    help: "A list where one name was meant, a map where a word was meant: the runtime does not read it. The message says what the field takes.",
+  },
+  {
+    id: "config/invalid-value",
+    category: "config",
+    level: "warn",
+    title: "A frontmatter value that does nothing",
+    help:
+      "`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/missing-field",
+    category: "config",
+    level: "warn",
+    title: "A required frontmatter field is missing",
+    help: "A skill with no description is never loaded: the model chooses skills by their descriptions.",
   },
   {
     id: "check/ignore-needs-reason",
@@ -329,6 +359,36 @@ export function redactSecret(secret: string): string {
   return secret.length <= 8 ? "****" : `${secret.slice(0, 4)}…${secret.slice(-2)}`;
 }
 
+/** Every credential in a piece of text, as [value, what]. One reading for
+ *  the secret rule and for any other rule that quotes the line. */
+function credentialsIn(line: string): [string, string][] {
+  const out: [string, string][] = [];
+  const seen = new Set<string>();
+  const add = (v: string, what: string) => {
+    if (!seen.has(v)) {
+      seen.add(v);
+      out.push([v, what]);
+    }
+  };
+  for (const [re, what] of SECRET_SHAPES) {
+    if (what === "a private key") continue; // a header names a key; it is not one
+    for (const m of line.matchAll(re)) {
+      if (!PLACEHOLDER.test(m[0]) && entropy(m[0]) >= 3) add(m[0], what);
+    }
+  }
+  for (const m of line.matchAll(ASSIGNED)) if (credentialLike(m[2]!)) add(m[2]!, `\`${m[1]}\` with a literal value`);
+  for (const m of line.matchAll(BEARER)) if (credentialLike(m[1]!)) add(m[1]!, "a bearer token");
+  return out;
+}
+
+/** The text with every credential in it redacted — for a finding that
+ *  quotes source, so no message ever carries a key whole. */
+export function redactText(text: string): string {
+  let out = text;
+  for (const [v] of credentialsIn(text).sort((a, b) => b[0].length - a[0].length)) out = out.split(v).join(redactSecret(v));
+  return out;
+}
+
 function scanSecrets(file: ScanFile, lines: string[], push: Push) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]!;
@@ -403,12 +463,12 @@ function scanContent(file: ScanFile, lines: string[], push: Push) {
       const kind = HIDDEN_NAMES.find(([re]) => re.test(line))?.[1] ?? "invisible characters";
       const n = line.match(HIDDEN)?.length ?? 0;
       const tagged = /\uDB40[\uDC00-\uDC7F]/.test(line) ? ` that read as: "${decodeTags(line).slice(0, 80)}"` : "";
-      push("content/hidden-unicode", file.path, i + 1, line, `${n} ${kind}${tagged} — invisible to a reviewer, read by the model`);
+      push("content/hidden-unicode", file.path, i + 1, line, `${n} ${kind}${redactText(tagged)} — invisible to a reviewer, read by the model`);
     }
     // An instruction quoted inside a fence is an example of one, not one.
     if (data && !fenced) {
       const m = INJECTION.find((re) => re.test(line));
-      if (m) push("content/injection-phrase", file.path, i + 1, line, `"${line.trim().slice(0, 90)}" — agents read this file as data, and this line reads as an order`);
+      if (m) push("content/injection-phrase", file.path, i + 1, line, `"${redactText(line.trim()).slice(0, 90)}" — agents read this file as data, and this line reads as an order`);
     }
     if (md) {
       for (const b of line.matchAll(BLOB)) {
@@ -475,29 +535,6 @@ function unpinned(pkg: string): boolean {
 
 // ── frontmatter ────────────────────────────────────────────────────────────
 
-/** What foldrun reads in an agent's frontmatter — the fields documented in
- *  agents.md, the Claude Code subagent fields an import carries, and the
- *  older spellings check already teaches about. Used only to suggest the
- *  field a typo meant: an unknown key that is nothing like any of these is
- *  left alone, since another tool may own it. */
-const AGENT_FIELDS = [
-  "name", "description", "model", "effort", "size", "tools", "disallowedTools", "skills", "hooks", "scripts",
-  "apis", "mcpServers", "agents", "subagents", "secrets", "limits", "network", "provider", "permissionMode",
-  "runtime", "ask", "web", "budget", "timezone", "language", "region", "currency", "units", "schedule", "color",
-  "memory", "foldrun_version", "use", "kind", "type", "notify", "triggers", "inputs", "outputs",
-];
-const FLOW_FIELDS = [
-  "name", "description", "trigger", "schedule", "timezone", "language", "region", "currency", "units", "model",
-  "effort", "overlap", "priority", "throttle", "debounce", "sla", "catchup", "pause_when", "disable_after",
-  "approvers", "approve_within", "notify", "at", "every", "budget", "limits", "size", "hooks", "inputs",
-  "webhook", "signing_secret", "signature", "idempotency", "filter", "after", "tags", "network", "secrets",
-];
-const TOOL_FIELDS = [
-  "name", "description", "transport", "type", "base", "methods", "headers", "query", "auth", "run", "args",
-  "command", "url", "env", "outward", "runtime", "secrets", "network", "timeout", "spec", "operations", "body",
-  "oauth", "limits", "input", "output", "schema", "kind",
-];
-
 function editDistance(a: string, b: string): number {
   const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array<number>(b.length).fill(0)]);
   for (let j = 1; j <= b.length; j++) d[0]![j] = j;
@@ -568,15 +605,13 @@ interface ToolFacts {
   lines: string[];
 }
 
-function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<string, ToolFacts>, push: Push) {
+function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<string, ToolFacts>, push: Push, networks: { account?: unknown; workspace?: unknown }) {
   const byName = new Map(agents.map((a) => [a.name, a]));
   for (const a of agents) {
     const d = a.data;
     const tools = refNames(d.tools);
     const denied = new Set(refNames(d.disallowedTools));
     const has = (t: string) => tools.includes(t) && !denied.has(t);
-    const network = d.network;
-    const netLevel = typeof network === "string" ? network : Array.isArray(network) ? "list" : network && typeof network === "object" ? "list" : null;
 
     // Untrusted: it reads the open web. (A webhook body is the other source;
     // that is a flow's trigger, and the flow-level rule is a later one.)
@@ -586,9 +621,11 @@ function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<st
     const apis = Array.isArray(d.apis) ? d.apis : [];
     const mcp = d.mcpServers && typeof d.mcpServers === "object" ? Object.keys(d.mcpServers as object) : [];
     const privateLeg = [...secrets.map((s) => `secret ${s}`), ...apis.map((x: any) => `api ${x?.name ?? "?"}`), ...mcp.map((m) => `MCP ${m}`)];
-    // Out: a sandbox open to every site (an agent that reads the web is open
-    // unless it says otherwise), a tool marked outward, or an API it may write to.
-    const openNet = netLevel === "open" || (readsWeb && netLevel === null);
+    // Out: a sandbox open to every site, a tool marked outward, or an API it
+    // may write to. The level is the runtime's own resolution — agent, then
+    // workspace, then account, and open by default for an agent that reads
+    // the web; a bare list of sites adds to a level, it does not set one.
+    const openNet = resolveNetwork({ account: networks.account, workspace: networks.workspace, agent: d.network, readsWeb }).level === "open";
     const outwardTools = tools.filter((t) => outward.has(t) && !denied.has(t));
     const writeApis = apis.filter((x: any) => WRITE_METHODS.test(JSON.stringify(x?.methods ?? x?.method ?? "")));
     const outLeg = [...(openNet ? ["an open network"] : []), ...outwardTools.map((t) => `outward tool ${t}`), ...writeApis.map((x: any) => `writes to api ${x?.name ?? "?"}`)];
@@ -598,7 +635,7 @@ function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<st
       push(
         "security/lethal-trifecta", a.file, a.line, `trifecta ${a.name}`,
         `${a.name} reads the web, holds ${privateLeg.slice(0, 3).join(", ")}${privateLeg.length > 3 ? ", …" : ""} and can reach ${outLeg.slice(0, 2).join(" and ")} — ` +
-          `a page it reads can tell it where to send what it holds. Narrow network:, split it, or add a hooks: gate`,
+          `a page it reads can tell it where to send what it holds. Take it off the open network (network: { level: trusted, allow: [...] }), split it, or add a hooks: gate`,
       );
     }
 
@@ -686,7 +723,7 @@ function ignored(ig: Ignores, rule: string, line?: number): boolean {
 
 // ── the scan ───────────────────────────────────────────────────────────────
 
-type Push = (rule: string, file: string, line: number | undefined, text: string, message: string) => void;
+type Push = (rule: string, file: string, line: number | undefined, text: string, message: string, level?: ScanLevel) => void;
 
 /** Installed and built code: someone else's files, and a crypto library's
  *  constants are not this workspace's keys. */
@@ -708,14 +745,14 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
   const seen = new Set<string>();
   const ignoresByFile = new Map<string, Ignores>();
 
-  const push: Push = (rule, file, line, text, message) => {
+  const push: Push = (rule, file, line, text, message, level) => {
     if (!enabled(rule)) return;
     const ig = ignoresByFile.get(file);
     if (ig && ignored(ig, rule, line)) return;
     const key = `${rule}\0${file}\0${line ?? ""}\0${message}`;
     if (seen.has(key)) return;
     seen.add(key);
-    findings.push({ rule, level: scanRule(rule)?.level ?? "warn", file, ...(line ? { line } : {}), message, fingerprint: findingFingerprint(rule, file, text) });
+    findings.push({ rule, level: level ?? scanRule(rule)?.level ?? "warn", file, ...(line ? { line } : {}), message, fingerprint: findingFingerprint(rule, file, text) });
   };
 
   const outward = new Set(options.outwardTools ?? []);
@@ -729,15 +766,21 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
     scanContent(f, lines, push);
     scanSupplyChain(f, lines, push);
 
-    const kind = docKind(f.path);
-    if (!kind) continue;
-    const data = frontOf(f.content);
+    const schema = schemaKindOf(f.path);
+    // 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;
     if (!data) continue;
-    const known = kind === "agent" ? AGENT_FIELDS : kind === "flow" ? FLOW_FIELDS : TOOL_FIELDS;
-    for (const key of Object.keys(data)) {
-      const near = nearestField(key, known);
-      if (near && near !== key) push("config/unknown-field", f.path, keyLine(lines, key), `field ${key}`, `\`${key}:\` is not a field foldrun reads — did you mean \`${near}:\`? As written it is ignored`);
+    if (schema) {
+      for (const p of frontmatterProblems(schema, data, nearestField)) {
+        // Fingerprint the key's own line, not the parsed value: a YAML alias
+        // can make the value circular, and JSON of it would throw.
+        const at = keyLine(lines, p.key);
+        push(p.rule, f.path, at, `${p.rule} ${at ? lines[at - 1] : p.key}`, p.message, p.level);
+      }
     }
+    const kind = docKind(f.path);
+    if (!kind) continue;
     if (kind === "agent") {
       const rel = f.path.replace(/^library\//, "");
       const name = /^agents\/([^/]+)\//.exec(rel)?.[1] ?? rel.replace(/^.*\/|\.md$/g, "");
@@ -748,7 +791,8 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
       toolDefs.set(f.path, { data, lines });
     }
   }
-  scanAgents(agents, outward, toolDefs, push);
+  const workspaceMd = files.find((f) => f.path === "AGENTS.md");
+  scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content)?.network : undefined });
 
   return findings.sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule));
 }
@@ -791,7 +835,12 @@ export function makeBaseline(findings: Pick<ScanFinding, "rule" | "file" | "fing
 export function applyBaseline<T extends Pick<ScanFinding, "rule" | "file" | "fingerprint">>(findings: T[], baseline: unknown): { kept: T[]; baselined: number } {
   const b = baseline as ScanBaseline | null;
   if (!b || b.version !== 1 || !Array.isArray(b.findings)) return { kept: findings, baselined: 0 };
-  const known = new Set(b.findings.map((f) => `${f.rule}\0${f.file}\0${f.fingerprint}`));
+  // An entry that is not {rule, file, fingerprint} hides nothing.
+  const entries = (b.findings as unknown[]).filter(
+    (f): f is ScanBaseline["findings"][number] =>
+      !!f && typeof f === "object" && typeof (f as any).rule === "string" && typeof (f as any).file === "string" && typeof (f as any).fingerprint === "string",
+  );
+  const known = new Set(entries.map((f) => `${f.rule}\0${f.file}\0${f.fingerprint}`));
   const kept = findings.filter((f) => !known.has(`${f.rule}\0${f.file}\0${f.fingerprint}`));
   return { kept, baselined: findings.length - kept.length };
 }

package/src/store.ts

@@ -21,6 +21,7 @@
 // An account is a named directory (per OKF: tenancy is a hosting concern).
 
 import { expandPlatformVars } from "./host-env.ts";
+import { EFFORT_LEVELS, FLOW_TRIGGERS } from "./frontmatter-fields.ts";
 import type { BrowserPodOutcome } from "./browser-pod.ts";
 import fs from "node:fs";
 import path from "node:path";
@@ -1082,7 +1083,7 @@ export function resolveModel(value: unknown): string {
 // model is which brain, effort is how long it thinks before answering. The
 // five levels are the SDK's own union — we neither invent our own scale nor
 // narrow theirs, so a level added upstream is one line here.
-export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
+export { EFFORT_LEVELS } from "./frontmatter-fields.ts";
 export type Effort = (typeof EFFORT_LEVELS)[number];
 
 const EFFORT_ALIASES: Record<string, Effort> = {
@@ -1464,7 +1465,8 @@ export interface FlowInfo {
   steps: FlowStep[];
 }
 
-export const FLOW_TRIGGERS = ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"] as const;
+// The list lives with every other frontmatter field (frontmatter-fields.ts).
+export { FLOW_TRIGGERS } from "./frontmatter-fields.ts";
 export type FlowTrigger = (typeof FLOW_TRIGGERS)[number];
 
 // Skills and memory files belonging to one agent — for the graph view and
@@ -1624,7 +1626,7 @@ const OPTION_RE = /^(\s+)([a-z_-]+):(.*)$/;
  *  publish" is prose that happens to contain a colon, and it used to be
  *  swallowed as an unknown option, silently, along with any typo of a real
  *  key. The consistency suite reads this list against the docs. */
-const STEP_OPTION_KEYS = new Set([
+export const STEP_OPTION_KEYS: ReadonlySet<string> = new Set([
   "approve", "ask", "case", "delegate", "each", "effort", "else", "limits", "loop", "max", "max_turns", "model",
   "on-fail", "onfail", "output", "parallel", "preview", "retry", "schema", "timeout", "until", "verify", "wait", "when",
 ]);