@falai/agent 4.0.0-alpha.7 → 4.0.0-alpha.9

package/src/core/FlowSpec.ts

@@ -410,11 +410,8 @@ export function validateFlow<C = unknown, D = LooseData>(
         continue;
       }
       if (!matchesParam(def, value)) {
-        throw problem(
-          at,
-          `parameter "${param}" of action "${name}" must be ${describeDef(def)}, got ${describe(value)}`,
-          "Values are not coerced; write the right type.",
-        );
+        const { expected, got, fix } = mismatch(def, value);
+        throw problem(at, `parameter "${param}" of action "${name}" must be ${expected}, got ${got}`, fix);
       }
     }
     for (const param of Object.keys(given)) {
@@ -554,12 +551,33 @@ function matches(def: ScalarDef, value: unknown): boolean {
   return typeof value !== "boolean" && def.enum.includes(value);
 }
 
+/**
+ * What a rejected value should have been and what it was. A value of the right type that is
+ * not a listed one names the listed values: "must be a string, got string" would say nothing.
+ */
+function mismatch(def: ParamDef, value: unknown): { expected: string; got: string; fix: string } {
+  const scalar = def.type === "array" ? def.items : def;
+  const { enum: allowed, ...typeOnly } = scalar;
+  const items = def.type === "array" && Array.isArray(value) ? value : [value];
+  const off = allowed ? items.findIndex((item) => matches(typeOnly, item) && !matches(scalar, item)) : -1;
+  if (!allowed || off === -1) {
+    return { expected: describeDef(def), got: describe(value), fix: "Values are not coerced; write the right type." };
+  }
+  const list = (v: unknown) => JSON.stringify(v);
+  return { expected: `one of ${allowed.map(list).join(", ")}`, got: list(items[off]), fix: "Use one of the listed values." };
+}
+
 function describe(value: unknown): string {
   return Array.isArray(value) ? "list" : value === null ? "null" : typeof value;
 }
 
 function describeDef(def: ParamDef): string {
-  return def.type === "array" ? `a list of ${def.items.type}` : `a ${def.type}`;
+  return def.type === "array" ? `a list of ${def.items.type}s` : `${article(def.type)} ${def.type}`;
+}
+
+/** "an integer", "a string". A vowel test rather than one hard-coded type, so a new type reads right for free. */
+function article(type: string): string {
+  return /^[aeiou]/.test(type) ? "an" : "a";
 }
 
 // ── flowSpecSchema ──────────────────────────────────────────────────────

package/src/core/Runner.ts

@@ -508,8 +508,7 @@ export class Runner<C = unknown, D = unknown> {
     const floorRun = this.floorRun(turn);
     const floorFlow = floorRun && this.flows.get(floorRun.flowId);
     const eligible = this.eligibleMessageFlows(turn);
-    // Exactly one eligible message flow and no floor: it starts without scoring (S9).
-    const messageFlows = !floorRun && eligible.length === 1 ? [] : eligible;
+    const messageFlows = !floorRun && this.startsUnscored(turn, eligible) ? [] : eligible;
     const mentionFlows = this.mentionFlows()
       .filter(({ flow, trigger }) => trigger.mention.length > 0 && this.repeatAllows(turn, flow, trigger, turn.triggerKey))
       .map(({ flow }) => flow);
@@ -562,6 +561,14 @@ export class Runner<C = unknown, D = unknown> {
     return this.messageFlows(turn, (list) => list.length > 0);
   }
 
+  /**
+   * The lone eligible flow starts without a score only when a low score would have nowhere
+   * else to send the message: no catch-all passes and the idle speaker is silent (S9).
+   */
+  private startsUnscored(turn: Turn<C, D>, eligible: Flow<C, D>[]): boolean {
+    return eligible.length === 1 && this.options.idle === "silent" && this.messageFlows(turn, (list) => list.length === 0).length === 0;
+  }
+
   private messageFlows(turn: Turn<C, D>, accept: (list: string[]) => boolean): Flow<C, D>[] {
     const out: Flow<C, D>[] = [];
     for (const flow of this.flows.values()) {
@@ -605,7 +612,7 @@ export class Runner<C = unknown, D = unknown> {
         const current = scores[asker.flowId] ?? 0;
         const top = best(eligible.filter((f) => f.id !== asker.flowId));
         if (top && top.score >= current + ROUTE_STICKY && top.score >= ROUTE_MIN) route = top.flow;
-      } else if (eligible.length === 1) {
+      } else if (this.startsUnscored(turn, eligible)) {
         route = eligible[0];
       } else {
         const top = best(eligible);

package/src/core/Understand.ts

@@ -44,12 +44,9 @@ export class Understand<C = unknown, D = unknown> {
     const candidates = candidateFlows(req);
     const onlyRouting =
       req.mentionFlows.length === 0 && req.branches.length === 0 && Object.keys(req.fields).length === 0;
-    if (onlyRouting && candidates.length <= 1) {
-      // One eligible flow and nobody on the floor: it starts, no scoring.
-      // Otherwise there is nothing to compare or extract.
-      const only = candidates[0];
-      return only && !req.floor ? { ...empty(0), flows: { [only.id]: 100 } } : empty(0);
-    }
+    // Nothing to compare or extract: no candidates, or only the floor's own flow. A lone
+    // candidate with nobody on the floor is here because the runner wants it scored.
+    if (onlyRouting && candidates.length <= (req.floor ? 1 : 0)) return empty(0);
 
     const aliases = new Aliases();
     const jsonSchema = buildEnvelope(req, candidates, aliases);

package/src/types/agent.ts

@@ -87,7 +87,11 @@ export type TurnBase<C = unknown, D = unknown> = ContextField<C> & {
   sessionId: string;
   /** Absent on a first turn. A wake never creates a session. */
   session?: Session<D>;
-  /** Pass on every input kind, wakes included. */
+  /**
+   * The conversation BEFORE this input. Pass it on every input kind, wakes included.
+   * Leave out the message this turn carries: both calls quote it on their own, so a
+   * history that ends with it makes the model read it twice.
+   */
   history?: History;
   silenced?: Silenced;
   /** Host anchors this session belongs to, e.g. `{ lead: { key: 'lead:456', lastInboundAt } }`. */