@falai/agent 4.0.0-alpha.2 → 4.0.0-alpha.20

package/dist/core/FlowSpec.js

@@ -17,7 +17,8 @@
  */
 import { FlowConfigurationError } from "../types/errors.js";
 import { isDuration } from "../utils/duration.js";
-import { toWireSchema } from "../utils/schema.js";
+import { splitPhrases } from "../utils/phrases.js";
+import { extractMode, toWireSchema } from "../utils/schema.js";
 // ── fromSpec / toSpec ───────────────────────────────────────────────────
 /**
  * A spec as a typed flow. The slugs and names inside a spec are strings from
@@ -27,9 +28,7 @@ import { toWireSchema } from "../utils/schema.js";
  */
 export function fromSpec(spec) {
     const clean = stripNulls(spec);
-    if (!Array.isArray(clean.steps)) {
-        throw problem(`flow "${clean.id}"`, "has no steps list", "Write steps as a list, even an empty one.");
-    }
+    checkShape(clean);
     const { steps, ...rest } = clean;
     const flow = { ...rest, steps: steps.map(fromStepSpec) };
     return flow;
@@ -49,6 +48,7 @@ export function toSpec(flow) {
         on: flow.on?.map((trigger, i) => triggerToSpec(trigger, at(`trigger #${i + 1}`))),
         anchor: flow.anchor,
         while: jsonPred(flow.while, at("while")),
+        collect: flow.collect,
         clearOnStart: flow.clearOnStart,
         steps: flow.steps.map((step) => stepToSpec(step, at(`step "${step.id}"`))),
         onEnd: flow.onEnd,
@@ -96,11 +96,13 @@ function stepToSpec(step, at) {
         instructions: step.instructions?.map((ins, i) => instructionToSpec(ins, `${at} instructions[${i}]`)),
     };
     if (step.collect !== undefined) {
-        return compact({ ...base, kind: "collect", collect: step.collect, prompt: step.prompt, ...talk });
+        return compact({ ...base, kind: "collect", collect: step.collect, prompt: step.prompt, question: step.question, ...talk });
     }
     if (step.prompt === undefined) {
         throw problem(at, "has neither prompt nor collect", "A talk step needs a guideline, fields to collect, or both.");
     }
+    if (step.question !== undefined)
+        throw questionWithoutCollect(at);
     return compact({ ...base, kind: "prompt", prompt: step.prompt, ...talk });
 }
 /** `typeof step.wait` alone does not narrow the union for tsc; this does. */
@@ -116,8 +118,12 @@ function jsonPredRequired(pred, at) {
     }
     return pred;
 }
-const BUILT_IN_CONDITIONS = ["equals", "known", "silenced"];
+export const BUILT_IN_CONDITIONS = ["equals", "known", "silenced"];
 const DURATION_HINT = 'Write a number and a unit: "30s", "5m", "24h" or "3d".';
+/** The four keys one of which makes an `on[]` entry a trigger. */
+const TRIGGER_KINDS = ["message", "mention", "silence", "event"];
+const ON_END = ["end", "stay", "reset"];
+const INSTRUCTION_KINDS = ["must", "never", "should"];
 /**
  * Check a flow, typed or as a spec, against the agent's registries. Throws
  * `FlowConfigurationError` on the first problem that would break at runtime;
@@ -126,16 +132,14 @@ const DURATION_HINT = 'Write a number and a unit: "30s", "5m", "24h" or "3d".';
 export function validateFlow(input, registries) {
     // Nulls mean "not set" in a spec; a typed flow has none, so one pass serves both forms.
     const flow = stripNulls(input);
-    const { fields, actions = {}, events = {}, conditions = {}, tools = [] } = registries;
+    checkShape(flow);
+    const { fields, actions = {}, events = {}, tools = [] } = registries;
     const toolIds = new Set(tools.map((tool) => tool.id));
     const warnings = [];
     if (typeof flow.id !== "string" || flow.id === "") {
         throw problem("flow", "has no id", "Give the flow a short unique id.");
     }
     const flowAt = `flow "${flow.id}"`;
-    if (!Array.isArray(flow.steps)) {
-        throw problem(flowAt, "has no steps list", "Write steps as a list, even an empty one.");
-    }
     const index = new Map();
     flow.steps.forEach((step, i) => {
         if (typeof step.id !== "string" || step.id === "") {
@@ -152,48 +156,14 @@ export function validateFlow(input, registries) {
     if (flow.on?.length && flow.steps.length === 0) {
         throw problem(flowAt, "has triggers but no steps", "Add at least one step or remove `on`.");
     }
-    const slug = (name, at, where) => {
-        if (!own(fields, name)) {
-            throw problem(at, `unknown field "${name}" in ${where}`, "Add it to the agent's fields or fix the slug.");
-        }
-    };
+    const slug = (name, at, where) => checkSlug(fields, name, at, where);
     const toolNames = (names, at) => {
         for (const name of names ?? []) {
             if (!toolIds.has(name))
                 throw problem(at, `unknown tool "${name}"`, "Register it in the agent's tools or fix the name.");
         }
     };
-    const pred = (value, at, where) => {
-        if (value === undefined || typeof value === "function")
-            return;
-        for (const [name, arg] of Object.entries(value)) {
-            if (name === "equals") {
-                if (arg === null || typeof arg !== "object" || Array.isArray(arg)) {
-                    throw problem(at, `${where}.equals is not an object`, "Write equals as { field: value }.");
-                }
-                for (const [field, given] of Object.entries(arg)) {
-                    slug(field, at, `${where}.equals`);
-                    const def = fields[field];
-                    if (!matches(def, given)) {
-                        throw problem(at, `${where}.equals gives "${field}" a ${describe(given)}, but the field is a ${def.type}`, `Write a ${def.type}; values are not coerced.`);
-                    }
-                }
-            }
-            else if (name === "known") {
-                if (!Array.isArray(arg))
-                    throw problem(at, `${where}.known is not a list`, "Write known as [field, ...].");
-                for (const field of arg)
-                    slug(String(field), at, `${where}.known`);
-            }
-            else if (name === "silenced") {
-                if (typeof arg !== "boolean")
-                    throw problem(at, `${where}.silenced is not a boolean`, "Write true or false.");
-            }
-            else if (!own(conditions, name)) {
-                throw problem(at, `unknown condition "${name}" in ${where}`, `Register it in conditions or use ${BUILT_IN_CONDITIONS.join(", ")}.`);
-            }
-        }
-    };
+    const pred = (value, at, where) => checkPred(value, at, where, registries);
     const duration = (value, at, where) => {
         if (value !== undefined && !isDuration(value)) {
             throw problem(at, `${where} has duration "${value}", which does not parse`, DURATION_HINT);
@@ -210,8 +180,16 @@ export function validateFlow(input, registries) {
             }
             return to;
         }
-        if ("flow" in next)
+        if ("flow" in next) {
+            // A templated id resolves per run; only a literal one can be checked now. A warning, not a throw:
+            // a host that drops one bad row keeps the rest of its agent, and the Runner skips this move as flow-gone.
+            const known = registries.flows?.map((f) => f.id);
+            if (known && !next.flow.includes("{{") && !known.includes(next.flow)) {
+                const fix = known.length ? `Use one of ${known.map((id) => `"${id}"`).join(", ")}, or add the flow.` : "Add the flow to the agent.";
+                warnings.push(`${at}: ${where} names flow "${next.flow}", which this agent does not have; a run skips this move with flow-gone. ${fix}`);
+            }
             return undefined;
+        }
         const to = index.get(next.step);
         if (to === undefined) {
             throw problem(at, `${where} points at step "${next.step}", which does not exist`, 'Use an existing step id or "end".');
@@ -241,7 +219,8 @@ export function validateFlow(input, registries) {
                 continue;
             }
             if (!matchesParam(def, value)) {
-                throw problem(at, `parameter "${param}" of action "${name}" must be ${describeDef(def)}, got ${describe(value)}`, "Values are not coerced; write the right type.");
+                const { expected, got, fix } = mismatch(def, value);
+                throw problem(at, `parameter "${param}" of action "${name}" must be ${expected}, got ${got}`, fix);
             }
         }
         for (const param of Object.keys(given)) {
@@ -250,13 +229,31 @@ export function validateFlow(input, registries) {
             }
         }
     };
+    for (const field of flow.collect ?? [])
+        slug(field, flowAt, "collect");
     for (const field of flow.clearOnStart ?? [])
         slug(field, flowAt, "clearOnStart");
+    // A field taken only from the answer to a step that asks it can never be filled when no step asks it.
+    const asked = new Set(flow.steps.flatMap((step) => step.collect ?? []));
+    for (const field of flow.collect ?? []) {
+        if (!asked.has(field) && extractMode(fields[field]) === "asked") {
+            warnings.push(`${flowAt}: collect lists "${field}", which is only taken from the answer to a step that asks it, and no ` +
+                "step does. Add it to a step's collect, or set extract: 'anywhere' on the field.");
+        }
+    }
     pred(flow.while, flowAt, "while");
     toolNames(flow.tools, flowAt);
     flow.instructions?.forEach((ins, i) => pred(ins.if, flowAt, `instructions[${i}].if`));
     flow.on?.forEach((trigger, i) => {
         const at = `${flowAt}, trigger #${i + 1}`;
+        // A trigger that names no kind can never fire, and nothing downstream says
+        // so: the Runner simply never finds it eligible and the flow looks broken
+        // for some other reason. `{ kind: 'message', when: [...] }` — the v3 shape —
+        // lands here, and so does a typo in the one key that matters.
+        if (!TRIGGER_KINDS.some((key) => trigger[key] !== undefined)) {
+            throw problem(at, "names no trigger kind", `A trigger is one of ${TRIGGER_KINDS.map((key) => `\`${key}\``).join(", ")}. ` +
+                "A flow the host starts itself has no `on` at all.");
+        }
         if (trigger.event !== undefined && !own(events, trigger.event)) {
             throw problem(at, `unknown event "${trigger.event}"`, "Register it in events or fix the name.");
         }
@@ -265,6 +262,17 @@ export function validateFlow(input, registries) {
         if (typeof trigger.repeat === "object")
             duration(trigger.repeat.cooldown, at, "repeat.cooldown");
         pred(trigger.if, at, "if");
+        // Phrases opening with `!` rule the trigger out; a list of nothing but
+        // those can never fire, so the flow is dead and nothing would say so.
+        // `message: []` is the deliberate catch-all and stays legal.
+        for (const key of ["message", "mention"]) {
+            const phrases = trigger[key];
+            if (!phrases?.length)
+                continue;
+            if (splitPhrases(phrases).counts.length > 0)
+                continue;
+            throw problem(at, `every ${key} phrase starts with "!", so nothing can ever match it`, `A "!" phrase rules the trigger out. Add at least one plain phrase saying when it should fire${key === "message" ? ", or use an empty list for a catch-all" : ""}.`);
+        }
     });
     flow.steps.forEach((step, i) => {
         const at = `${flowAt}, step "${step.id}"`;
@@ -275,8 +283,13 @@ export function validateFlow(input, registries) {
                 slug(field, at, "collect");
             for (const field of Object.keys(step.ask ?? {}))
                 slug(field, at, "ask");
+            if (step.question !== undefined && !step.collect?.length)
+                throw questionWithoutCollect(at);
             const fields_ = step.collect ?? [];
-            if (step.prompt === undefined && fields_.length > 0 && fields_.every((f) => !step.ask?.[f] && !fields[f].ask)) {
+            if (step.prompt === undefined &&
+                step.question === undefined &&
+                fields_.length > 0 &&
+                fields_.every((f) => !step.ask?.[f] && !fields[f].ask)) {
                 warnings.push(`${at}: collects ${fields_.map((f) => `"${f}"`).join(", ")} with no prompt and no ask; the AI has nothing ` +
                     "to go on. Add a prompt or an ask per field.");
             }
@@ -286,6 +299,12 @@ export function validateFlow(input, registries) {
             if (branch.when === undefined && branch.if === undefined) {
                 throw problem(at, `${where} has neither when nor if`, "Give the branch an AI condition (when) or a code one (if).");
             }
+            // No understand call judges a wait, so an AI condition there never fires. A warning, not a throw: the
+            // flow still runs as it did, a reply goes to `else`, and editors that offered the branch keep their rows.
+            if (branch.when !== undefined && step.wait !== undefined) {
+                warnings.push(`${at}: ${where} is a "when" branch on a wait step, which no call judges, so a reply goes to else. ` +
+                    'Use "if", or move the branch to a talk step.');
+            }
             pred(branch.if, at, `${where}.if`);
             edge(i, branch.then, at, `${where}.then`);
         });
@@ -316,6 +335,232 @@ export function validateFlow(input, registries) {
     });
     return { warnings };
 }
+function checkSlug(fields, name, at, where) {
+    if (!own(fields, name)) {
+        throw problem(at, `unknown field "${name}" in ${where}`, "Add it to the agent's fields or fix the slug.");
+    }
+}
+/**
+ * A predicate's names against the registries: the fields `equals` and `known`
+ * read, and every other key as one of the agent's conditions. A function is
+ * code and passes as is. The agent runs this on its own instructions too.
+ */
+export function checkPred(value, at, where, registries) {
+    if (value === undefined || typeof value === "function")
+        return;
+    const { fields, conditions = {} } = registries;
+    for (const [name, arg] of Object.entries(value)) {
+        if (name === "equals") {
+            if (!isObject(arg)) {
+                throw problem(at, `${where}.equals is not an object`, "Write equals as { field: value }.");
+            }
+            for (const [field, given] of Object.entries(arg)) {
+                checkSlug(fields, field, at, `${where}.equals`);
+                const def = fields[field];
+                if (!matches(def, given)) {
+                    const { listed, expected, got, fix } = mismatch(def, given);
+                    throw listed
+                        ? problem(at, `${where}.equals gives "${field}" ${got}, which is not ${expected}`, fix)
+                        : problem(at, `${where}.equals gives "${field}" ${article(got)} ${got}, but the field is ${expected}`, `Write ${expected}; values are not coerced.`);
+                }
+            }
+        }
+        else if (name === "known") {
+            if (!Array.isArray(arg))
+                throw problem(at, `${where}.known is not a list`, "Write known as [field, ...].");
+            for (const field of arg)
+                checkSlug(fields, String(field), at, `${where}.known`);
+        }
+        else if (name === "silenced") {
+            if (typeof arg !== "boolean")
+                throw problem(at, `${where}.silenced is not a boolean`, "Write true or false.");
+        }
+        else if (!own(conditions, name)) {
+            throw problem(at, `unknown condition "${name}" in ${where}`, `Register it in conditions or use ${BUILT_IN_CONDITIONS.join(", ")}.`);
+        }
+    }
+}
+// ── Shape ───────────────────────────────────────────────────────────────
+/**
+ * The JSON shape, checked before any name is. Stored rows and generated specs
+ * are untrusted: a string where a list belongs used to crash with a raw
+ * TypeError naming no flow, or pass and misbehave at run time (`collect:
+ * "nome"` read as the fields "n", "o", "m", "e").
+ */
+function checkShape(value) {
+    if (!isObject(value))
+        throw problem("flow", `is ${show(value)}, not an object`, "Pass the flow itself: { id, name, steps }.");
+    const flowAt = typeof value.id === "string" ? `flow "${value.id}"` : "flow";
+    if (!Array.isArray(value.steps)) {
+        throw problem(flowAt, "has no steps list", "Write steps as a list, even an empty one.");
+    }
+    text(value, ["description", "anchor"], flowAt);
+    for (const key of ["collect", "clearOnStart", "tools"])
+        listOf(value[key], key, flowAt, "string");
+    oneOf(value.onEnd, "onEnd", ON_END, flowAt);
+    predShape(value.while, "while", flowAt);
+    instructionsShape(value.instructions, flowAt);
+    listOf(value.on, "on", flowAt, "object").forEach((trigger, i) => {
+        const at = `${flowAt}, trigger #${i + 1}`;
+        if (!isObject(trigger))
+            return;
+        listOf(trigger.message, "message", at, "string");
+        listOf(trigger.mention, "mention", at, "string");
+        predShape(trigger.if, "if", at);
+        const { repeat } = trigger;
+        if (repeat !== undefined && repeat !== "once" && repeat !== "always" && !(isObject(repeat) && typeof repeat.cooldown === "string")) {
+            throw problem(at, `repeat is ${show(repeat)}`, 'Use "once", "always" or { cooldown: "24h" }.');
+        }
+    });
+    listOf(value.steps, "steps", flowAt, "object").forEach((step, i) => {
+        if (!isObject(step))
+            return;
+        const at = typeof step.id === "string" ? `${flowAt}, step "${step.id}"` : `${flowAt}, step #${i + 1}`;
+        stepShape(step, at);
+    });
+}
+/** One step: what it does, and every value the right kind of thing. */
+function stepShape(step, at) {
+    // A step that does none of the five things is one the run walks straight
+    // past; one that does two runs only the first, and the other never happens.
+    const kinds = bodyKinds(step);
+    if (kinds.length === 0) {
+        throw problem(at, "does nothing", "A step talks (`prompt` / `collect`), says (`say`), acts (`do`), waits (`wait`) or forks (`if`).");
+    }
+    if (kinds.length > 1) {
+        throw problem(at, `mixes ${and(kinds.map((k) => `"${k}"`))}`, "A step does one thing. Split it into one step per kind.");
+    }
+    // The spec's `kind` must say what the body does; the Runner reads the body.
+    if (step.kind !== undefined && step.kind !== kinds[0]) {
+        throw problem(at, `has kind ${show(step.kind)}, but its body is a "${kinds[0]}" step`, `Set kind to "${kinds[0]}", or change the body to match.`);
+    }
+    text(step, ["say", "prompt", "question"], at);
+    listOf(step.collect, "collect", at, "string");
+    listOf(step.tools, "tools", at, "string");
+    if (step.ask !== undefined && !isObject(step.ask)) {
+        throw problem(at, `ask is ${show(step.ask)}, not an object`, 'Write ask as { field: "how to ask" }.');
+    }
+    if (step.with !== undefined && !isObject(step.with)) {
+        throw problem(at, `with is ${show(step.with)}, not an object`, "Write with as { parameter: value }.");
+    }
+    const { maxAsks } = step;
+    if (maxAsks !== undefined && !(typeof maxAsks === "number" && Number.isInteger(maxAsks) && maxAsks >= 1)) {
+        throw problem(at, `maxAsks is ${show(maxAsks)}, not a whole number of 1 or more`, "Write a number like 3.");
+    }
+    if (isObject(step.wait) && typeof step.wait.event !== "string") {
+        throw problem(at, "wait has no event", 'Write wait: { event: "name" } to wait for an event, or a duration like "1h".');
+    }
+    predShape(step.if, "if", at);
+    for (const key of ["then", "else", "onFail"])
+        nextShape(step[key], key, at);
+    instructionsShape(step.instructions, at);
+    listOf(step.branches, "branches", at, "object").forEach((branch, j) => {
+        if (!isObject(branch))
+            return;
+        const where = `branches[${j}]`;
+        if (branch.when !== undefined && typeof branch.when !== "string") {
+            throw problem(at, `${where}.when is ${show(branch.when)}, not text`, "Write the condition as one sentence.");
+        }
+        predShape(branch.if, `${where}.if`, at);
+        nextShape(branch.then, `${where}.then`, at);
+    });
+}
+/** The kinds a step's body carries, by its keys. A talk step is `collect` with a list, `prompt` with a guideline alone. */
+function bodyKinds(step) {
+    const kinds = [];
+    if (step.collect !== undefined)
+        kinds.push("collect");
+    else if (step.prompt !== undefined)
+        kinds.push("prompt");
+    if (step.say !== undefined)
+        kinds.push("say");
+    if (step.do !== undefined)
+        kinds.push("do");
+    if (step.wait !== undefined)
+        kinds.push(typeof step.wait === "string" ? "wait" : "waitEvent");
+    if (step.if !== undefined)
+        kinds.push("if");
+    return kinds;
+}
+function instructionsShape(value, at) {
+    listOf(value, "instructions", at, "object").forEach((ins, i) => {
+        if (!isObject(ins))
+            return;
+        const where = `instructions[${i}]`;
+        oneOf(ins.kind, `${where}.kind`, INSTRUCTION_KINDS, at);
+        if (typeof ins.prompt !== "string") {
+            throw problem(at, `${where}.prompt is ${show(ins.prompt)}, not text`, "Write the rule as a sentence.");
+        }
+        if (ins.when !== undefined && typeof ins.when !== "string")
+            listOf(ins.when, `${where}.when`, at, "string");
+        predShape(ins.if, `${where}.if`, at);
+    });
+}
+/** A step id, `"end"`, `{ step, clear? }` or `{ flow, input? }`. */
+function nextShape(value, where, at) {
+    if (value === undefined || typeof value === "string")
+        return;
+    if (isObject(value) && (typeof value.step === "string" || typeof value.flow === "string")) {
+        listOf(value.clear, `${where}.clear`, at, "string");
+        return;
+    }
+    throw problem(at, `${where} is ${show(value)}, not a step id or a target`, 'Write a step id, "end", { step: "id" } or { flow: "id" }.');
+}
+/** A condition object, or code on a typed flow. */
+function predShape(value, where, at) {
+    if (value === undefined || typeof value === "function" || isObject(value))
+        return;
+    throw problem(at, `${where} is ${show(value)}, not a condition`, 'Write it as an object, e.g. { known: ["nome"] }.');
+}
+/** Each named key, when set, must be text. */
+function text(owner, keys, at) {
+    for (const key of keys) {
+        const value = owner[key];
+        if (value !== undefined && typeof value !== "string") {
+            throw problem(at, `${key} is ${show(value)}, not text`, `Write ${key} as a string.`);
+        }
+    }
+}
+function oneOf(value, where, allowed, at) {
+    if (value === undefined || (typeof value === "string" && allowed.includes(value)))
+        return;
+    throw problem(at, `${where} is ${show(value)}, which is not one of ${allowed.map((v) => `"${v}"`).join(", ")}`, "Use one of them.");
+}
+/** A list whose items are all strings or all objects; absent reads as empty. */
+function listOf(value, where, at, item) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        const example = item === "string" && typeof value === "string" ? `${where}: ${JSON.stringify([value])}` : `${where} as a list`;
+        throw problem(at, `${where} is ${show(value)}, not a list`, `Write ${example}.`);
+    }
+    value.forEach((entry, i) => {
+        if (item === "string" ? typeof entry !== "string" : !isObject(entry)) {
+            throw problem(at, `${where}[${i}] is ${show(entry)}, not ${item === "string" ? "text" : "an object"}`, `Write each entry of ${where} as ${item === "string" ? "a string" : "an object"}.`);
+        }
+    });
+    return value;
+}
+/** A plain object: not null, not a list, not a function. */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A wrong value as an error names it: short scalars verbatim, anything else by kind. */
+function show(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value.length > 40 ? `${value.slice(0, 37)}...` : value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (value === undefined)
+        return "missing";
+    if (value === null)
+        return "null";
+    return Array.isArray(value) ? "a list" : typeof value === "function" ? "a function" : "an object";
+}
+/** `"a"`, `"a" and "b"`, `"a", "b" and "c"`. */
+function and(items) {
+    return items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}
 function matchesParam(def, value) {
     if (def.type === "array")
         return Array.isArray(value) && value.every((item) => matches(def.items, item));
@@ -336,11 +581,30 @@ function matches(def, value) {
         return true;
     return typeof value !== "boolean" && def.enum.includes(value);
 }
+/**
+ * What a rejected value should have been and what it was. A value of the right type that is
+ * not a listed one names the listed values: "must be a string, got string" would say nothing.
+ */
+function mismatch(def, value) {
+    const scalar = def.type === "array" ? def.items : def;
+    const { enum: allowed, ...typeOnly } = scalar;
+    const items = def.type === "array" && Array.isArray(value) ? value : [value];
+    const off = allowed ? items.findIndex((item) => matches(typeOnly, item) && !matches(scalar, item)) : -1;
+    if (!allowed || off === -1) {
+        return { listed: false, expected: describeDef(def), got: describe(value), fix: "Values are not coerced; write the right type." };
+    }
+    const list = (v) => JSON.stringify(v);
+    return { listed: true, expected: `one of ${allowed.map(list).join(", ")}`, got: list(items[off]), fix: "Use one of the listed values." };
+}
 function describe(value) {
     return Array.isArray(value) ? "list" : value === null ? "null" : typeof value;
 }
 function describeDef(def) {
-    return def.type === "array" ? `a list of ${def.items.type}` : `a ${def.type}`;
+    return def.type === "array" ? `a list of ${def.items.type}s` : `${article(def.type)} ${def.type}`;
+}
+/** "an integer", "a string". A vowel test rather than one hard-coded type, so a new type reads right for free. */
+function article(type) {
+    return /^[aeiou]/.test(type) ? "an" : "a";
 }
 // ── flowSpecSchema ──────────────────────────────────────────────────────
 const STRING = { type: "string" };
@@ -398,6 +662,8 @@ export function flowSpecSchema(registries) {
             : undefined,
     ]);
     const branches = orNull(list(union([closed({ when: STRING, then: next }), closed({ if: condition, then: next })]), "Exits judged while the step asks"));
+    // No understand call judges a wait, so its branches are code only.
+    const waitBranches = orNull(list(closed({ if: condition, then: next }), "Exits checked by code when the lead replies before the wait ends"));
     const stepBase = { id: STRING, label: orNull(STRING), then: nextOrNull };
     const step = union([
         closed({ ...stepBase, kind: enumOf(["prompt"]), prompt: { type: "string", description: "Guideline for the AI's next message" }, branches }),
@@ -407,6 +673,7 @@ export function flowSpecSchema(registries) {
                 kind: enumOf(["collect"]),
                 collect: { ...slugList, description: "Fields the AI asks for until they are known" },
                 prompt: orNull(STRING),
+                question: orNull({ type: "string", description: "A fixed first question, sent word for word; later asks are the AI's" }),
                 maxAsks: orNull({ ...INTEGER, description: "Times a field may be asked before it is skipped; default 3" }),
                 branches,
             }),
@@ -424,7 +691,7 @@ export function flowSpecSchema(registries) {
             wait: { ...duration, description: "Park this long; then = time passed, else = the lead replied" },
             businessHours: orNull(BOOLEAN),
             else: nextOrNull,
-            branches,
+            branches: waitBranches,
         }),
         eventNames.length
             ? closed({
@@ -449,9 +716,10 @@ export function flowSpecSchema(registries) {
         on: orNull(list(trigger, "What starts a run; null = started by hand")),
         anchor: orNull({ type: "string", description: "'session' (default) or a host anchor such as 'lead'" }),
         while: orNull({ ...condition, description: "The run ends when this stops holding" }),
+        collect: slugList && orNull({ ...slugList, description: "The data this flow needs; its steps ask for it in order, and any of it the lead gives is noted" }),
         clearOnStart: slugList && orNull({ ...slugList, description: "Fields to forget when a run starts" }),
         steps: list(step, "In order; a run moves to the next step unless `then` says otherwise"),
-        onEnd: orNull(enumOf(["end", "stay", "reset"], "After the last step: end the run, stay on it, or reset to the first")),
+        onEnd: orNull(enumOf(["end", "stay", "reset"], "After the last step: end the run, stay on the last talk step it took answering every message, or reset to the first")),
         instructions: orNull(list(instruction, "Rules that apply only inside this flow")),
     });
 }
@@ -492,6 +760,9 @@ function orNull(schema) {
     return typeof schema.type === "string" ? { ...schema, type: [schema.type, "null"] } : { anyOf: [schema, NULL] };
 }
 // ── Shared helpers ──────────────────────────────────────────────────────
+function questionWithoutCollect(at) {
+    return problem(at, "has a question but collects nothing", "A fixed question asks for fields: add collect, or send the text with a say step.");
+}
 function problem(at, what, fix) {
     return new FlowConfigurationError(`[FlowConfigurationError] ${at}: ${what}. ${fix}`);
 }