@foldrun/core 0.4.0 → 0.5.0

package/dist/src/flow-lint.js

@@ -10,6 +10,18 @@
 // Every check here is *structural*: it reasons about what a step can possibly
 // have in context, never about whether the model did a good job. Nothing is
 // blocked — flows still run, warnings are advisory.
+import { whenRowsPath } from "./store.js";
+import { timezoneProblem } from "./clock.js";
+/** What a `[[flow:x]]` step's options are called in a flow file, for the
+ *  ones expandSubflows does not carry into the nested steps. */
+const SUBFLOW_DROPPED = [
+    ["approve", "an approval (!)"], ["when", "when:"], ["case", "case:"], ["else", "else:"],
+    ["retry", "retry:"], ["timeout", "timeout:"], ["verify", "verify:"], ["model", "model:"],
+    ["effort", "effort:"], ["onFail", "on-fail:"], ["waitSecs", "wait:"], ["waitFor", "wait:"],
+    ["ask", "ask:"], ["preview", "preview:"], ["delegate", "delegate:"], ["loop", "loop:"],
+    ["until", "until:"], ["each", "each:"], ["max", "max:"], ["output", "output:"],
+    ["schema", "schema:"], ["parallel", "parallel:"], ["maxTurns", "max_turns:"], ["limits", "limits:"],
+];
 // Anaphora: phrases that only mean something if earlier output exists.
 // Deliberately conservative — a false warning is worse than a missed one,
 // because noisy warnings get ignored and then the real one is invisible too.
@@ -26,9 +38,40 @@ function looksLikeAddress(a) {
     const dot = domain.indexOf(".");
     return dot > 0 && dot < domain.length - 1;
 }
+/** The assertion words a `verify:` may open with. Anything else is handed to
+ *  a shell — see `checkVerify` in step-exec.ts, which owns this list. */
+const VERIFY_ASSERTION = /^(contains|not-contains|matches|file|judge):\s/;
+/** What a shell command has that a sentence does not: an operator that only
+ *  means something to a shell, a path or bracket at the very start, or one
+ *  of the commands these flows actually reach for. Deliberately NOT any
+ *  punctuation a sentence might carry — the first version disqualified on
+ *  `;`, `,`, `'` and `"`, so "the reply opens with GOOD; a GOOD reply names
+ *  the SHA" read as shell and a guaranteed exit 127 sat in fix-desk unseen
+ *  by the very lint written to catch it. */
+const LOOKS_LIKE_SHELL = /&&|\|\||\s\|\s|\$\(|\$\{|`|\s[<>]\s|\d?>[>&]?\s|^\[|^[.~/]|^\s*\b(test|grep|egrep|find|head|tail|cat|ls|node|npm|npx|bash|sh|zsh|python3?|jq|awk|sed|curl|git|make|exit|n=|[A-Za-z_]+=)/;
+/** A `verify:` that is a claim in English rather than a command. Conservative
+ *  on purpose, the same bargain as REFERS_BACK: it must have no assertion
+ *  prefix, nothing shell-shaped anywhere in it, and enough words to be a
+ *  sentence — so a bare `./check.sh` or a one-word command is left alone and
+ *  the warning only fires where the author plainly wrote prose. */
+function looksLikeProse(verify) {
+    const v = verify.trim();
+    if (!v || VERIFY_ASSERTION.test(v))
+        return false;
+    if (LOOKS_LIKE_SHELL.test(v))
+        return false;
+    return v.split(/\s+/).length >= 4;
+}
 export function lintFlow(flow, known) {
     const warnings = [];
     const agentNames = known ? new Set(known.agents) : null;
+    // A frontmatter enum the parser could not read, or a step line whose
+    // `[[target]]` is malformed — recorded by parseFlow, reported here at
+    // error level so `foldrun check` fails on it, the way a bad step option
+    // does. A value nothing can read is never a silent default.
+    for (const fp of flow.frontProblems ?? []) {
+        warnings.push({ step: null, level: "error", message: fp, detail: "The line is written but its value cannot be read, so a run would use a silent default instead of what the author meant. Write one of the values the option names, or a target in lower case, digits and dashes." });
+    }
     // Cron's oldest trap, and an expensive one: when day-of-month AND
     // day-of-week are both restricted they are OR'd, not AND'd — the scheduler
     // does it too, correctly (`domRestricted && dowRestricted` → `domOk ||
@@ -60,6 +103,20 @@ export function lintFlow(flow, known) {
                 "a second pair of eyes with `!` (or `approve: true`), or drop the approvers: line.",
         });
     }
+    // A zone nobody can read is two faults at once: the cron fires at the
+    // wrong hour, and every step's calendar quietly falls through to the level
+    // above. Both are invisible in a green run, so `foldrun check` refuses it.
+    const zoneProblem = timezoneProblem(flow.timezone);
+    if (zoneProblem) {
+        warnings.push({
+            step: null,
+            level: "error",
+            message: zoneProblem,
+            detail: "This is the zone the schedule fires in AND the calendar every step in this flow works " +
+                "to. Unreadable, the schedule falls back to UTC and each step inherits the workspace's " +
+                "zone instead of this one.",
+        });
+    }
     // A deadline on a gate that does not exist reads as a safety net and is not
     // one. Same reasoning, said separately because the fix is different.
     if (flow.approveWithin && !flow.steps.some((s) => s.approve || s.ask)) {
@@ -153,6 +210,22 @@ export function lintFlow(flow, known) {
                     "within the key's cap (retry and loop at most 5, max at most 20).",
             });
         }
+        // An instruction written over more than one line. It is read in full
+        // now, but the parser had to decide where it stopped, and the line
+        // below a wrapped instruction is one edit away from being prose. Said
+        // out loud so an author who meant to wrap can see it, and one who did
+        // not can see what got joined on.
+        if (step.wrapped) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                message: `"${step.subflow ?? step.agent}" has an instruction spread over more than one line`,
+                detail: "A step's instruction ends where the step ends: the indented lines directly under it " +
+                    "are joined on, and the first blank line, option, heading, bullet or unindented line " +
+                    "finishes it. Put the whole instruction on the step's own line — one line, however " +
+                    "long — so what the agent is told does not depend on where the paragraph below begins.",
+            });
+        }
         // The first group starts with context = null. An instruction that points
         // at earlier output therefore points at nothing.
         if (inFirstGroup && step.instruction && REFERS_BACK.test(step.instruction)) {
@@ -164,6 +237,29 @@ export function lintFlow(flow, known) {
                     "invent what it was asked to review rather than fail. Move it to a later group.",
             });
         }
+        // `../../storage/…` still works everywhere; `workspace/storage/…` is the
+        // spelling that also works in a shell, and the one the docs teach. Said
+        // once per step, advisory — never an error on a path that resolves.
+        {
+            const rowsOf = step.when ? whenRowsPath(step.when) : null;
+            const spots = [
+                step.eachPath ? ["each: rows of", step.eachPath] : null,
+                rowsOf ? ["when: rows of", rowsOf] : null,
+                step.verify ? ["verify:", step.verify] : null,
+                step.schemaPath ? ["schema:", step.schemaPath] : null,
+                step.instruction ? ["the instruction", step.instruction] : null,
+            ].filter((x) => !!x && /\.\.\/\.\.\/(storage|state)\b/.test(x[1]));
+            if (spots.length) {
+                warnings.push({
+                    step: i,
+                    line: step.line,
+                    kind: "spelling",
+                    message: `"${step.subflow ?? step.agent}" writes ../../storage or ../../state in ${spots.map((x) => x[0]).join(", ")}`,
+                    detail: "It still works. The documented spelling is workspace/storage/… and workspace/state/… — " +
+                        "the same place, and it also resolves in the shell and in scripts.",
+                });
+            }
+        }
         // A gate with no `preview:` shows only the previous step's reply and
         // whatever files that reply happens to name. The person deciding sees a
         // summary, not the thing — unless the agent remembered.
@@ -177,6 +273,41 @@ export function lintFlow(flow, known) {
                     "always sees the document, not a pointer, even when the agent forgets to name it.",
             });
         }
+        // A step that can act on the outside world, with nothing to say whether
+        // it did. The two answers are a check the runtime can fail on, or a
+        // person; either is fine, neither is not. This is the one lint here that
+        // is an error: every other structural warning costs a reread, and this
+        // one costs a send nobody can take back.
+        if (known?.outwardAgents?.includes(step.agent ?? "") && !step.verify && !step.approve && !step.ask) {
+            warnings.push({
+                step: step.group,
+                line: step.line,
+                level: "error",
+                kind: "outward",
+                message: `[[${step.agent}]] can act outside this workspace and this step has no verify: and no gate`,
+                detail: "A step that sends, posts, buys or publishes needs one of two things: a `verify:` the " +
+                    "runtime can fail the step on — a receipt file, a ledger row, the reply's own verdict " +
+                    "line — or a person, with `!` or `ask:`. Without either, a step that sent nothing and a " +
+                    "step that sent everything end the same way: reported as done.",
+            });
+        }
+        // retry: re-runs a failed step from the start. For a step that sends,
+        // a failure can come after the send — the verify: or the JSON check
+        // failed on a step whose email went — and the retry sends it again. The
+        // runner declines that one retry (see actedThenFailedCheck in runner.ts)
+        // but a crash mid-send still reruns; the author should know.
+        if (known?.outwardAgents?.includes(step.agent ?? "") && step.retry) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                kind: "outward",
+                message: `[[${step.agent}]] can act outside this workspace and this step has retry: ${step.retry}`,
+                detail: "A retry runs the whole step again, sends included. The runner does not retry a failure " +
+                    "that came from the check after the step's tools ran, but an attempt that failed mid-way — " +
+                    "a timeout, a crash, a provider error after the first send — is retried and may repeat " +
+                    "what it already did. Make the send idempotent (check a ledger before sending), or drop retry:.",
+            });
+        }
         // `each: items` fans out over DATA, and only an `output: json` step in
         // an earlier group produces any. Without one the step expands to
         // nothing every time, quietly — the exact failure this file exists for.
@@ -210,6 +341,42 @@ export function lintFlow(flow, known) {
                 detail: "schema: describes the JSON value an output: json step returns. Without output: json nothing is parsed, so nothing is checked. Add `output: json`.",
             });
         }
+        // The step's own agent. `delegate:` and `on-fail:` are checked below and
+        // the step's target was not, which is the reference that stops the run
+        // rather than degrading it: the runner reaches the step, finds nothing to
+        // run and fails it with `agent "<name>" not found in workspace`. A
+        // scheduled flow does that at 3am, three times, before anyone looks.
+        if (agentNames && step.agent && !step.subflow && !agentNames.has(step.agent)) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                level: "error",
+                message: `[[${step.agent}]] is not an agent in this workspace`,
+                detail: "This step has nothing to run. Every run of this flow fails here. Check the spelling " +
+                    "against `agents/<name>/agent.md` — the name is the folder's, not the file's heading — " +
+                    "or add the agent.",
+            });
+        }
+        // A `verify:` written as a sentence. Two dialects share the key: a line
+        // beginning `contains:`, `not-contains:`, `matches:`, `file:` or
+        // `judge:` is an assertion, and ANYTHING else is handed to a shell. So
+        // `verify: the reply names the clone it made` runs a program called
+        // `the`, exits 127, and fails a step that did its job perfectly — every
+        // run, with an error about bash that says nothing about the flow. The
+        // fix is one word: the same sentence behind `judge:` is graded by a
+        // model, which is what the author meant.
+        if (step.verify && looksLikeProse(step.verify)) {
+            warnings.push({
+                step: i,
+                line: step.line,
+                level: "error",
+                message: `verify: reads as a sentence, so it will be run as a shell command`,
+                detail: `\`${step.verify.slice(0, 60)}${step.verify.length > 60 ? "…" : ""}\` has no assertion ` +
+                    "prefix, so the runtime executes it: the first word becomes the program and the step " +
+                    "fails with `command not found`. Put `judge: ` in front to have a model grade the " +
+                    "claim, or write it as a shell command that exits 0 when the claim holds.",
+            });
+        }
         // A step's OTHER agent references — the ones no parser validates,
         // because they are options rather than the step's target. Both fail
         // silently and at the worst possible moment: a misspelled `delegate:`
@@ -249,7 +416,8 @@ export function lintFlow(flow, known) {
             });
         }
         // `when:` tests the previous results, which the first group doesn't have.
-        if (inFirstGroup && step.when) {
+        // `when: rows of` reads a file instead, which may well exist already.
+        if (inFirstGroup && step.when && whenRowsPath(step.when) === null) {
             warnings.push({
                 step: i,
                 line: step.line,
@@ -258,6 +426,23 @@ export function lintFlow(flow, known) {
                     "always be skipped. Move it after the step whose output it depends on.",
             });
         }
+        // A `[[flow:x]]` step is spliced in as the other flow's own steps, and
+        // only its `?` and its instruction survive the splice. Everything else
+        // written under it was dropped without a word — a `when:` that never
+        // gated, a `!` that never asked.
+        if (step.subflow) {
+            const dropped = SUBFLOW_DROPPED.filter(([field]) => step[field] !== undefined).map(([, name]) => name);
+            if (dropped.length) {
+                warnings.push({
+                    step: i,
+                    line: step.line,
+                    message: `"flow:${step.subflow}" has ${dropped.join(", ")}, which a nested flow ignores`,
+                    detail: "A nested flow runs as its own steps, with their own options; what is written under the " +
+                        "[[flow:…]] line is not applied to them. Put the option on the steps inside that flow, " +
+                        "or make this an agent step.",
+                });
+            }
+        }
     });
     // The same agent twice in one parallel group gets two identical contexts and
     // no way to divide the work — almost always a drag that landed wrong.
@@ -280,6 +465,43 @@ export function lintFlow(flow, known) {
                 });
             }
         }
+        // A gate parks its whole group, and on approval every step in it starts
+        // together. So `5. [[editor]]` beside `5! [[publisher]]` does not mean
+        // "edit, then ask, then publish": the editor waits for the approval too,
+        // and the publisher runs alongside it, reading files the editor has not
+        // written yet. medium-desk's publisher did exactly that on 2026-09-28
+        // (run-mukdjeh8-cr66): post.json was still empty when it started.
+        const gated = (s) => Boolean(s.approve || s.ask || s.waitFor === "event");
+        const gates = steps.filter(gated);
+        const others = steps.filter((s) => !gated(s));
+        if (gates.length && others.length) {
+            const name = (s) => (s.subflow ? `flow:${s.subflow}` : s.agent);
+            warnings.push({
+                step: flow.steps.indexOf(gates[0]),
+                line: gates[0].line,
+                message: `"${name(gates[0])}" waits for a person but shares number ${group} with "${others.map(name).join('", "')}"`,
+                detail: "Steps with the same number run together. The gate holds all of them until it is " +
+                    "approved, then they start at once — so the gated step cannot use what the others " +
+                    `produce, and the approver sees none of it. To run the gated step after them, number it ${group + 1}.`,
+            });
+        }
+    }
+    // A number with nothing under it is harmless to the runner, which only
+    // orders groups, but it is almost always one step numbered twice: 3, 3, 4,
+    // 5, 5!, 7 is a renumbering that missed the 5! that was meant to be 6.
+    const numbers = [...byGroup.keys()].sort((a, b) => a - b);
+    for (let i = 1; i < numbers.length; i++) {
+        if (numbers[i] - numbers[i - 1] < 2)
+            continue;
+        const missing = numbers[i - 1] + 1 === numbers[i] - 1 ? `${numbers[i - 1] + 1}` : `${numbers[i - 1] + 1} to ${numbers[i] - 1}`;
+        const shared = [...byGroup.entries()].filter(([, s]) => s.length > 1).map(([g]) => g);
+        warnings.push({
+            step: null,
+            message: `step numbers go from ${numbers[i - 1]} to ${numbers[i]}; nothing is numbered ${missing}`,
+            detail: "The same number means \"run together\", so a gap usually means a step kept an old number " +
+                "after a renumbering" +
+                (shared.length ? ` — ${shared.map((g) => `number ${g}`).join(", ")} has more than one step; check whether one of them belongs in the gap.` : "."),
+        });
     }
     return warnings;
 }

package/dist/src/flow-patterns.d.ts

@@ -0,0 +1,141 @@
+import { type FlowStep } from "./store.ts";
+import { type Groups } from "./arrange.ts";
+import { type RemovalImpact } from "./step-removal.ts";
+/** A flow's steps as groups of indices into its parsed steps — what
+ *  reorderFlowSteps and the arrange helpers take. */
+export declare function flowGroups(steps: FlowStep[]): Groups;
+/** The step options a pattern writes. Everything else in a step stays the
+ *  author's (and updateFlowStep's) business. */
+export declare const PATTERN_OPTION_KEYS: readonly ["ask", "wait", "on-fail", "each", "max", "loop", "until", "verify", "case", "else", "when", "retry", "approve"];
+export type PatternOptionKey = (typeof PATTERN_OPTION_KEYS)[number];
+export type PatternOptions = Partial<Record<PatternOptionKey, string | null>>;
+export type PatternEdit = 
+/** Chain (at.rail: its own group there) or Parallel (at.column: join
+ *  the group in that column). Rail 0 is before every group. */
+{
+    op: "insert";
+    target: string;
+    subflow?: boolean;
+    instruction?: string;
+    at: {
+        rail: number;
+    } | {
+        column: number;
+    };
+    options?: PatternOptions;
+}
+/** Router: a triage step, then one group of case:/else: branches. */
+ | {
+    op: "router";
+    router: string;
+    instruction?: string;
+    rail: number;
+    cases: {
+        value: string;
+        target: string;
+    }[];
+    else?: string;
+}
+/** Fan-out, evaluator loop, ask, wait, rescue: options on one step. */
+ | {
+    op: "options";
+    step: number;
+    set: PatternOptions;
+}
+/** Approval gate: the `!` marker. */
+ | {
+    op: "approve";
+    step: number;
+    on: boolean;
+}
+/** Delete one step (removeStep). */
+ | {
+    op: "remove";
+    step: number;
+}
+/** Copy one step beside itself (duplicateStep). */
+ | {
+    op: "duplicate";
+    step: number;
+}
+/** Copied step markdown, placed (pasteSteps). */
+ | {
+    op: "paste";
+    text: string;
+    at: {
+        rail: number;
+    } | {
+        column: number;
+    };
+};
+/** A new step, placed; the file, the new step's index and its column. */
+declare function insertFlowStepLF(raw: string, o: {
+    target: string;
+    subflow?: boolean;
+    instruction?: string;
+    at: {
+        rail: number;
+    } | {
+        column: number;
+    };
+    options?: PatternOptions;
+}): {
+    text: string;
+    index: number;
+    column: number;
+};
+/**
+ * Paste copied steps (stepSource output, one block or several) into a flow.
+ * Steps copied with the same group number stay parallel with each other.
+ * `{ rail }` places the pasted groups as their own consecutive groups there
+ * (0 is before every group); `{ column }` puts every pasted step in that
+ * existing group. Groups renumber; prose stays where it was. Returns the
+ * file and the pasted steps' indices in it. Refused when the paste does not
+ * parse as those steps, or when `check` would gain an error.
+ */
+declare function pasteStepsLF(raw: string, text: string, at: {
+    rail: number;
+} | {
+    column: number;
+}): {
+    text: string;
+    indices: number[];
+};
+export declare const setStepOptions: (raw: string, index: number, set: PatternOptions) => string;
+export declare const setStepApprove: (raw: string, index: number, on: boolean) => string;
+export declare function insertFlowStep(...[raw, o]: Parameters<typeof insertFlowStepLF>): ReturnType<typeof insertFlowStepLF>;
+export declare const removeStepImpact: (raw: string, index: number) => RemovalImpact;
+export declare const removeStep: (raw: string, index: number) => string;
+export declare const stepSource: (raw: string, index: number) => string;
+export declare const duplicateStep: (raw: string, index: number) => string;
+export declare function pasteSteps(...[raw, text, at]: Parameters<typeof pasteStepsLF>): ReturnType<typeof pasteStepsLF>;
+export declare const applyPatternEdit: (raw: string, edit: PatternEdit) => string;
+/** The frontmatter list fields an agent's team lives in: whom it delegates
+ *  to, whom it consults, and what it may do (`ask` among them). */
+export declare const TEAM_LIST_KEYS: readonly ["subagents", "agents", "tools"];
+export type TeamListKey = (typeof TEAM_LIST_KEYS)[number];
+/** The names a frontmatter list holds, read the way the file says them. */
+export declare function frontmatterList(raw: string, key: string): string[];
+/**
+ * Add `name` to, or remove it from, the list under `key`, touching only the
+ * lines that list is on. Flow style (`key: [a, b]`) stays flow style, block
+ * style stays block style, a trailing `# comment` stays put, and the other
+ * items keep their spelling. A list emptied by a removal is written
+ * `key: []` rather than deleted: the file still says "none", which for
+ * `tools:` is not the same as saying nothing.
+ */
+export declare function editFrontmatterList(raw: string, key: string, name: string, action: "add" | "remove"): string;
+/** A YAML scalar for a one-line value: plain when plain reads back as the
+ *  same string, double-quoted (JSON is valid YAML) when it would not. */
+export declare function yamlScalar(value: string): string;
+/** Set one scalar key — `description:`, `model:`. Replaces its line (and the
+ *  indented lines of a `>`/`|` block under it); absent, it goes right after
+ *  `name:`, or last. */
+export declare function setFrontmatterScalar(raw: string, key: string, value: string): string;
+/** A new agent file: the template with the answers to "what is it for"
+ *  and "which model" written into it, the rest as the template wrote it. */
+export declare function newAgentFile(template: string, o: {
+    description?: string;
+    model?: string;
+}): string;
+export {};