@falai/agent 4.0.0-alpha.8 → 4.0.0

package/src/core/FlowSpec.ts

@@ -44,7 +44,7 @@ import type {
 import type { StructuredSchema } from "../types/schema.js";
 import { isDuration } from "../utils/duration.js";
 import { splitPhrases } from "../utils/phrases.js";
-import { toWireSchema } from "../utils/schema.js";
+import { extractMode, toWireSchema } from "../utils/schema.js";
 
 // ── The JSON form ───────────────────────────────────────────────────────
 
@@ -77,7 +77,7 @@ interface TalkSpecExtras {
 export type StepSpec = StepBase<LooseData> &
   (
     | ({ kind: "prompt"; prompt: Template; collect?: undefined } & TalkSpecExtras)
-    | ({ kind: "collect"; collect: string[]; prompt?: Template } & TalkSpecExtras)
+    | ({ kind: "collect"; collect: string[]; prompt?: Template; question?: Template } & TalkSpecExtras)
     | ({ kind: "say" } & SayStep)
     | ({ kind: "do" } & DoStep<LooseData>)
     | { kind: "wait"; wait: Duration; businessHours?: boolean; else?: Next<LooseData>; branches?: BranchSpec[] }
@@ -92,6 +92,7 @@ export interface FlowSpec {
   on?: TriggerSpec[];
   anchor?: string;
   while?: ConditionSpec<LooseData>;
+  collect?: string[];
   clearOnStart?: string[];
   steps: StepSpec[];
   onEnd?: "end" | "stay" | "reset";
@@ -99,8 +100,14 @@ export interface FlowSpec {
   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 }>;
+};
 
 // ── fromSpec / toSpec ───────────────────────────────────────────────────
 
@@ -112,9 +119,7 @@ export type Registries = Pick<AgentOptions, "fields" | "actions" | "events" | "c
  */
 export function fromSpec<C = unknown, D = LooseData>(spec: FlowSpec): Flow<C, D> {
   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: Flow<unknown, LooseData> = { ...rest, steps: steps.map(fromStepSpec) };
   return flow as Flow<C, D>;
@@ -136,6 +141,7 @@ export function toSpec<C, D extends LooseData>(flow: Flow<C, D>): FlowSpec {
     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,
@@ -189,11 +195,12 @@ function stepToSpec<C, D extends LooseData>(step: Step<C, D>, at: string): StepS
     instructions: step.instructions?.map((ins, i) => instructionToSpec(ins, `${at} instructions[${i}]`)),
   };
   if (step.collect !== undefined) {
-    return compact<StepSpec>({ ...base, kind: "collect", collect: step.collect, prompt: step.prompt, ...talk });
+    return compact<StepSpec>({ ...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<StepSpec>({ ...base, kind: "prompt", prompt: step.prompt, ...talk });
 }
 
@@ -248,6 +255,7 @@ interface LooseStep {
   onFail?: Next<LooseData>;
   prompt?: Template;
   collect?: string[];
+  question?: Template;
   ask?: Partial<Record<string, string>>;
   branches?: LooseBranch[];
   instructions?: LooseInstruction[];
@@ -262,21 +270,23 @@ interface LooseFlow {
   id: string;
   on?: LooseTrigger[];
   while?: LoosePred;
+  collect?: string[];
   clearOnStart?: string[];
   steps: LooseStep[];
   instructions?: LooseInstruction[];
   tools?: string[];
 }
 
-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"] as const;
 
-/** The six keys one of which makes a step do something. */
-const STEP_DOES = ["prompt", "collect", "say", "do", "wait", "if"] as const;
+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
@@ -289,7 +299,8 @@ export function validateFlow<C = unknown, D = LooseData>(
 ): { warnings: string[] } {
   // Nulls mean "not set" in a spec; a typed flow has none, so one pass serves both forms.
   const flow: LooseFlow = 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: string[] = [];
 
@@ -297,9 +308,6 @@ export function validateFlow<C = unknown, D = LooseData>(
     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<string, number>();
   flow.steps.forEach((step, i) => {
@@ -318,11 +326,7 @@ export function validateFlow<C = unknown, D = LooseData>(
     throw problem(flowAt, "has triggers but no steps", "Add at least one step or remove `on`.");
   }
 
-  const slug = (name: string, at: string, where: string): void => {
-    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: string, at: string, where: string): void => checkSlug(fields, name, at, where);
 
   const toolNames = (names: string[] | undefined, at: string): void => {
     for (const name of names ?? []) {
@@ -330,38 +334,7 @@ export function validateFlow<C = unknown, D = LooseData>(
     }
   };
 
-  const pred = (value: LoosePred | undefined, at: string, where: string): void => {
-    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: LoosePred | undefined, at: string, where: string): void => checkPred(value, at, where, registries);
 
   const duration = (value: string | undefined, at: string, where: string): void => {
     if (value !== undefined && !isDuration(value)) {
@@ -379,7 +352,16 @@ export function validateFlow<C = unknown, D = LooseData>(
       }
       return to;
     }
-    if ("flow" in next) return undefined;
+    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".');
@@ -410,11 +392,8 @@ export function validateFlow<C = unknown, D = LooseData>(
         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)) {
@@ -424,7 +403,18 @@ export function validateFlow<C = unknown, D = LooseData>(
     }
   };
 
+  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`));
@@ -469,25 +459,20 @@ export function validateFlow<C = unknown, D = LooseData>(
 
   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) {
       for (const field of step.collect ?? []) 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.",
@@ -499,6 +484,14 @@ export function validateFlow<C = unknown, D = LooseData>(
       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`);
     });
@@ -535,6 +528,228 @@ export function validateFlow<C = unknown, D = LooseData>(
   return { warnings };
 }
 
+function checkSlug(fields: FieldDefs, name: string, at: string, where: string): void {
+  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: LoosePred | undefined, at: string, where: string, registries: Registries): void {
+  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: unknown): void {
+  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: Record<string, unknown>, at: string): void {
+  // 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: Record<string, unknown>): StepKind[] {
+  const kinds: StepKind[] = [];
+  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: unknown, at: string): void {
+  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: unknown, where: string, at: string): void {
+  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: unknown, where: string, at: string): void {
+  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: Record<string, unknown>, keys: string[], at: string): void {
+  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: unknown, where: string, allowed: string[], at: string): void {
+  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: unknown, where: string, at: string, item: "string" | "object"): unknown[] {
+  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: unknown): value is Record<string, unknown> {
+  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: unknown): string {
+  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: string[]): string {
+  return items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}
+
 function matchesParam(def: ParamDef, value: unknown): boolean {
   if (def.type === "array") return Array.isArray(value) && value.every((item) => matches(def.items, item));
   return matches(def, value);
@@ -554,6 +769,22 @@ function matches(def: ScalarDef, value: unknown): boolean {
   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: ParamDef, value: unknown): { listed: boolean; expected: string; got: string; fix: string } {
+  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: unknown) => 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: unknown): string {
   return Array.isArray(value) ? "list" : value === null ? "null" : typeof value;
 }
@@ -633,6 +864,8 @@ export function flowSpecSchema(registries: Registries): StructuredSchema {
   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 }),
@@ -642,6 +875,7 @@ export function flowSpecSchema(registries: Registries): StructuredSchema {
         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,
       }),
@@ -661,7 +895,7 @@ export function flowSpecSchema(registries: Registries): StructuredSchema {
       wait: { ...duration, description: "Park this long; then = time passed, else = the lead replied" },
       businessHours: orNull(BOOLEAN),
       else: nextOrNull,
-      branches,
+      branches: waitBranches,
     }),
     eventNames.length
       ? closed({
@@ -687,9 +921,10 @@ export function flowSpecSchema(registries: Registries): StructuredSchema {
     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")),
   });
 }
@@ -738,6 +973,10 @@ function orNull(schema: StructuredSchema): StructuredSchema {
 
 // ── Shared helpers ──────────────────────────────────────────────────────
 
+function questionWithoutCollect(at: string): FlowConfigurationError {
+  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: string, what: string, fix: string): FlowConfigurationError {
   return new FlowConfigurationError(`[FlowConfigurationError] ${at}: ${what}. ${fix}`);
 }

package/src/core/Migrate.ts

@@ -112,7 +112,7 @@ function checkRun(raw: unknown, index: number, bad: Bad): Run {
 
   const status = text("status");
   if (!RUN_STATUS.has(status)) throw bad(`${at}.status is "${status}"`);
-  const { stepId, hop, outcomes, input, waiting, suspendedAt } = raw;
+  const { stepId, hop, outcomes, input, waiting, suspendedAt, staying } = raw;
   if (stepId !== null && typeof stepId !== "string") throw bad(`${at}.stepId is ${describe(stepId)}, expected text or null`);
   if (!isWhole(hop)) throw bad(`${at}.hop is ${describe(hop)}, expected a whole number`);
   if (!Array.isArray(outcomes)) throw bad(`${at}.outcomes is ${describe(outcomes)}, expected a list`);
@@ -139,6 +139,7 @@ function checkRun(raw: unknown, index: number, bad: Bad): Run {
   if (input !== undefined) run.input = input;
   if (waiting !== undefined) run.waiting = waiting as Run["waiting"];
   if (typeof suspendedAt === "string") run.suspendedAt = suspendedAt;
+  if (staying === true) run.staying = true;
   return run;
 }
 

package/src/core/Prompt.ts

@@ -160,3 +160,43 @@ export function pendingSection(
     ...lines,
   ].join("\n");
 }
+
+/** Gemini rejects any other character in a property name. */
+const SAFE_KEY = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Envelope property names for ids the schema cannot carry. A safe id keeps
+ * its own name; anything else (run ids carry `#`, `:` and `/`) or a name the
+ * envelope already uses (`reserved`) gets a short alias, mapped back when the
+ * reply is parsed.
+ */
+export class Aliases {
+  private readonly byReal = new Map<string, string>();
+  private readonly byAlias = new Map<string, string>();
+  private n = 0;
+
+  constructor(reserved: readonly string[] = []) {
+    for (const name of reserved) this.byAlias.set(name, name);
+  }
+
+  of(real: string, prefix = "k"): string {
+    const seen = this.byReal.get(real);
+    if (seen) return seen;
+    const alias = SAFE_KEY.test(real) && !this.byAlias.has(real) ? real : this.fresh(prefix);
+    this.byAlias.set(alias, real);
+    this.byReal.set(real, alias);
+    return alias;
+  }
+
+  /** Unknown aliases come back as they are; Runner drops keys it does not know. */
+  real(alias: string): string {
+    return this.byAlias.get(alias) ?? alias;
+  }
+
+  private fresh(prefix: string): string {
+    let alias: string;
+    do alias = `${prefix}${++this.n}`;
+    while (this.byAlias.has(alias));
+    return alias;
+  }
+}