@falai/agent 4.0.0-alpha.6 → 4.0.0-alpha.8

package/src/core/FlowSpec.ts

@@ -251,6 +251,7 @@ interface LooseStep {
   ask?: Partial<Record<string, string>>;
   branches?: LooseBranch[];
   instructions?: LooseInstruction[];
+  say?: Template;
   do?: string;
   with?: Record<string, unknown>;
   wait?: Duration | { event: string; upTo?: Duration };
@@ -271,6 +272,12 @@ const BUILT_IN_CONDITIONS = ["equals", "known", "silenced"];
 
 const DURATION_HINT = 'Write a number and a unit: "30s", "5m", "24h" or "3d".';
 
+/** The four keys one of which makes an `on[]` entry a trigger. */
+const TRIGGER_KINDS = ["message", "mention", "silence", "event"] as const;
+
+/** The six keys one of which makes a step do something. */
+const STEP_DOES = ["prompt", "collect", "say", "do", "wait", "if"] as const;
+
 /**
  * Check a flow, typed or as a spec, against the agent's registries. Throws
  * `FlowConfigurationError` on the first problem that would break at runtime;
@@ -424,6 +431,18 @@ export function validateFlow<C = unknown, D = LooseData>(
 
   flow.on?.forEach((trigger, i) => {
     const at = `${flowAt}, trigger #${i + 1}`;
+    // A trigger that names no kind can never fire, and nothing downstream says
+    // so: the Runner simply never finds it eligible and the flow looks broken
+    // for some other reason. `{ kind: 'message', when: [...] }` — the v3 shape —
+    // lands here, and so does a typo in the one key that matters.
+    if (!TRIGGER_KINDS.some((key) => trigger[key] !== undefined)) {
+      throw problem(
+        at,
+        "names no trigger kind",
+        `A trigger is one of ${TRIGGER_KINDS.map((key) => `\`${key}\``).join(", ")}. ` +
+          "A flow the host starts itself has no `on` at all.",
+      );
+    }
     if (trigger.event !== undefined && !own(events, trigger.event)) {
       throw problem(at, `unknown event "${trigger.event}"`, "Register it in events or fix the name.");
     }
@@ -450,6 +469,17 @@ export function validateFlow<C = unknown, D = LooseData>(
 
   flow.steps.forEach((step, i) => {
     const at = `${flowAt}, step "${step.id}"`;
+    // Same reasoning as the trigger above: a step that does none of the five
+    // things is a step the run walks straight past, silently. `kind` alone is
+    // not enough — the spec form drops it and keeps the body, so what counts
+    // is whether the body says what to do.
+    if (!STEP_DOES.some((key) => step[key] !== undefined)) {
+      throw problem(
+        at,
+        "does nothing",
+        "A step talks (`prompt` / `collect`), says (`say`), acts (`do`), waits (`wait`) or forks (`if`).",
+      );
+    }
     const thenTo = edge(i, step.then, at, "then");
     edge(i, step.else, at, "else");
 
@@ -529,7 +559,12 @@ function describe(value: unknown): string {
 }
 
 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 } }`. */