@falai/agent 4.0.0-alpha.11 → 4.0.0-alpha.13

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";
@@ -136,6 +137,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 +191,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 +251,7 @@ interface LooseStep {
   onFail?: Next<LooseData>;
   prompt?: Template;
   collect?: string[];
+  question?: Template;
   ask?: Partial<Record<string, string>>;
   branches?: LooseBranch[];
   instructions?: LooseInstruction[];
@@ -262,6 +266,7 @@ interface LooseFlow {
   id: string;
   on?: LooseTrigger[];
   while?: LoosePred;
+  collect?: string[];
   clearOnStart?: string[];
   steps: LooseStep[];
   instructions?: LooseInstruction[];
@@ -421,7 +426,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`));
@@ -483,8 +499,14 @@ export function validateFlow<C = unknown, D = LooseData>(
     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.",
@@ -655,6 +677,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,
       }),
@@ -700,9 +723,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")),
   });
 }
@@ -751,6 +775,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/Runner.ts

@@ -137,6 +137,13 @@ function talkKind(step: { collect?: readonly string[] }): StepOutcomeKind {
   return step.collect?.length ? "collect" : "prompt";
 }
 
+/** Everything a flow collects: its own `collect`, then each talk step's, once each. */
+function flowFields<C, D>(flow: Flow<C, D>): string[] {
+  const fields = new Set<string>(flow.collect);
+  for (const step of flow.steps) if (isTalk(step)) for (const field of step.collect ?? []) fields.add(field);
+  return [...fields];
+}
+
 function kindOf<C, D>(step: Step<C, D> | undefined): StepOutcomeKind {
   if (!step) return "if";
   if (isTalk(step)) return talkKind(step);
@@ -303,6 +310,8 @@ export class Runner<C = unknown, D = unknown> {
       const branch = step.branches?.find((b) => "if" in b && this.holds(b.if, turn, run));
       const target = branch ? branch.then : step.else;
       this.outcome(turn, run, { kind: "wait", status: "ok", code: "replied", next: nextLabel(target) });
+      // The reply is this run's while it moves, so a stay it reaches answers it.
+      if (!turn.floorFromIngest) turn.floorRunId = run.id;
       this.follow(turn, run, flow, step, target);
       this.takeFloor(turn, run);
     }
@@ -541,16 +550,25 @@ export class Runner<C = unknown, D = unknown> {
     }
     const fields: UnderstandRequest<C, D>["fields"] = {};
     const data: Record<string, unknown> = turn.session.data;
+    const harvestable = (field: string): boolean => {
+      const def = this.options.fields[field];
+      return def !== undefined && !isKnown(data[field]) && extractMode(def) === "anywhere";
+    };
     for (const flow of [...(floorFlow ? [floorFlow] : []), ...eligible]) {
-      for (const step of flow.steps) {
-        if (!isTalk(step)) continue;
-        for (const field of step.collect ?? []) {
-          const def = this.options.fields[field];
-          if (def && !isKnown(data[field]) && extractMode(def) === "anywhere") fields[field] = def;
-        }
-      }
+      for (const field of flowFields(flow).filter(harvestable)) fields[field] = this.options.fields[field];
+    }
+    const judging = messageFlows.length > 0 || mentionFlows.length > 0 || branches.length > 0 || Object.keys(fields).length > 0;
+    // With nobody on the floor the catch-all may take this message, and an opening message often says the most. The
+    // fields its first step asks ride on that step's speak call, so alone they spend no call; a fixed question has no speak call.
+    // ponytail: "first step" is steps[0]; a catch-all that opens with a say or an if pays the call for that step's fields too.
+    const fallback = floorRun ? undefined : this.messageFlows(turn, (list) => list.length === 0)[0];
+    if (fallback) {
+      const first = fallback.steps[0];
+      const free = new Set<string>(first && isTalk(first) && first.question === undefined ? first.collect : []);
+      const own = flowFields(fallback).filter(harvestable);
+      if (judging || own.some((field) => !free.has(field))) for (const field of own) fields[field] = this.options.fields[field];
     }
-    if (!messageFlows.length && !mentionFlows.length && !branches.length && !Object.keys(fields).length) return null;
+    if (!judging && !Object.keys(fields).length) return null;
     return {
       text: turn.what.text,
       history: this.historyOf(turn),
@@ -659,6 +677,9 @@ export class Runner<C = unknown, D = unknown> {
       }
     }
 
+    // Unless routing or Ingest moved it, the message is the asker's: written down, so a chain beside it cannot take it.
+    if (asker && !route && !turn.floorFromIngest) turn.floorRunId = asker.id;
+
     for (const [field, raw] of Object.entries(understanding?.fields ?? {})) this.writeField(turn, field, raw);
 
     if (asker && turn.session.runs.includes(asker) && asker.status === "asking") {
@@ -669,8 +690,15 @@ export class Runner<C = unknown, D = unknown> {
   }
 
   private fireBranch(turn: Turn<C, D>, run: Run, flow: Flow<C, D>, step: TalkOf<C, D>, understanding: Understanding | null): void {
+    // Staying, a run does not take an `if` branch back onto a path it has already run: the fact it tests is still true,
+    // so it would re-run that path on every message. A `when` branch is judged on each new message and always counts.
+    // ponytail: "already run" is the target's visit count, so an `if` restart (`{ step, clear }` to a visited step) never fires while staying; write it as a `when`.
+    const ran = (then: Next<D>): boolean =>
+      typeof then === "string" ? then === "end" || (run.visits[then] ?? 0) > 0 : "step" in then && (run.visits[then.step] ?? 0) > 0;
     const hit = (branch: Branch<C, D>, index: number): boolean =>
-      "if" in branch ? this.holds(branch.if, turn, run) : understanding?.branches[`${run.id}/${step.id}/${index}`] === true;
+      "if" in branch
+        ? !(run.staying && ran(branch.then)) && this.holds(branch.if, turn, run)
+        : understanding?.branches[`${run.id}/${step.id}/${index}`] === true;
     const index = (step.branches ?? []).findIndex(hit);
     if (index < 0) return;
     const branch = (step.branches ?? [])[index];
@@ -700,10 +728,43 @@ export class Runner<C = unknown, D = unknown> {
 
   async advance(turn: Turn<C, D>): Promise<TalkRequest<C, D> | IdleRequest<C, D> | null> {
     if (turn.ignored) return null;
-    this.resumeSuspended(turn);
+    this.resume(turn);
     turn.queue = [...turn.session.runs];
     await this.drain(turn);
-    return this.speaker(turn);
+    // An asker that moved on without a word hands the message to the run it suspended, and that one to the next.
+    // Each pass takes a run off the suspended stack, so the stack's size bounds the loop.
+    for (let left = turn.session.runs.length; left > 0; left--) {
+      if (turn.what.kind !== "message" || turn.silenced !== undefined || turn.talk || turn.spokeBy.size > 0) break;
+      const resumed = this.resume(turn);
+      if (!resumed) break;
+      turn.queue.push(resumed);
+      await this.drain(turn);
+    }
+    const speaker = this.speaker(turn);
+    if (speaker && !("idle" in speaker) && this.askFixed(turn, speaker)) {
+      turn.talk = undefined;
+      return null;
+    }
+    return speaker;
+  }
+
+  /**
+   * Send the step's fixed question when this is its first ask: every field it collects still unknown, none asked yet,
+   * and the run not staying (a staying run answers the lead). The question counts as one ask of each field. False when
+   * the AI should phrase the ask instead.
+   */
+  private askFixed(turn: Turn<C, D>, { run, step, pending }: TalkRequest<C, D>): boolean {
+    const { question, collect = [] } = step;
+    if (question === undefined || run.staying) return false;
+    if (pending.length !== collect.length || pending.some((field) => (run.asked[field] ?? 0) > 0)) return false;
+    const key = this.stepKey(run, step);
+    turn.messages.push({ text: render(question, this.scope(turn, run)), kind: "verbatim", afterMs: turn.afterMs, key, runId: run.id, stepId: step.id });
+    turn.afterMs = 0;
+    turn.spokeBy.add(run.id);
+    turn.spoke = true;
+    for (const field of pending) run.asked[field] = (run.asked[field] ?? 0) + 1;
+    this.outcome(turn, run, { kind: "collect", status: "ok", key, code: "asked-fixed", stepId: step.id });
+    return true;
   }
 
   /**
@@ -773,6 +834,11 @@ export class Runner<C = unknown, D = unknown> {
       return;
     }
     if (!this.premiseHolds(turn, run, flow)) return;
+    // The flow was edited off 'stay' after this run finished its steps: its new `onEnd` decides now.
+    if (run.staying && flow.onEnd !== "stay") {
+      this.finishFlow(turn, run, flow);
+      return;
+    }
     const resuming = run.status === "asking";
     run.status = "running";
     if (run.stepId === null) {
@@ -824,7 +890,9 @@ export class Runner<C = unknown, D = unknown> {
       let pending: string[] = [];
       if (step.collect?.length) {
         pending = pendingFields(step, data, run.asked);
-        if (!pending.length) {
+        // A `stay` run answers even with nothing left to collect: answering is what it stays for. It only runs on a message
+        // (asking runs sit out wakes and events), and on a silenced one the check below keeps it asking.
+        if (!pending.length && !run.staying) {
           this.reportMaxAsks(turn, run, step);
           this.outcome(turn, run, resuming
             ? { kind, status: "ok", key, next: nextLabel(step.then) }
@@ -845,7 +913,9 @@ export class Runner<C = unknown, D = unknown> {
         }
       }
       run.status = "asking";
+      // Reached after Speak (settle's drain), a talk step waits for the next message; a fixed question costs no call, so it goes out now, as a say would.
       if (!turn.speakDone) turn.talk = { run, flow, step, pending };
+      else this.askFixed(turn, { run, flow, step, pending });
       return;
     }
 
@@ -986,18 +1056,22 @@ export class Runner<C = unknown, D = unknown> {
     }
     if ("step" in target) {
       const data: Record<string, unknown> = turn.session.data;
-      for (const field of target.clear ?? []) delete data[field];
+      // Forgetting a field means asking for it from scratch: its ask count goes too, so a fixed question goes out again.
+      for (const field of target.clear ?? []) {
+        delete data[field];
+        delete run.asked[field];
+      }
       this.jump(turn, run, flow, target.step);
       return;
     }
     const childId = render(target.flow, this.scope(turn, run));
     const key = this.stepKey(run, step);
     this.endRun(turn, run, "flow");
-    this.chain(turn, childId, key, target.input ?? run.input, run.hop + 1);
+    this.chain(turn, run, childId, key, target.input ?? run.input, run.hop + 1);
   }
 
-  /** Start a child flow that holds the floor and moves in this same phase. */
-  private chain(turn: Turn<C, D>, flowId: string, key: string, input: unknown, hop: number, keepData = false): void {
+  /** Start a child flow that moves in this same phase. It inherits the floor when its parent held it, or when nobody did. */
+  private chain(turn: Turn<C, D>, parent: Run, flowId: string, key: string, input: unknown, hop: number, keepData = false): void {
     const child = this.flows.get(flowId);
     if (!child) {
       turn.skipped.push({ flowId, anchor: turn.session.id, triggerKey: key, code: "flow-gone", message: OUTCOME_MESSAGES["flow-gone"] });
@@ -1005,8 +1079,10 @@ export class Runner<C = unknown, D = unknown> {
     }
     const run = this.startRun(turn, child, "flow", key, { payload: input, hop, keepData });
     if (!run) return;
-    turn.floorRunId = run.id;
-    if (turn.ingesting) turn.floorFromIngest = true;
+    if (turn.floorRunId === undefined || turn.floorRunId === parent.id) {
+      turn.floorRunId = run.id;
+      if (turn.ingesting) turn.floorFromIngest = true;
+    }
     turn.queue.push(run);
   }
 
@@ -1021,15 +1097,55 @@ export class Runner<C = unknown, D = unknown> {
     run.visits[stepId] = (run.visits[stepId] ?? 0) + 1;
     run.status = "running";
     delete run.waiting;
+    delete run.staying;
+  }
+
+  /** `onEnd: 'stay'`: the run sits on its last talk step and answers every message from there, each answer a new visit and so a new key. */
+  private stayAt(run: Run, step: Step<C, D>): void {
+    this.enter(run, step.id);
+    run.staying = true;
+    run.status = "asking";
+  }
+
+  /**
+   * Where `stay` answers from: the talk step this run last took, so a branched flow stays on its own path. The flow's last talk step when the log names none.
+   * ponytail: read back from `run.outcomes`, which keeps 50 lines; a tail of 50+ lines after the talk step (a long polling loop) loses it and the run
+   * stays on the flow's last talk step. Upgrade: record the talk step on the run when it talks.
+   */
+  private stayStep(run: Run, flow: Flow<C, D>): TalkOf<C, D> | undefined {
+    for (let i = run.outcomes.length - 1; i >= 0; i--) {
+      const { kind, stepId } = run.outcomes[i];
+      const step = kind === "prompt" || kind === "collect" ? this.stepOf(flow, stepId ?? null) : undefined;
+      if (step && isTalk(step)) return step;
+    }
+    return [...flow.steps].reverse().find(isTalk);
   }
 
   private finishFlow(turn: Turn<C, D>, run: Run, flow: Flow<C, D>): void {
     const onEnd = flow.onEnd ?? "end";
     const last = flow.steps[flow.steps.length - 1];
-    if (onEnd === "stay" && last) {
-      // "repete o último passo": the run stays live at its last step, re-entered so the repetition mints a new key, and runs it on the next message.
-      this.enter(run, last.id);
-      run.status = "asking";
+    const stay = onEnd === "stay" ? this.stayStep(run, flow) : undefined;
+    if (stay) {
+      // The steps after it ran once, on the way here; staying, it only answers.
+      this.stayAt(run, stay);
+      // One asker at a time. A run the lead's message went to holds the conversation and suspends the other asker;
+      // any other run waits behind that asker and resumes when it is done.
+      const others = turn.session.runs.filter((r) => r !== run && r.status === "asking");
+      if (others.length && !(turn.what.kind === "message" && turn.floorRunId === run.id)) {
+        run.status = "suspended";
+        run.suspendedAt = turn.nowIso;
+        return;
+      }
+      for (const other of others) {
+        other.status = "suspended";
+        other.suspendedAt = turn.nowIso;
+        if (turn.talk?.run === other) turn.talk = undefined;
+      }
+      // A message nothing has answered yet gets its answer now. Reached in Ingest, the run stays asking: Decide judges its
+      // branches as the asker's, and it answers when it moves.
+      if (!turn.ingesting && turn.what.kind === "message" && turn.silenced === undefined && !turn.speakDone && turn.spokeBy.size === 0) {
+        run.status = "running";
+      }
       return;
     }
     if (onEnd === "reset" && last) {
@@ -1037,7 +1153,7 @@ export class Runner<C = unknown, D = unknown> {
       // It is a chain into itself, so it costs a hop: a code-only flow that resets forever stops at the hop cap instead of spinning.
       const key = this.stepKey(run, last);
       this.endRun(turn, run, "reset");
-      this.chain(turn, flow.id, key, run.input, run.hop + 1, true);
+      this.chain(turn, run, flow.id, key, run.input, run.hop + 1, true);
       return;
     }
     this.endRun(turn, run, "end");
@@ -1060,9 +1176,20 @@ export class Runner<C = unknown, D = unknown> {
     turn.schedule.push({ key: waiting.key, at });
   }
 
+  /** `resumeSuspended`, and on a message the resumed run's `if` branches are judged before it speaks, as the asker's are in Decide. */
+  private resume(turn: Turn<C, D>): Run | undefined {
+    const run = this.resumeSuspended(turn);
+    if (run && turn.what.kind === "message") {
+      const flow = this.flows.get(run.flowId);
+      const step = flow && this.stepOf(flow, run.stepId);
+      if (flow && step && isTalk(step)) this.fireBranch(turn, run, flow, step, null);
+    }
+    return run;
+  }
+
   /** When nobody asks, the most recently suspended run returns to asking. */
-  private resumeSuspended(turn: Turn<C, D>): void {
-    if (this.asker(turn)) return;
+  private resumeSuspended(turn: Turn<C, D>): Run | undefined {
+    if (this.asker(turn)) return undefined;
     const suspendedAt = (r: Run): string => r.suspendedAt ?? r.startedAt;
     const next = turn.session.runs
       .filter((r) => r.status === "suspended")
@@ -1071,6 +1198,7 @@ export class Runner<C = unknown, D = unknown> {
       next.status = "asking";
       delete next.suspendedAt;
     }
+    return next;
   }
 
   // ── Settle: the one applier after Speak (design §4.7) ─────────────────
@@ -1120,15 +1248,22 @@ export class Runner<C = unknown, D = unknown> {
     Object.assign(turn.session.data, spoken.data);
     this.outcome(turn, run, { kind: talkKind(step), status: "ok", key, llmCalls: spoken.llmCalls, stepId: step.id });
     if (!turn.session.runs.includes(run)) return;
-    if (step.collect?.length) {
-      const pending = pendingFields(step, turn.session.data, run.asked);
-      if (pending.length) {
-        for (const field of pending) run.asked[field] = (run.asked[field] ?? 0) + 1;
-        run.status = "asking";
-        return;
+    const pending = step.collect?.length ? pendingFields(step, turn.session.data, run.asked) : [];
+    for (const field of pending) run.asked[field] = (run.asked[field] ?? 0) + 1;
+    if (run.staying) {
+      // Each answer is a new visit, so a new key, even while a field is still pending; that field's max-asks is reported once, when it gets there.
+      const maxAsks = step.maxAsks ?? DEFAULT_MAX_ASKS;
+      for (const field of pending) {
+        if (run.asked[field] === maxAsks) this.outcome(turn, run, { kind: "collect", status: "skipped", key, code: "max-asks", detail: field });
       }
-      this.reportMaxAsks(turn, run, step);
+      this.stayAt(run, step);
+      return;
+    }
+    if (pending.length) {
+      run.status = "asking";
+      return;
     }
+    this.reportMaxAsks(turn, run, step);
     run.status = "running";
     this.follow(turn, run, flow, step, step.then);
     if (turn.session.runs.includes(run) && run.status === "running") turn.queue.push(run);

package/src/core/Speak.ts

@@ -96,6 +96,8 @@ const WIRE_NAME = /^[a-zA-Z0-9_-]+$/;
 const GUIDELINE_HEADING = "## Guideline for your reply (adapt to the conversation)";
 const DEFAULT_GUIDELINE =
   "Collect what is still missing below, in the flow of the conversation, one or two things per message.";
+/** A step with no prompt and nothing left to collect: the step an `onEnd: 'stay'` run answers from. */
+const ANSWER_GUIDELINE = "Answer the customer's message, in the flow of the conversation.";
 const TOOLS_SECTION =
   "## Tools\nCall the tools provided when you need to look something up or act before answering. Once you have what you need, answer the customer.";
 const FINAL_SECTION =
@@ -330,7 +332,7 @@ function buildPrompt<C, D>(
       ? [guideline(talk.idle.prompt)]
       : [
           `## Flow\n${talk.flow.name}${talk.flow.description ? `: ${talk.flow.description}` : ""}`,
-          guideline(talk.step.prompt ?? DEFAULT_GUIDELINE),
+          guideline(talk.step.prompt ?? (talk.pending.length ? DEFAULT_GUIDELINE : ANSWER_GUIDELINE)),
           pendingSection(talk.pending, options.fields, talk.step.ask ?? {}, scope),
           // `Partial<D>` is a mapped type; the guard is how it reaches an index-signature parameter without a cast.
           factsSection(options.fields, isRecord(req.data) ? req.data : {}),

package/src/types/flow.ts

@@ -45,6 +45,8 @@ export interface ScalarDef<T extends ScalarType = ScalarType> {
 
 /** One collectable field, authored once on the agent. */
 export interface FieldDef<T extends ScalarType = ScalarType> extends ScalarDef<T> {
+  /** The name a person reads, in an editor or next to a collected value. The model never sees it. */
+  label?: string;
   /** How the AI should ask for this field when a step collects it. */
   ask?: string;
   /**
@@ -185,6 +187,12 @@ export type TalkStep<C = unknown, D = unknown> = (
 ) & {
   /** Per-flow wording for a field; the field's own `ask` is the default. */
   ask?: Partial<Record<keyof D & string, string>>;
+  /**
+   * A fixed first question, sent word for word with no model call when the step
+   * first asks: every field it collects is still unknown and none was asked yet.
+   * Any later ask is the AI's own wording. Needs `collect`.
+   */
+  question?: Template;
   /** Times a field may be asked before it is skipped. Default 3. */
   maxAsks?: number;
   branches?: Branch<C, D>[];
@@ -253,9 +261,15 @@ export interface Flow<C = unknown, D = unknown> {
   anchor?: string;
   /** Re-checked whenever the run moves. Default: the trigger's `if`. */
   while?: Pred<C, D>;
+  /**
+   * The data this flow needs, as agent field slugs. Its talk steps' `collect`
+   * says which of it to ask, and in what order; a field no step asks is still
+   * noted whenever the lead gives it while the flow holds the conversation.
+   */
+  collect?: (keyof D & string)[];
   clearOnStart?: (keyof D & string)[];
   steps: Step<C, D>[];
-  /** What the run does after its last step. Default `'end'`. */
+  /** What the run does after its last step. Default `'end'`. `'stay'`: the last talk step the run took answers every later message. */
   onEnd?: "end" | "stay" | "reset";
   instructions?: Instruction<C, D>[];
   tools?: string[];

package/src/types/session.ts

@@ -28,6 +28,8 @@ export interface Run {
   startedAt: string;
   /** Set while `suspended`; the most recently suspended run resumes first. */
   suspendedAt?: string;
+  /** Set once an `onEnd: 'stay'` run has finished its steps: it sits on its last talk step and answers every message from there. Any other move clears it. */
+  staying?: true;
   waiting?: {
     kind: "timer" | "event";
     /** The wake key; only a `wake` equal to it is honoured. */
@@ -75,6 +77,7 @@ export type StepOutcomeCode =
   | "silenced"
   // A step
   | "already-known"
+  | "asked-fixed"
   | "another-reply"
   | "already-sent"
   | "branch"

package/src/utils/outcomes.ts

@@ -28,6 +28,7 @@ export const OUTCOME_MESSAGES = {
   silenced: "the host cannot speak right now",
 
   "already-known": "every field this step collects is known",
+  "asked-fixed": "the step's fixed question went out word for word",
   "another-reply": "another run already answered this turn",
   "already-sent": "this message was already sent once",
   branch: "a branch of this step fired",

package/src/utils/schema.ts

@@ -76,7 +76,7 @@ export interface WireOptions {
 
 /**
  * The JSON schema a provider sees: an allow-list of JSON-schema keys, with
- * `ask`, `extract` and `optional` stripped. Closed (`additionalProperties:
+ * `label`, `ask`, `extract` and `optional` stripped. Closed (`additionalProperties:
  * false`); every property required unless a parameter says `optional`.
  */
 export function toWireSchema(defs: FieldDefs | ParamDefs, options: WireOptions = {}): StructuredSchema {
@@ -102,8 +102,8 @@ function wireProperty(def: FieldDef | ParamDef, nullable: boolean): StructuredSc
 
 /**
  * Merge field rows authored per flow into the agent's one field set. Two
- * rows for one slug must agree on type and enum; the first non-empty `ask`
- * and `description` win.
+ * rows for one slug must agree on type and enum; the first non-empty `label`,
+ * `ask` and `description` win.
  */
 export function buildSchema(groups: Array<{ id: string; fields: FieldDefs }>): FieldDefs {
   const merged: FieldDefs = {};
@@ -131,6 +131,7 @@ export function buildSchema(groups: Array<{ id: string; fields: FieldDefs }>): F
       merged[slug] = {
         ...seen,
         enum: seen.enum ?? def.enum,
+        label: seen.label ?? def.label,
         ask: seen.ask ?? def.ask,
         description: seen.description ?? def.description,
         extract: seen.extract ?? def.extract,