@falai/agent 4.0.0-alpha.14 → 4.0.0-alpha.15

package/README.md

@@ -68,13 +68,15 @@ console.log(r.messages[0]?.text);
 ## Install
 
 ```bash
-bun add @falai/agent
+bun add @falai/agent@alpha
 # or
-npm install @falai/agent
+npm install @falai/agent@alpha
 # or
-pnpm add @falai/agent
+pnpm add @falai/agent@alpha
 ```
 
+4.0 is in alpha. Plain `@falai/agent`, with no tag, still installs 3.x, and the examples here will not compile against it.
+
 Requires Node 22.12+ or Bun 1.0+. Set a provider API key in your environment (for example `GEMINI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, or `DEEPSEEK_API_KEY`).
 
 ## License

package/dist/cjs/core/Agent.js

@@ -101,6 +101,14 @@ function compactionOptions(options) {
 }
 /** Every name a flow uses must resolve now, not on the turn that first reaches it. */
 function validate(options) {
+    // A host condition under a built-in's name is never called: the built-in answers first.
+    for (const name of Object.keys(options.conditions ?? {})) {
+        if (FlowSpec_js_1.BUILT_IN_CONDITIONS.includes(name)) {
+            throw new errors_js_1.FlowConfigurationError(`[FlowConfigurationError] condition "${name}" shadows a built-in: ${FlowSpec_js_1.BUILT_IN_CONDITIONS.join(", ")} are reserved. Rename it.`);
+        }
+    }
+    // An agent-level `if` is judged on every turn, so an unknown name here would throw on every turn.
+    options.instructions?.forEach((ins, i) => (0, FlowSpec_js_1.checkPred)(ins.if, "agent", `instructions[${i}].if`, options));
     const ids = new Set();
     for (const flow of options.flows ?? []) {
         if (ids.has(flow.id)) {
@@ -122,6 +130,7 @@ function validate(options) {
     }
     const { idle } = options;
     if (idle && idle !== "silent") {
+        idle.instructions?.forEach((ins, i) => (0, FlowSpec_js_1.checkPred)(ins.if, "idle", `instructions[${i}].if`, options));
         const known = new Set((options.tools ?? []).map((tool) => tool.id));
         for (const name of idle.tools ?? []) {
             if (!known.has(name)) {

package/dist/cjs/core/Agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../../../src/core/Agent.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/CompactionEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CompactionEngine.d.ts","sourceRoot":"","sources":["../../../src/core/CompactionEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAGlF,qBAAa,gBAAgB;IACzB;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IA4BxD;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM;IAiBrD;;;;;;OAMG;IACH,MAAM,CAAC,qBAAqB,CACxB,OAAO,EAAE,WAAW,EAAE,EACtB,iBAAiB,EAAE,MAAM,GAC1B,WAAW,EAAE;IAkBhB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IA2B3B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAc/B;;;OAGG;mBACkB,iBAAiB;IA+BtC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAWjC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAgCjC;;;;;;;;;;;OAWG;WACU,eAAe,CACxB,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,EAAE,iBAAiB,GAC3B,OAAO,CAAC,gBAAgB,CAAC;CAkG/B"}
+{"version":3,"file":"CompactionEngine.d.ts","sourceRoot":"","sources":["../../../src/core/CompactionEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAGlF,qBAAa,gBAAgB;IACzB;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAmCxD;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM;IAiBrD;;;;;;OAMG;IACH,MAAM,CAAC,qBAAqB,CACxB,OAAO,EAAE,WAAW,EAAE,EACtB,iBAAiB,EAAE,MAAM,GAC1B,WAAW,EAAE;IAkBhB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IA2B3B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAc/B;;;OAGG;mBACkB,iBAAiB;IA+BtC;;;;;;;;;OASG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAWjC;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAgCjC;;;;;;;;;;;OAWG;WACU,eAAe,CACxB,OAAO,EAAE,WAAW,EAAE,EACtB,OAAO,EAAE,iBAAiB,GAC3B,OAAO,CAAC,gBAAgB,CAAC;CAkG/B"}

package/dist/cjs/core/CompactionEngine.js

@@ -20,18 +20,23 @@ class CompactionEngine {
      * Validate CompactionOptions. Throws on invalid values.
      */
     static validateOptions(options) {
+        if (typeof options.maxTokens !== "number" || !(options.maxTokens > 0)) {
+            throw new Error(`[CompactionEngine] maxTokens is ${String(options.maxTokens)}: it must be above 0. ` +
+                `Set it to the most history, in tokens, each call should carry, e.g. 100000.`);
+        }
         if (typeof options.compactionThreshold !== "number" ||
             options.compactionThreshold < 0.5 ||
             options.compactionThreshold > 0.95) {
-            throw new Error(`compactionThreshold must be between 0.5 and 0.95, got ${options.compactionThreshold}`);
+            throw new Error(`[CompactionEngine] compactionThreshold is ${String(options.compactionThreshold)}: it must be between 0.5 and 0.95. ` +
+                `Use 0.8 unless you measured otherwise.`);
         }
         if (typeof options.preserveRecentCount !== "number" ||
             options.preserveRecentCount < 2) {
-            throw new Error(`preserveRecentCount must be >= 2, got ${options.preserveRecentCount}`);
+            throw new Error(`[CompactionEngine] preserveRecentCount is ${String(options.preserveRecentCount)}: it must be 2 or more. Use 4, the default.`);
         }
         if (typeof options.maxToolResultChars !== "number" ||
             options.maxToolResultChars <= 0) {
-            throw new Error(`maxToolResultChars must be > 0, got ${options.maxToolResultChars}`);
+            throw new Error(`[CompactionEngine] maxToolResultChars is ${String(options.maxToolResultChars)}: it must be above 0. Use 5000, the default.`);
         }
     }
     /**

package/dist/cjs/core/CompactionEngine.js.map

@@ -1 +1 @@
-{"version":3,"file":"CompactionEngine.js","sourceRoot":"","sources":["../../../src/core/CompactionEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CompactionEngine.js","sourceRoot":"","sources":["../../../src/core/CompactionEngine.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/FlowSpec.d.ts

@@ -99,8 +99,16 @@ export interface FlowSpec {
     instructions?: InstructionSpec[];
     tools?: string[];
 }
-/** What a flow's names resolve against: the agent's fields, actions, events, conditions and tools. */
-export type Registries = Pick<AgentOptions, "fields" | "actions" | "events" | "conditions" | "tools">;
+/**
+ * What a flow's names resolve against: the agent's fields, actions, events,
+ * conditions and tools. With `flows`, a literal `{ flow }` target must name
+ * one of them; the agent passes its own.
+ */
+export type Registries = Pick<AgentOptions, "fields" | "actions" | "events" | "conditions" | "tools"> & {
+    flows?: ReadonlyArray<{
+        id: string;
+    }>;
+};
 /**
  * A spec as a typed flow. The slugs and names inside a spec are strings from
  * storage, so the result is typed by claim: `validateFlow` (which the agent
@@ -110,6 +118,9 @@ export type Registries = Pick<AgentOptions, "fields" | "actions" | "events" | "c
 export declare function fromSpec<C = unknown, D = LooseData>(spec: FlowSpec): Flow<C, D>;
 /** Throws `FlowConfigurationError` when the flow carries a function predicate: it cannot be stored. */
 export declare function toSpec<C, D extends LooseData>(flow: Flow<C, D>): FlowSpec;
+/** A read-only view that a typed Flow and a spec-derived Flow both fit; the validator only reads. */
+type LoosePred = ((ctx: never) => boolean) | Record<string, unknown>;
+export declare const BUILT_IN_CONDITIONS: string[];
 /**
  * Check a flow, typed or as a spec, against the agent's registries. Throws
  * `FlowConfigurationError` on the first problem that would break at runtime;
@@ -118,6 +129,12 @@ export declare function toSpec<C, D extends LooseData>(flow: Flow<C, D>): FlowSp
 export declare function validateFlow<C = unknown, D = LooseData>(input: Flow<C, D> | FlowSpec, registries: Registries): {
     warnings: string[];
 };
+/**
+ * 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 declare function checkPred(value: LoosePred | undefined, at: string, where: string, registries: Registries): void;
 /**
  * FlowSpec's JSON schema with this workspace's actions (each with its
  * parameter schema), events, conditions and field slugs as enums. Every

package/dist/cjs/core/FlowSpec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FlowSpec.d.ts","sourceRoot":"","sources":["../../../src/core/FlowSpec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"FlowSpec.d.ts","sourceRoot":"","sources":["../../../src/core/FlowSpec.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core/FlowSpec.js

@@ -17,9 +17,11 @@
  * nulls dropped, and the identity on a spec that had none.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILT_IN_CONDITIONS = void 0;
 exports.fromSpec = fromSpec;
 exports.toSpec = toSpec;
 exports.validateFlow = validateFlow;
+exports.checkPred = checkPred;
 exports.flowSpecSchema = flowSpecSchema;
 const errors_js_1 = require("../types/errors.js");
 const duration_js_1 = require("../utils/duration.js");
@@ -34,9 +36,7 @@ const schema_js_1 = require("../utils/schema.js");
  */
 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;
@@ -126,12 +126,12 @@ function jsonPredRequired(pred, at) {
     }
     return pred;
 }
-const BUILT_IN_CONDITIONS = ["equals", "known", "silenced"];
+exports.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"];
-/** The six keys one of which makes a step do something. */
-const STEP_DOES = ["prompt", "collect", "say", "do", "wait", "if"];
+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;
@@ -140,16 +140,14 @@ const STEP_DOES = ["prompt", "collect", "say", "do", "wait", "if"];
 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 === "") {
@@ -166,48 +164,14 @@ 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 && !(0, duration_js_1.isDuration)(value)) {
             throw problem(at, `${where} has duration "${value}", which does not parse`, DURATION_HINT);
@@ -224,8 +188,16 @@ 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".');
@@ -312,13 +284,6 @@ function validateFlow(input, registries) {
     });
     flow.steps.forEach((step, i) => {
         const at = `${flowAt}, step "${step.id}"`;
-        // Same reasoning as the trigger above: a step that does none of the five
-        // things is a step the run walks straight past, silently. `kind` alone is
-        // not enough — the spec form drops it and keeps the body, so what counts
-        // is whether the body says what to do.
-        if (!STEP_DOES.some((key) => step[key] !== undefined)) {
-            throw problem(at, "does nothing", "A step talks (`prompt` / `collect`), says (`say`), acts (`do`), waits (`wait`) or forks (`if`).");
-        }
         const thenTo = edge(i, step.then, at, "then");
         edge(i, step.else, at, "else");
         if (step.collect !== undefined || step.prompt !== undefined) {
@@ -342,6 +307,12 @@ 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`);
         });
@@ -372,6 +343,232 @@ 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.
+ */
+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 ${exports.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));
@@ -402,10 +599,10 @@ function mismatch(def, value) {
     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 { expected: describeDef(def), got: describe(value), fix: "Values are not coerced; write the right type." };
+        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 { expected: `one of ${allowed.map(list).join(", ")}`, got: list(items[off]), fix: "Use one of the listed values." };
+    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;
@@ -473,6 +670,8 @@ 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 }),
@@ -500,7 +699,7 @@ 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({