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

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/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.11",
+  "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);
     }
@@ -659,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") {
@@ -669,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];
@@ -700,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);
   }
 
@@ -773,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) {
@@ -824,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) }
@@ -993,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"] });
@@ -1005,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);
   }
 
@@ -1021,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) {
@@ -1037,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");
@@ -1060,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")
@@ -1071,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) ─────────────────
@@ -1120,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. */