@foldrun/core 1.3.0 → 1.4.0

package/src/frontmatter-schema.ts

@@ -0,0 +1,167 @@
+// Checking frontmatter against frontmatter-fields.ts: the values, not just
+// the names. Node-side (it reads store's parsers); the browser takes the
+// field list alone from frontmatter-fields.ts.
+
+import { FRONTMATTER, type FieldType, type SchemaKind } from "./frontmatter-fields.ts";
+import { resolveEffort, parseDuration, parseInstant, parseRate, STEP_OPTION_KEYS } from "./store.ts";
+import { budgetProblem } from "./budget.ts";
+import { cronProblem } from "./cron.ts";
+
+export { FRONTMATTER, schemaKindOf, type FieldSpec, type FieldType, type SchemaKind } from "./frontmatter-fields.ts";
+
+/** A value for a message: a scalar as written, anything else by its shape.
+ *  Never String() of a map — its `toString` is whatever the YAML says. */
+function shown(v: unknown): string {
+  return typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? String(v) : v instanceof Date ? v.toISOString() : Array.isArray(v) ? "a list" : "a map";
+}
+
+const DURATION = (min: number, max: number, unit = "") => (v: unknown) => {
+  if (typeof v !== "string" && typeof v !== "number") return `is ${shown(v)}, not a duration — write seconds (900) or 30s, 15m, 4h, 3d`;
+  const s = parseDuration(String(v));
+  if (s === undefined) return `"${String(v)}" is not a duration — write seconds (900) or 30s, 15m, 4h, 3d`;
+  if (s < min || s > max) return `"${String(v)}" is outside ${unit || `${min}s to ${max}s`}`;
+  return null;
+};
+
+/** Why a value is wrong, or null — per kind, per field: the rules a list of
+ *  values cannot say (aliases, durations, cron, budgets). */
+const CHECKS: Partial<Record<SchemaKind, Record<string, (value: unknown) => string | null>>> = {
+  "agent": {
+    effort: (v) => (resolveEffort(v) ? null : `"${String(v)}" is not an effort — low, medium, high, xhigh or max; the step runs at the model's default`),
+    apis: apisProblem,
+    budget: (v) => budgetProblem(v, ["run"]),
+    ask: (v) => askProblem(v),
+  },
+  "agents-md": {
+    budget: (v) => budgetProblem(v, ["day", "week", "month"]),
+    concurrency: (v) => (Number.isInteger(Number(v)) && Number(v) > 0 ? null : `${String(v)} is not a whole number of runs, 1 or more`),
+  },
+  "flow": {
+    schedule: cronProblem,
+    effort: (v) => (resolveEffort(v) ? null : `"${String(v)}" is not an effort — low, medium, high, xhigh or max`),
+    at: (v) => (parseInstant(v) ? null : `"${String(v)}" is not an ISO 8601 instant — a once flow with it never fires`),
+    url: (v) => (/^https?:\/\//i.test(String(v)) ? null : `"${String(v)}" is not an http(s) URL`),
+    every: DURATION(1, 30 * 86400, "1s to 30 days"),
+    debounce: DURATION(1, 30 * 86400, "1s to 30 days"),
+    throttle: DURATION(1, 30 * 86400, "1s to 30 days"),
+    sla: DURATION(1, 30 * 86400, "1s to 30 days"),
+    approve_within: DURATION(1, 30 * 86400, "1s to 30 days"),
+    disable_after: (v) => (Number(v) > 0 && Number(v) <= 100 ? null : `${String(v)} is not a count from 1 to 100; it is ignored`),
+    pause_when: (v) => (String(v).length <= 60 ? null : "is longer than 60 characters"),
+    budget: (v) => budgetProblem(v, ["run"]),
+  },
+  "tool": {
+    transport: (v) => (["http", "script", "mcp"].includes(String(v).toLowerCase()) ? null : `"${String(v)}" is not a transport — http, script or mcp`),
+    methods: methodsProblem,
+    rate: (v) => (parseRate(v) ? null : `"${shown(v)}" is not a rate — N/s, N/minute, N/hour, or a number per second, above 0`),
+  },
+  "eval": {
+    effort: (v) => (resolveEffort(v) ? null : `"${String(v)}" is not an effort — low, medium, high, xhigh or max; the judge runs at none`),
+  },
+};
+
+export interface FieldProblem {
+  key: string;
+  rule: "config/unknown-field" | "config/wrong-type" | "config/invalid-value" | "config/missing-field";
+  level: "warn" | "info";
+  message: string;
+}
+
+// YAML reads an unquoted 2026-11-01T09:00:00Z as a Date; the runtime takes
+// it as the string it was written as, so it is one here too.
+const typeOf = (v: unknown): FieldType | "null" =>
+  v === null || v === undefined ? "null" : v instanceof Date ? "string" : Array.isArray(v) ? "list" : typeof v === "object" ? "object" : (typeof v as FieldType);
+
+/** Where a key that is not read in this kind of file IS read, for a message
+ *  that says where it belongs. */
+function belongsIn(key: string, kind: SchemaKind): string | null {
+  const where: [SchemaKind, string][] = [["agent", "an agent"], ["agents-md", "AGENTS.md"], ["flow", "a flow"], ["tool", "a tool"]];
+  const homes = where.filter(([k]) => k !== kind && FRONTMATTER[k].some((f) => f.key === key && !f.legacy)).map(([, label]) => label);
+  return homes.length ? homes.join(" or ") : null;
+}
+
+/**
+ * What is wrong with one file's frontmatter, by its schema: a key nothing
+ * reads (a near-miss names the field it meant), a value of the wrong type,
+ * a value outside the ones that do something, a required field missing.
+ * `near` is the typo matcher; scan.ts passes its own.
+ */
+export function frontmatterProblems(
+  kind: SchemaKind,
+  data: Record<string, unknown>,
+  near: (key: string, known: readonly string[]) => string | null,
+): FieldProblem[] {
+  const fields = FRONTMATTER[kind];
+  const known = fields.map((f) => f.key);
+  const out: FieldProblem[] = [];
+  for (const [key, value] of Object.entries(data)) {
+    const spec = fields.find((f) => f.key === key);
+    const check = CHECKS[kind]?.[key];
+    if (!spec) {
+      const meant = near(key, known);
+      const home = belongsIn(key, kind);
+      if (meant && meant !== key) {
+        out.push({ key, rule: "config/unknown-field", level: "warn", message: `\`${key}:\` is not a field foldrun reads — did you mean \`${meant}:\`? As written it is ignored` });
+      } else if (kind === "agent" && STEP_OPTION_KEYS.has(key)) {
+        // `timeout: 3600` on an agent reads like a setting and is not one:
+        // it is an option of a flow's step.
+        out.push({ key, rule: "config/unknown-field", level: "warn", message: `\`${key}:\` is not read on an agent — it is a step option: indent it under the step in the flow (\`   ${key}: ${shown(value)}\`). Here it is ignored` });
+      } else if (home) {
+        out.push({ key, rule: "config/unknown-field", level: "warn", message: `\`${key}:\` is read in ${home}, not in ${kind === "agents-md" ? "AGENTS.md" : kind === "eval" ? "an eval" : `a ${kind}`} — here it is ignored` });
+      } else {
+        out.push({ key, rule: "config/unknown-field", level: "info", message: `\`${key}:\` is not a field foldrun reads; it is ignored` });
+      }
+      continue;
+    }
+    if (spec.validated || value === null || value === undefined) continue;
+    const want = Array.isArray(spec.type) ? spec.type : [spec.type];
+    const got = typeOf(value);
+    // A string where a list is wanted is a one-item list wherever the
+    // runtime splits it, and the list types above say so.
+    if (!want.includes(got as FieldType)) {
+      out.push({ key, rule: "config/wrong-type", level: "warn", message: `\`${key}:\` should be ${want.map((t) => (t === "list" ? "a list" : t === "object" ? "a map of keys" : `a ${t}`)).join(" or ")}, not ${got === "list" ? "a list" : got === "object" ? "a map" : `a ${got}`} — as written it is not read` });
+      continue;
+    }
+    // A field's own check knows its aliases (`effort: quick` is low), so it
+    // decides alone; `values` alone is for a closed set with none.
+    // A check reads customer YAML: a value shaped to break it (a map whose
+    // `toString` is a string) is a finding, never a crash of the whole scan.
+    let checked: string | null = null;
+    try {
+      checked = check ? check(value) : null;
+    } catch {
+      checked = "holds a value that cannot be read";
+    }
+    const why = check
+      ? checked
+      : spec.values && typeof value === "string" && !spec.values.includes(value.trim())
+        ? `"${value}" is not one of ${spec.values.join(", ")} — as written it is ignored`
+        : null;
+    if (why) out.push({ key, rule: "config/invalid-value", level: "warn", message: `\`${key}:\` ${why.replace(/^\w+: /, "")}` });
+  }
+  if (kind === "skill" && !(typeof data.description === "string" && data.description.trim())) {
+    out.push({ key: "description", rule: "config/missing-field", level: "warn", message: "no `description:` — a skill without one is never loaded; the model chooses a skill by it" });
+  }
+  return out;
+}
+
+function askProblem(v: unknown): string | null {
+  const t = (v as { timeout?: unknown } | null)?.timeout;
+  return t === undefined ? null : DURATION(30, 86400, "30s to 24h")(t);
+}
+
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+function methodsProblem(v: unknown): string | null {
+  const list = Array.isArray(v) ? v.map(String) : String(v).split(",");
+  const bad = list.map((m) => m.trim()).filter((m) => m && !METHODS.includes(m.toUpperCase()));
+  return bad.length ? `${bad.join(", ")} — not a method; it is dropped. GET, POST, PUT, PATCH or DELETE` : null;
+}
+function apisProblem(v: unknown): string | null {
+  for (const api of Array.isArray(v) ? v : []) {
+    if (!api || typeof api !== "object") return "each entry is {name, base, …}";
+    const m = (api as { methods?: unknown }).methods;
+    const p = m === undefined ? null : methodsProblem(m);
+    if (p) return `${String((api as { name?: unknown }).name ?? "an api")}: methods: ${p}`;
+  }
+  return null;
+}

package/src/scan.ts

@@ -30,6 +30,7 @@ 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";
@@ -176,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",
@@ -510,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;
@@ -721,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. */
@@ -743,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 ?? []);
@@ -764,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, "");

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",
 ]);