@falai/agent 4.0.0-alpha.10 → 4.0.0-alpha.12

package/docs/reference/actions-events-conditions.md

@@ -220,7 +220,7 @@ An event turn never spends an understand call. It costs one speak call (plus too
 
 1. **Direction.** `'inbound'` sets `lastUserAt` to now and resolves reply waits: every run parked on a timer `wait` that has an `else` resumes with `code: 'replied'` and follows a matching `if` branch's `then`, else `else`. `'outbound'` sets `lastAssistantAt` to now, which re-arms `silence` triggers at the end of the turn.
 2. **Waiting runs.** Every run parked on `wait: { event: name }` for this name resumes with `code: 'event-arrived'` and follows `then`. The first one to resume takes the floor for this turn.
-3. **Triggers.** Every flow with `on: [{ event: name }]` goes through the start order: trigger `if`, `repeat` (default `'always'` for events), the hop cap, one live run per flow and anchor. With `after`, the run parks first (`code: 'awaiting-trigger'`, wake key `${runId}:start:${atMs}`) and enters its first step when the wake fires; `businessHours: true` snaps that time forward through the agent's `businessHours` function.
+3. **Triggers.** Every flow with `on: [{ event: name }]` goes through the start order: trigger `if`, `repeat` (default `'always'` for events), the hop cap, one live run per flow and anchor. With `after`, the run parks first (`code: 'awaiting-trigger'`, wake key `${runId}:start:${atMs}`) and enters its first step when the wake fires; `businessHours: true` snaps that time forward through the agent's `businessHours` function. With `businessHours: true` and no `after`, an event that arrives outside working hours parks the run the same way until the next working moment.
 
 `wait: { event, upTo }` in a step parks the run for at most `upTo` (default `'30d'`, from `src/core/Runner.ts`). If the event never comes, the line carries `code: 'no-event'` and the run follows `else`, or ends when there is none.
 

package/docs/reference/branches.md

@@ -34,7 +34,7 @@ type Branch<C = unknown, D = unknown> = { then: Next<D> } & (
 3. The run leaves the step with the outcome `code: 'branch'` (kind `prompt` or `collect`, status `ok`, `next` naming the target) and follows `then` in the same turn. Fields the understand call extracted from the same message are written first, so `then` may land on a step that is already satisfied.
 4. When no branch holds, the step continues as usual: pending fields are harvested and the step speaks again.
 
-A `when` branch costs the understand call; when it is the only thing to judge, that is one model call the turn would not otherwise spend. An `if` branch is judged on every message turn even when no understand call happens.
+A `when` branch costs the understand call; when it is the only thing to judge, that is one model call the turn would not otherwise spend. An `if` branch is judged on every message turn even when no understand call happens. A suspended run that returns to asking during the turn, because the asker ended or moved on without a word, has its `if` branches judged before its step speaks; its `when` branches were not in the understand call, so they wait for the next message.
 
 **On a wait step.** Only `if` branches are judged, and only when the customer writes before the time passes and the step has `else`. The first `if` branch that holds replaces `else` as the target (outcome `code: 'replied'`). A `when` branch on a wait step is never asked, because a reply to a wait step does not reach the understand call. When the wake fires, branches are not consulted: the run follows `then`, or `else` when the customer wrote after the wait was set.
 

package/docs/reference/flow.md

@@ -63,7 +63,7 @@ It enters `steps[0]` in the same turn unless the trigger has `after`. Keys and s
 
 **`onEnd`.**
 - `'end'`: the run ends with reason `'end'`.
-- `'stay'`: the run re-enters the last step (a new visit, so new keys) and stays asking. It speaks that step again on the next message. Meant for a last talk step that answers follow-up questions.
+- `'stay'`: the run goes back to the last talk step it took and stays there, asking. On a branched flow that is the step on its own path; when its log names none, the flow's last talk step. From then on that step answers every message, even when it has nothing left to collect, and each answer is a new visit, so a new key. The steps after it ran once, on the way to the end, and do not run again. If the run finishes on a message nothing has answered yet (no `say`, no `spoke: true`), the step answers it in that same turn. If another run is asking, the staying run waits `suspended` behind it and takes over when that run is done, answering the message that run moved on from without a word. When the customer's message belongs to this run (it was routed to this flow, or it resolved this run's `wait`), the run takes the conversation instead: the other asker is suspended, and this run answers unless its own `say` already did. Its `when` branches are judged on every message and still move the run. Its `if` branches are judged too, except one that leads to `'end'` or to a step the run has already been through: that path already ran and the fact is still true, so it would run again on every message. A field still pending there (a `when` branch took the run to the end before the customer gave it) is asked for on each answer, each with its own key, and `max-asks` is reported once, on the answer that reaches the limit. If the flow is edited off `'stay'` while a run stays, the new `onEnd` applies on that run's next message. A flow with no talk step ends, as with `'end'`.
 - `'reset'`: the run ends with reason `'reset'` and a fresh run of the same flow starts at `steps[0]`, data kept, one hop deeper. A flow that resets forever without asking anything stops at hop 5, with `code: 'hop-limit'`.
 
 **Instructions and tools while speaking.** The speak call sees the agent's instructions, then this flow's, then the step's, each already filtered by its `if`. Tools are the step's `tools`; without one, the flow's `tools`; without that, every agent tool.

package/docs/reference/session.md

@@ -38,6 +38,7 @@ interface Run {
   hop: number;
   startedAt: string;
   suspendedAt?: string;
+  staying?: true;
   waiting?: { kind: "timer" | "event"; key?: string; until?: string; setAt: string; event?: string };
   asked: Record<string, number>;
   visits: Record<string, number>;
@@ -86,6 +87,7 @@ From `src/types/session.ts`. Every date is ISO 8601 text, never a `Date`: the bl
 | `hop` | `number` | Chaining depth. `0` for a run a trigger started; `+1` per `{ flow }` move and per `onEnd: 'reset'`. A start at hop 5 is skipped: `code: 'hop-limit'` on `TurnResult.skipped`. |
 | `startedAt` | `string` | The clock's now when the run started. |
 | `suspendedAt` | `string?` | Set while `suspended`. The most recently suspended run is the one that resumes. |
+| `staying` | `true?` | Set once an `onEnd: 'stay'` run has finished its steps and sits on its last talk step, answering every message. Any other move clears it. |
 | `waiting` | object? | Set while `waiting`. See below. |
 | `asked` | `Record<string, number>` | Per field, how many times a talk step spoke with that field still pending. A field at the step's `maxAsks` (default 3, `src/utils/schema.ts`) leaves the pending set: `code: 'max-asks'`, with the field's slug in `detail`. |
 | `visits` | `Record<string, number>` | Per step, how many times this run entered it. Part of every message and action key, so a revisit mints new keys. |

package/docs/reference/step.md

@@ -153,9 +153,9 @@ The code forks. No model call.
 | Form | Meaning |
 |---|---|
 | `'passo'` | Jump to that step id. |
-| `'end'` | Finish the run here, exactly as running past the last step does — `onEnd` still decides: `'end'` ends it, `'stay'` re-enters the last step and keeps asking, `'reset'` starts a fresh run. `'end'` is reserved: no step may use it as an id. |
+| `'end'` | Finish the run here, exactly as running past the last step does — `onEnd` still decides: `'end'` ends it, `'stay'` goes back to the last talk step and answers every message from there, `'reset'` starts a fresh run. `'end'` is reserved: no step may use it as an id. |
 | `{ step: 'passo', clear: ['campo'] }` | Delete the listed fields from `session.data`, then jump. The way to ask something again. |
-| `{ flow: 'outro', input? }` | End this run (reason `'flow'`) and start `outro` in the same turn, one hop deeper. The child gets `input`, or this run's `input` when absent, and holds the floor. `flow` is a template. |
+| `{ flow: 'outro', input? }` | End this run (reason `'flow'`) and start `outro` in the same turn, one hop deeper. The child gets `input`, or this run's `input` when absent. It holds the floor when this run did, or when no run did: a `mention` flow that chains does not take the message from the run it was routed to. `flow` is a template. |
 
 Entering a step counts a visit; the visit is part of every key minted there, so a step visited twice sends twice. A `{ step }` jump to an id that no longer exists ends the run with `code: 'step-gone'`; a `{ flow }` to an unknown flow is skipped with `code: 'flow-gone'`.
 

package/docs/reference/trigger.md

@@ -85,7 +85,7 @@ A trigger whose phrases are *all* exclusions can never fire, so `validateFlow` r
 | `event` | `string` | required | The event's name in the agent's `events`. |
 | `after` | `Duration` | none | Park the run this long before its first step. |
 | `if` | `Pred<C, D>` | none | Judged when the event arrives, with the payload as `input`. |
-| `businessHours` | `boolean` | `false` | Snap the `after` wake forward. |
+| `businessHours` | `boolean` | `false` | Start only in working hours: snap the start (now, or now + `after`) forward with the agent's `businessHours`. |
 | `repeat` | `Repeat` | `'always'` | |
 
 The event's `payload` is the run's `input`.
@@ -116,7 +116,7 @@ Pass a real message `id` on every message turn. Only `id` is checked against the
 
 **Dedupe key.** `${flowId}:${anchor}:${nonce}`. The nonce is the trigger key when `repeat` is `'always'` and empty otherwise. It is written to `session.claims` when the run starts, given to actions as `ctx.dedupeKey`, and returned in `started[]`. The last 50 `'always'` claims per flow and anchor are kept; `'once'` and cooldown claims are never pruned. The host may pass claims from the customer's other sessions in `turn({ claims })`; they count the same.
 
-**Wake for `after`.** `${runId}:start:${atMs}`, where `atMs` is the fire time in milliseconds after `businessHours` snapping. The run is returned in `started[]` at once with the outcome `code: 'awaiting-trigger'`. At the wake it enters its first step. A second event for the same flow and anchor while it is parked replaces it: the parked run ends with reason `'replaced'`.
+**Wake for `after`.** `${runId}:start:${atMs}`, where `atMs` is the fire time in milliseconds after `businessHours` snapping. With `businessHours: true` and no `after`, the same wake parks a run whose event arrives outside working hours; inside them it starts at once. The run is returned in `started[]` at once with the outcome `code: 'awaiting-trigger'`. At the wake it enters its first step. A second event for the same flow and anchor while it is parked replaces it: the parked run ends with reason `'replaced'`.
 
 **Wake for silence.** `silence:${flowId}:${sessionId}:${lastAssistantAtMs}`. Armed at the end of every turn in which the assistant spoke and the customer has not written since, for every silence flow passing `if` and `repeat`; the entry's `replaces` names the previous silence wake. At fire time it is honoured only while `session.lastAssistantAt` still equals that timestamp and the customer has not written since (`code: 'silence-broken'` otherwise).
 

package/examples/05-branches.ts

@@ -54,7 +54,7 @@ const agent = f.agent({
           then: "dados",
         },
       ],
-      // After the last step the run stays on it, so follow-up questions land here.
+      // After the last step the run goes back to the last talk step it took, so follow-up questions land there.
       onEnd: "stay",
     }),
     f.flow({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@falai/agent",
   "packageManager": "bun@1.4.2",
-  "version": "4.0.0-alpha.10",
+  "version": "4.0.0-alpha.12",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/FlowSpec.ts

@@ -702,7 +702,7 @@ export function flowSpecSchema(registries: Registries): StructuredSchema {
     while: orNull({ ...condition, description: "The run ends when this stops holding" }),
     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")),
   });
 }

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

@@ -303,6 +303,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);
     }
@@ -425,9 +427,11 @@ export class Runner<C = unknown, D = unknown> {
     }
     session.runs.push(run);
     turn.started.push({ runId: run.id, flowId: flow.id, anchor, dedupeKey });
-    const after = opts.trigger && "event" in opts.trigger ? opts.trigger.after : undefined;
-    if (after) {
-      const at = this.snap(turn, new Date(turn.now.getTime() + parseDuration(after)), opts.trigger && "event" in opts.trigger ? opts.trigger.businessHours : undefined);
+    const eventTrigger = opts.trigger && "event" in opts.trigger ? opts.trigger : undefined;
+    const after = eventTrigger?.after;
+    const at = this.snap(turn, new Date(turn.now.getTime() + (after ? parseDuration(after) : 0)), eventTrigger?.businessHours);
+    // With no `after`, only a closed hour parks the start: inside working hours the snap returns now.
+    if (after || at.getTime() > turn.now.getTime()) {
       this.park(turn, run, { kind: "timer", key: `${run.id}:start:${at.getTime()}` }, at);
       this.outcome(turn, run, { kind: "wait", status: "waiting", code: "awaiting-trigger", until: at.toISOString() });
     }
@@ -657,6 +661,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") {
@@ -667,8 +674,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];
@@ -698,9 +712,18 @@ 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);
+    // 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);
+    }
     return this.speaker(turn);
   }
 
@@ -771,6 +794,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) {
@@ -822,7 +850,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) }
@@ -991,11 +1021,11 @@ export class Runner<C = unknown, D = unknown> {
     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"] });
@@ -1003,8 +1033,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);
   }
 
@@ -1019,15 +1051,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) {
@@ -1035,7 +1107,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");
@@ -1058,9 +1130,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")
@@ -1069,6 +1152,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) ─────────────────
@@ -1118,15 +1202,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

@@ -255,7 +255,7 @@ export interface Flow<C = unknown, D = unknown> {
   while?: Pred<C, D>;
   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. */