@foldrun/core 1.2.0 → 1.4.0

package/dist/src/completions.js

@@ -9,6 +9,7 @@
 // go here. No React, no fetch — so the rules are testable and one component
 // renders them.
 import { PROVIDERS } from "./providers.js";
+import { FRONTMATTER } from "./frontmatter-fields.js";
 const MODELS = [
     { label: "fast", hint: "haiku — cheap, for checks and triage" },
     { label: "default", hint: "sonnet — the working default" },
@@ -157,8 +158,6 @@ const FIELDS = {
         { label: "trigger", insert: "trigger: manual" },
         { label: "schedule", insert: "schedule: \"0 6 * * MON\"" },
         { label: "timezone", insert: "timezone: Australia/Sydney" },
-        { label: "language", insert: "language: en-AU" },
-        { label: "region", insert: "region: au", hint: "currency, units, calendar, weekend and text direction follow" },
         { label: "model", insert: "model: fast", hint: "every step, unless the step says" },
         { label: "effort", insert: "effort: high", hint: "every step, unless the step says" },
     ],
@@ -216,6 +215,26 @@ export function fileKind(path) {
         return "evalFile";
     return "note";
 }
+/** Which frontmatter schema a completion kind offers. */
+const SCHEMA_OF = { agent: "agent", flow: "flow", tool: "tool", skill: "skill", evalFile: "eval" };
+/**
+ * The fields to offer at the start of a frontmatter line: the hand-written
+ * snippets above where a field has one, then every other field the schema
+ * says this kind of file takes — so a field added to frontmatter-fields.ts is
+ * offered here with no second edit, and a snippet for a field the runtime no
+ * longer reads is dropped. AGENTS.md takes its own set, not an agent's.
+ */
+function fieldsFor(path, kind) {
+    const agentsMd = /(^|\/)AGENTS\.md$/.test(path) || path === "project.md";
+    const schema = agentsMd ? FRONTMATTER["agents-md"] : SCHEMA_OF[kind] ? FRONTMATTER[SCHEMA_OF[kind]] : null;
+    if (!schema)
+        return FIELDS[kind];
+    const offered = schema.filter((f) => !f.legacy);
+    const keys = new Set(offered.map((f) => f.key));
+    const curated = FIELDS[kind].filter((c) => keys.has(c.label.split(".")[0]));
+    const have = new Set(curated.map((c) => c.label.split(".")[0]));
+    return [...curated, ...offered.filter((f) => !have.has(f.key)).map((f) => ({ label: f.key, insert: `${f.key}: `, hint: f.help }))];
+}
 /**
  * Does [[ ]] in this file get expanded into a path, or stay literal?
  *
@@ -581,9 +600,9 @@ export function completionsAt(path, text, cursor, vocab) {
     //    this kind of file. This is where you learn the format by writing it.
     const fmEnd = text.indexOf("\n---", text.indexOf("---") + 3);
     const inFrontmatter = text.startsWith("---") && (fmEnd === -1 || cursor <= fmEnd);
-    if (inFrontmatter && /^[a-zA-Z_]*$/.test(line)) {
+    if (inFrontmatter && /^[a-zA-Z_][a-zA-Z_-]*$|^$/.test(line)) {
         const from = cursor - line.length;
-        return { from, query: line, items: filter(FIELDS[kind], line), title: `${kind} fields` };
+        return { from, query: line, items: filter(fieldsFor(path, kind), line), title: `${kind} fields` };
     }
     return null;
 }

package/dist/src/cron.d.ts

@@ -0,0 +1,17 @@
+export declare const NAMED: Record<string, string>;
+export declare const DOW_NAMES: string[];
+export interface Cron {
+    minute: Set<number>;
+    hour: Set<number>;
+    dom: Set<number>;
+    month: Set<number>;
+    dow: Set<number>;
+    domRestricted: boolean;
+    dowRestricted: boolean;
+    /** Neither minute nor hour is a wildcard: a job at a time of day, which
+     *  is what the DST rules in cronMatches apply to (as in Vixie cron). */
+    fixedTime: boolean;
+}
+export declare function parseCron(expr: string): Cron | null;
+/** Why `schedule:` is not a cron the scheduler can run, or null when it is. */
+export declare function cronProblem(expr: unknown): string | null;

package/dist/src/cron.js

@@ -0,0 +1,107 @@
+// Cron: the one reading of a flow's `schedule:`.
+//
+// Moved here from the platform's scheduler so `foldrun check`, the deploy and
+// the scheduler ask the same function whether a schedule is one — a cron the
+// scheduler cannot parse used to be skipped silently, and nothing earlier
+// said so. The scheduler imports this; the expansion is unchanged.
+export const NAMED = {
+    "@hourly": "0 * * * *",
+    "@daily": "0 0 * * *",
+    "@midnight": "0 0 * * *",
+    "@weekly": "0 0 * * 0",
+    "@monthly": "0 0 1 * *",
+};
+export const DOW_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+// Expand one cron field ("*", "*/15", "1-5", "mon,fri", "3") to a value set.
+function expandField(field, min, max, names) {
+    const out = new Set();
+    for (const part of field.split(",")) {
+        const [rangePart, stepPart] = part.split("/");
+        const step = stepPart ? Number(stepPart) : 1;
+        if (!Number.isInteger(step) || step < 1)
+            return null;
+        let lo = min;
+        let hi = max;
+        if (rangePart !== "*") {
+            const bounds = rangePart.split("-");
+            const parse = (raw) => {
+                const token = raw.trim().toLowerCase();
+                if (names) {
+                    // A name counts from the field's own minimum: SUN is 0 on the
+                    // weekday field, JAN is 1 on the month field. Indexed from zero,
+                    // JAN read as 0 (refused — the flow never fired) and FEB…DEC as
+                    // the month before.
+                    const idx = names.indexOf(token);
+                    if (idx !== -1)
+                        return min + idx;
+                }
+                const n = Number(token);
+                return Number.isInteger(n) ? n : null;
+            };
+            const a = parse(bounds[0]);
+            if (a === null)
+                return null;
+            lo = a;
+            if (bounds.length > 1) {
+                const b = parse(bounds[1]);
+                if (b === null)
+                    return null;
+                hi = b;
+            }
+            else {
+                hi = stepPart ? max : a; // "5" → just 5; "5/10" → 5,15,25...
+            }
+        }
+        if (lo < min || hi > max || lo > hi)
+            return null;
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out;
+}
+/** `@daily` → its five fields; anything else as written. An own-property
+ *  lookup, so `schedule: constructor` is a bad cron, not a crash. */
+function expand(expr) {
+    const key = expr.trim().toLowerCase();
+    return (Object.hasOwn(NAMED, key) ? NAMED[key] : expr).trim();
+}
+export function parseCron(expr) {
+    if (typeof expr !== "string")
+        return null;
+    const normalized = expand(expr);
+    const fields = normalized.split(/\s+/);
+    if (fields.length !== 5)
+        return null;
+    const [mi, ho, dm, mo, dw] = fields;
+    const minute = expandField(mi, 0, 59);
+    const hour = expandField(ho, 0, 23);
+    const dom = expandField(dm, 1, 31);
+    const month = expandField(mo, 1, 12, MONTH_NAMES);
+    const dowRaw = expandField(dw, 0, 7, DOW_NAMES);
+    if (!minute || !hour || !dom || !month || !dowRaw)
+        return null;
+    // cron allows both 0 and 7 for Sunday.
+    const dowSet = new Set([...dowRaw].map((d) => (d === 7 ? 0 : d)));
+    return {
+        minute,
+        hour,
+        dom,
+        month,
+        dow: dowSet,
+        domRestricted: dm.trim() !== "*",
+        dowRestricted: dw.trim() !== "*",
+        fixedTime: !mi.startsWith("*") && !ho.startsWith("*"),
+    };
+}
+/** Why `schedule:` is not a cron the scheduler can run, or null when it is. */
+export function cronProblem(expr) {
+    if (typeof expr !== "string" || !expr.trim())
+        return "schedule: is a cron expression — five fields, or @hourly, @daily, @weekly, @monthly";
+    if (parseCron(expr))
+        return null;
+    const fields = expand(expr).split(/\s+/).length;
+    return fields !== 5
+        ? `schedule: "${expr}" has ${fields} field${fields === 1 ? "" : "s"}; cron has five — minute hour day-of-month month day-of-week ("0 9 * * MON"), or @hourly, @daily, @weekly, @monthly. As written the flow never fires`
+        : `schedule: "${expr}" is not a cron the scheduler can read — a field is out of range or not a number (minute 0-59, hour 0-23, day 1-31, month 1-12, weekday 0-7 or sun-sat). As written the flow never fires`;
+}

package/dist/src/frontmatter-fields.d.ts

@@ -0,0 +1,27 @@
+export type FieldType = "string" | "number" | "boolean" | "list" | "object";
+export interface FieldSpec {
+    key: string;
+    /** What YAML may hand over. "list" is also offered where the runtime
+     *  splits `a, b` on one line, so such fields list "string" too. */
+    type: FieldType | FieldType[];
+    /** The values that do something, when the set is closed and has no
+     *  aliases. Anything else is reported. */
+    values?: readonly string[];
+    /** Another function validates this field in full and is the one place
+     *  that does; the schema only says the field exists. */
+    validated?: boolean;
+    /** An older name still read, or kept so the right message (not
+     *  "unknown") reaches whoever wrote it. Not offered as a completion. */
+    legacy?: boolean;
+    /** One line: what it is. The completion's hint. */
+    help: string;
+}
+export type SchemaKind = "agent" | "agents-md" | "flow" | "tool" | "skill" | "eval" | "hook";
+/** What can start a flow. store.ts re-exports it; parseFlow and the editor
+ *  read this one. */
+export declare const FLOW_TRIGGERS: readonly ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
+/** The effort levels; store.ts re-exports it with the aliases beside. */
+export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+export declare const FRONTMATTER: Readonly<Record<SchemaKind, readonly FieldSpec[]>>;
+/** Which schema a workspace-relative path is read with, or null. */
+export declare function schemaKindOf(p: string): SchemaKind | null;

package/dist/src/frontmatter-fields.js

@@ -0,0 +1,197 @@
+// Every frontmatter field foldrun reads, per kind of file — as data.
+//
+// The one list. Before it, the fields lived in five places that drifted: the
+// runtime's reads, the dashboard's completions, the scanner's typo lists, the
+// docs, and the assistant's vocabulary — the completions offered `language:`
+// on a flow, which no run reads. Now:
+//
+//   · completions.ts offers exactly these, in the browser (so this file is
+//     pure data: no fs, no store);
+//   · frontmatter-schema.ts checks values against them, for `foldrun check`,
+//     the Checks page, the editor and the deploy's view;
+//   · tests/frontmatter-schema.test.ts fails when the runner, parseFlow or a
+//     tool parser reads a field missing here, or a completion offers one
+//     that is not; foldrun-web's consistency test fails when one here is not
+//     in the docs.
+//
+// A new field is added here first, then read.
+/** What can start a flow. store.ts re-exports it; parseFlow and the editor
+ *  read this one. */
+export const FLOW_TRIGGERS = ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
+/** The effort levels; store.ts re-exports it with the aliases beside. */
+export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+const LOCALE = { validated: true };
+const AGENT = [
+    { key: "name", type: "string", help: "kebab-case; the folder is the identity" },
+    { key: "description", type: "string", help: "what it does and when — other agents and people read it" },
+    { key: "model", type: "string", help: "fast | default | max, an alias, or a full model id" },
+    { key: "effort", type: "string", values: EFFORT_LEVELS, help: "how long it thinks" },
+    { key: "size", type: "string", values: ["small", "large", "heavy"], help: "the sandbox it rents; anything else becomes large" },
+    { key: "permissionMode", type: "string", values: ["plan"], help: "plan = read-only; no other mode changes anything here" },
+    { key: "tools", type: ["list", "string"], help: "the one grant list" },
+    { key: "disallowedTools", type: ["list", "string"], help: "subtract from what it would otherwise have" },
+    { key: "skills", type: ["list", "string"], help: "an allowlist; absent inherits every skill" },
+    { key: "hooks", type: ["list", "string", "object"], help: "hook names; a Claude Code hooks: object is read as none" },
+    { key: "scripts", type: "list", help: "programs in scripts/, each a tool" },
+    { key: "apis", type: "list", help: "an HTTP API as a tool" },
+    { key: "mcpServers", type: "object", help: "MCP servers, name → {command | url, args, env, headers}" },
+    { key: "agents", type: ["list", "string"], help: "colleagues it may consult" },
+    { key: "subagents", type: ["list", "string"], help: "colleagues it may delegate to" },
+    { key: "secrets", type: ["list", "string"], help: "keys it spends itself" },
+    { key: "budget", type: ["number", "string"], help: "USD per run" },
+    { key: "limits", type: "object", validated: true, help: "per-step call limits" },
+    { key: "network", type: ["string", "list", "object"], validated: true, help: "open | trusted | none, sites, or {level, allow, defaults}" },
+    { key: "web", type: "object", validated: true, help: "providers for the web tool's actions" },
+    { key: "provider", type: "object", help: "an Anthropic- or OpenAI-format endpoint for this agent" },
+    { key: "runtime", type: "object", help: "packages and system packages for its sandbox" },
+    { key: "ask", type: "object", help: "{timeout} for tools: [ask]" },
+    { key: "timezone", type: "string", ...LOCALE, help: "IANA name or offset" },
+    { key: "language", type: "string", ...LOCALE, help: "BCP-47 tag" },
+    { key: "region", type: "string", ...LOCALE, help: "two-letter country" },
+    { key: "currency", type: "string", ...LOCALE, help: "three letters" },
+    { key: "units", type: "string", ...LOCALE, help: "metric | imperial" },
+    { key: "calendar", type: "string", ...LOCALE, help: "an Intl calendar" },
+    { key: "schedule", type: ["string", "object"], validated: true, legacy: true, help: "refused: only a flow has a clock" },
+    { key: "use", type: ["list", "string"], validated: true, legacy: true, help: "retired: write tools:" },
+];
+const AGENTS_MD = [
+    { key: "foldrun_version", type: ["string", "number"], help: "the format version this account targets" },
+    { key: "mdagent_version", type: ["string", "number"], legacy: true, help: "older spelling of foldrun_version" },
+    { key: "name", type: "string", help: "the workspace's name" },
+    { key: "description", type: "string", help: "shown in the workspace list" },
+    { key: "provider", type: "object", help: "the model endpoint every agent here uses unless it names its own" },
+    { key: "runtime", type: "object", help: "packages for agents that declare none" },
+    { key: "web", type: "object", validated: true, help: "web.browse defaults" },
+    { key: "network", type: ["string", "list", "object"], validated: true, help: "every agent's default network" },
+    { key: "limits", type: "object", validated: true, help: "default call limits" },
+    { key: "hooks", type: ["list", "string"], help: "hooks every agent here runs" },
+    { key: "timezone", type: "string", ...LOCALE, help: "default timezone" },
+    { key: "language", type: "string", ...LOCALE, help: "default language" },
+    { key: "region", type: "string", ...LOCALE, help: "default region" },
+    { key: "currency", type: "string", ...LOCALE, help: "default currency" },
+    { key: "units", type: "string", ...LOCALE, help: "default units" },
+    { key: "calendar", type: "string", ...LOCALE, help: "default calendar" },
+    { key: "notify", type: ["string", "object"], help: "an email or URL told about failed runs and waiting approvals" },
+    { key: "budget", type: ["number", "string"], help: "USD per month, or N/day | N/week | N/month" },
+    { key: "priority", type: "string", values: ["high", "normal", "low"], help: "account: where its runs stand in the queue" },
+    { key: "concurrency", type: ["number", "string"], help: "account: runs at once" },
+    { key: "schedule", type: ["string", "object"], validated: true, legacy: true, help: "refused: only a flow has a clock" },
+];
+const FLOW = [
+    { key: "name", type: "string", help: "the flow's name" },
+    { key: "description", type: "string", help: "what it is for" },
+    { key: "trigger", type: "string", values: FLOW_TRIGGERS, help: "what starts it; any other value never fires" },
+    { key: "schedule", type: "string", help: "cron, when trigger: schedule" },
+    { key: "timezone", type: "string", validated: true, help: "the zone its schedule reads in" },
+    { key: "model", type: "string", help: "every step's model unless the step says" },
+    { key: "effort", type: "string", values: EFFORT_LEVELS, help: "every step's effort unless the step says" },
+    { key: "overlap", type: "string", validated: true, help: "skip | queue" },
+    { key: "priority", type: "string", validated: true, help: "high | normal | low" },
+    { key: "catchup", type: "string", validated: true, help: "last | none" },
+    { key: "on", type: "string", validated: true, help: "trigger: flow — completed | failed | blocked | any" },
+    { key: "signature", type: "string", validated: true, help: "github | stripe | slack | hmac" },
+    { key: "signing_secret", type: "string", help: "the secret a webhook's signature is checked with" },
+    { key: "after", type: ["string", "list"], help: "trigger: flow — the flow this one follows" },
+    { key: "at", type: "string", help: "trigger: once — when" },
+    { key: "url", type: "string", help: "trigger: watch — the page watched" },
+    { key: "every", type: ["string", "number"], help: "trigger: watch — how often" },
+    { key: "path", type: "string", help: "trigger: storage — the prefix under storage/" },
+    { key: "idempotency", type: "string", help: "a header name, or body:<field>, that marks a repeat delivery" },
+    { key: "debounce", type: ["string", "number"], help: "wait for a burst to end" },
+    { key: "throttle", type: ["string", "number"], help: "at most one run per window" },
+    { key: "sla", type: ["string", "number"], help: "tell someone when a run outlives it" },
+    { key: "approve_within", type: ["string", "number"], help: "how long an approval may wait" },
+    { key: "disable_after", type: ["number", "string"], help: "switch the flow off after this many failures in a row" },
+    { key: "pause_when", type: "string", help: "a marker that pauses the flow when a run's result says it" },
+    { key: "approvers", type: ["list", "string"], help: "who may approve its gates" },
+    { key: "budget", type: ["number", "string"], help: "USD per run" },
+    { key: "live", type: "boolean", help: "true: steps may act for real in a test run" },
+];
+const TOOL = [
+    { key: "name", type: "string", help: "defaults to the file or folder name" },
+    { key: "description", type: "string", help: "what it does — the model chooses by it" },
+    { key: "transport", type: "string", values: ["http", "script", "mcp"], help: "http | script | mcp" },
+    { key: "type", type: "string", legacy: true, help: "older spelling of transport" },
+    { key: "outward", type: "boolean", help: "true: it changes something outside the workspace" },
+    { key: "base", type: "string", help: "http: the API's base URL" },
+    { key: "headers", type: "object", help: "http or mcp: request headers; ${SECRET} is filled server-side" },
+    { key: "query", type: "object", help: "http: query parameters on every call" },
+    { key: "methods", type: ["list", "string"], help: "http: GET, POST, PUT, PATCH, DELETE" },
+    { key: "openapi", type: "string", help: "http: an OpenAPI document for the operations" },
+    { key: "operations", type: ["list", "object"], help: "http: which operations to offer" },
+    { key: "rate", type: ["string", "number"], help: "http: N/s, N/minute, N/hour, or a number per second" },
+    { key: "timeout", type: ["number", "string"], help: "seconds one call may take" },
+    { key: "run", type: "string", help: "script: the program, relative to the tool" },
+    { key: "args", type: ["object", "list"], help: "script: its arguments, name → what it is; mcp: the command's arguments" },
+    { key: "interpreter", type: "string", help: "script: what runs it" },
+    { key: "test_mode", type: "string", values: ["allow"], help: "script: allow — it may run in a test run" },
+    { key: "secrets", type: ["list", "string"], help: "script: secret names, or proxied | materialised" },
+    { key: "runtime", type: "object", help: "script: packages it needs" },
+    { key: "code", type: "string", help: "script: the program inline" },
+    { key: "command", type: "string", help: "mcp: the server's command" },
+    { key: "env", type: "object", help: "mcp: its environment" },
+    { key: "url", type: "string", help: "mcp: a server over http" },
+    { key: "guide", type: "string", legacy: true, help: "ignored — the guide is the body" },
+];
+const SKILL = [
+    { key: "name", type: "string", help: "defaults to the folder" },
+    { key: "description", type: "string", help: "required — the model chooses a skill by it" },
+    { key: "when", type: ["list", "string"], help: "run tags it loads on" },
+    // The Agent Skills format's own optional fields: not read, not wrong.
+    { key: "license", type: "string", help: "Agent Skills format" },
+    { key: "compatibility", type: "string", help: "Agent Skills format" },
+    { key: "metadata", type: "object", help: "Agent Skills format" },
+    { key: "allowed-tools", type: ["string", "list"], help: "Agent Skills format: space-separated pre-approved tools (experimental)" },
+];
+const EVAL = [
+    { key: "name", type: "string", help: "the eval's name" },
+    { key: "agent", type: "string", help: "the agent it tests" },
+    { key: "flow", type: "string", help: "or the flow" },
+    { key: "model", type: "string", help: "the judge's model" },
+    { key: "effort", type: "string", values: EFFORT_LEVELS, help: "the judge's effort" },
+    { key: "trigger", type: "string", values: ["deploy", "manual"], help: "deploy (default) | manual; anything else is deploy" },
+    { key: "live", type: "boolean", help: "true: real calls" },
+    { key: "inputs", type: "boolean", help: "true: cases carry inputs" },
+];
+const HOOK = [
+    { key: "on", type: "string", validated: true, help: "tool.call | tool.result | step.start | step.end" },
+    { key: "tool", type: "string", validated: true, help: "only on tool events" },
+    { key: "timeout", type: "number", validated: true, help: "seconds, 1 to 120" },
+    { key: "description", type: "string", help: "what it guards" },
+    { key: "name", type: "string", help: "the folder is the name" },
+];
+/** `kind:` and `type:` were how a document once said what it was; the path
+ *  says it now, and `foldrun check` has its own message for them. */
+const SAID_WHAT_IT_IS = [
+    { key: "kind", type: "string", validated: true, legacy: true, help: "no longer read — the path says what this is" },
+    { key: "type", type: "string", validated: true, legacy: true, help: "no longer read — the path says what this is" },
+];
+export const FRONTMATTER = {
+    agent: [...AGENT, ...SAID_WHAT_IT_IS],
+    "agents-md": AGENTS_MD,
+    flow: [...FLOW, ...SAID_WHAT_IT_IS],
+    tool: [...TOOL, ...SAID_WHAT_IT_IS.filter((f) => f.key !== "type")],
+    skill: [...SKILL, ...SAID_WHAT_IT_IS],
+    eval: [...EVAL, ...SAID_WHAT_IT_IS],
+    hook: HOOK,
+};
+/** Which schema a workspace-relative path is read with, or null. */
+export function schemaKindOf(p) {
+    // A library entry is `library/<kind>/<path>`; read it as `<kind>/<path>`.
+    const rel = p.replace(/^library\/(?=[a-z]+\/)/, "");
+    if (/^agents\/[^/]+\/agent\.md$/.test(rel) || /^\.(?:claude|agents)\/agents\/[^/]+\.md$/.test(rel))
+        return "agent";
+    if (rel === "AGENTS.md" || rel === "project.md")
+        return "agents-md";
+    if (/^flows\/[^/]+\.md$/.test(rel))
+        return "flow";
+    if (/^tools\/[^/]+\/tool\.md$/.test(rel) || /^tools\/[^/]+\.md$/.test(rel))
+        return "tool";
+    if (/(?:^|\/)skills\/[^/]+\/SKILL\.md$/.test(rel))
+        return "skill";
+    if (/^evals\/[^/]+\.md$/.test(rel))
+        return "eval";
+    if (/^hooks\/[^/]+\/hook\.md$/.test(rel))
+        return "hook";
+    return null;
+}

package/dist/src/frontmatter-schema.d.ts

@@ -0,0 +1,15 @@
+import { type SchemaKind } from "./frontmatter-fields.ts";
+export { FRONTMATTER, schemaKindOf, type FieldSpec, type FieldType, type SchemaKind } from "./frontmatter-fields.ts";
+export interface FieldProblem {
+    key: string;
+    rule: "config/unknown-field" | "config/wrong-type" | "config/invalid-value" | "config/missing-field";
+    level: "warn" | "info";
+    message: string;
+}
+/**
+ * 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 declare function frontmatterProblems(kind: SchemaKind, data: Record<string, unknown>, near: (key: string, known: readonly string[]) => string | null): FieldProblem[];

package/dist/src/frontmatter-schema.js

@@ -0,0 +1,156 @@
+// 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 } from "./frontmatter-fields.js";
+import { resolveEffort, parseDuration, parseInstant, parseRate, STEP_OPTION_KEYS } from "./store.js";
+import { budgetProblem } from "./budget.js";
+import { cronProblem } from "./cron.js";
+export { FRONTMATTER, schemaKindOf } from "./frontmatter-fields.js";
+/** 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) {
+    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, max, unit = "") => (v) => {
+    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 = {
+    "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`),
+    },
+};
+// 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) => v === null || v === undefined ? "null" : v instanceof Date ? "string" : Array.isArray(v) ? "list" : typeof v === "object" ? "object" : typeof v;
+/** 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, kind) {
+    const where = [["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, data, near) {
+    const fields = FRONTMATTER[kind];
+    const known = fields.map((f) => f.key);
+    const out = [];
+    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)) {
+            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 = 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) {
+    const t = v?.timeout;
+    return t === undefined ? null : DURATION(30, 86400, "30s to 24h")(t);
+}
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+function methodsProblem(v) {
+    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) {
+    for (const api of Array.isArray(v) ? v : []) {
+        if (!api || typeof api !== "object")
+            return "each entry is {name, base, …}";
+        const m = api.methods;
+        const p = m === undefined ? null : methodsProblem(m);
+        if (p)
+            return `${String(api.name ?? "an api")}: methods: ${p}`;
+    }
+    return null;
+}

package/dist/src/scan.d.ts

@@ -33,6 +33,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 declare const OWASP_URL = "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026";
 export declare const SCAN_RULES: readonly ScanRule[];
@@ -60,6 +63,9 @@ export declare function ruleDocsUrl(id: string): string;
 export declare function findingFingerprint(rule: string, file: string, text: string): string;
 /** What a finding may show of a secret: enough to find it, not to use it. */
 export declare function redactSecret(secret: string): string;
+/** The text with every credential in it redacted — for a finding that
+ *  quotes source, so no message ever carries a key whole. */
+export declare function redactText(text: string): string;
 /** The known field a key was probably meant to be, or null. */
 export declare function nearestField(key: string, known: readonly string[]): string | null;
 /**