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

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);
@@ -543,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),
@@ -724,7 +740,31 @@ export class Runner<C = unknown, D = unknown> {
       turn.queue.push(resumed);
       await this.drain(turn);
     }
-    return this.speaker(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;
   }
 
   /**
@@ -873,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;
     }
 
@@ -1014,7 +1056,11 @@ 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;
     }

package/src/providers/ProviderAdapter.ts

@@ -290,6 +290,8 @@ export abstract class ProviderAdapter implements AiProvider {
   public abstract readonly capabilities: ProviderCapabilities;
 
   protected readonly provider: Provider;
+  /** `provider` without the fallback chain: the one model this adapter was built for. */
+  private readonly primary: Provider;
   protected readonly primaryModel: string;
   protected readonly backupModels: string[];
   protected readonly retryConfig: RetryConfig;
@@ -304,6 +306,7 @@ export abstract class ProviderAdapter implements AiProvider {
     this.primaryModel = init.model;
     this.backupModels = init.backupModels ?? [];
     this.retryConfig = resolveRetryConfig(init.retryConfig);
+    this.primary = init.provider;
 
     if (init.fallbacks && init.fallbacks.length > 0) {
       const coreProviders: Provider[] = [
@@ -337,9 +340,14 @@ export abstract class ProviderAdapter implements AiProvider {
    * boot when it is `null` — that model cannot serve this framework's turns).
    * Log `calls`: `0/3 and 3/3` is what makes the next model swap's regression
    * obvious. Costs `samples × 2` short calls, and errors propagate.
+   *
+   * It asks the primary alone, never the fallback chain. The answer configures
+   * this adapter's model; a call the chain handed to a fallback would score
+   * another model as this one. Each fallback is an adapter of its own: probe it
+   * the same way.
    */
   async probeJsonWithTools(opts?: ProbeOptions): Promise<JsonWithToolsProbe> {
-    return probeJsonWithTools(this.provider, {
+    return probeJsonWithTools(this.primary, {
       model: this.primaryModel,
       ...(opts ?? {}),
     });

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,6 +261,12 @@ 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'`. `'stay'`: the last talk step the run took answers every later message. */

package/src/types/session.ts

@@ -77,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,