@falai/agent 4.0.0-alpha.3 → 4.0.0-alpha.5

package/src/core/FlowSpec.ts

@@ -43,6 +43,7 @@ import type {
 } from "../types/flow.js";
 import type { StructuredSchema } from "../types/schema.js";
 import { isDuration } from "../utils/duration.js";
+import { splitPhrases } from "../utils/phrases.js";
 import { toWireSchema } from "../utils/schema.js";
 
 // ── The JSON form ───────────────────────────────────────────────────────
@@ -233,6 +234,8 @@ interface LooseInstruction {
 }
 interface LooseTrigger {
   repeat?: Repeat;
+  message?: string[];
+  mention?: string[];
   event?: string;
   silence?: Duration;
   after?: Duration;
@@ -428,6 +431,21 @@ export function validateFlow<C = unknown, D = LooseData>(
     duration(trigger.after, at, "after");
     if (typeof trigger.repeat === "object") duration(trigger.repeat.cooldown, at, "repeat.cooldown");
     pred(trigger.if, at, "if");
+    // Phrases opening with `!` rule the trigger out; a list of nothing but
+    // those can never fire, so the flow is dead and nothing would say so.
+    // `message: []` is the deliberate catch-all and stays legal.
+    for (const key of ["message", "mention"] as const) {
+      const phrases: string[] | undefined = trigger[key];
+      if (!phrases?.length) continue;
+      if (splitPhrases(phrases).counts.length > 0) continue;
+      throw problem(
+        at,
+        `every ${key} phrase starts with "!", so nothing can ever match it`,
+        `A "!" phrase rules the trigger out. Add at least one plain phrase saying when it should fire${
+          key === "message" ? ", or use an empty list for a catch-all" : ""
+        }.`,
+      );
+    }
   });
 
   flow.steps.forEach((step, i) => {

package/src/core/Prompt.ts

@@ -9,6 +9,7 @@
 
 import type { AgentOptions } from "../types/agent.js";
 import type { FieldDef, Instruction } from "../types/flow.js";
+import { splitPhrases } from "../utils/phrases.js";
 import { isKnown } from "../utils/schema.js";
 import { render, type TemplateScope } from "../utils/template.js";
 
@@ -106,7 +107,12 @@ export function instructionsSection<C, D>(groups: InstructionGroup<C, D>[], scop
       const text = render(item.prompt, scope).trim();
       if (!text) continue;
       const when = item.when === undefined ? [] : Array.isArray(item.when) ? item.when : [item.when];
-      const condition = when.length ? ` (apply only when: ${when.join(" OR ")})` : "";
+      const { counts, excludes } = splitPhrases(when);
+      const clauses = [
+        ...(counts.length ? [`apply only when: ${counts.join(" OR ")}`] : []),
+        ...(excludes.length ? [`never when: ${excludes.join(" OR ")}`] : []),
+      ];
+      const condition = clauses.length ? ` (${clauses.join("; ")})` : "";
       lines.push(`- [${item.kind ?? "should"}] ${group.caption} ${text}${condition}`);
     }
   }

package/src/core/Understand.ts

@@ -23,6 +23,7 @@ import type { FieldDef, FieldDefs, Flow, ParamDef, ParamDefs } from "../types/fl
 import type { StructuredSchema } from "../types/schema.js";
 import { extractEmbeddedJSONObject, isRecord } from "../utils/json.js";
 import { logger } from "../utils/logger.js";
+import { splitPhrases } from "../utils/phrases.js";
 import { coerceField, isKnown, pendingFields, toWireSchema } from "../utils/schema.js";
 import { render, type TemplateScope } from "../utils/template.js";
 import { readUsage } from "../utils/usage.js";
@@ -245,8 +246,9 @@ function flowsSection<C, D>(candidates: Flow<C, D>[], aliases: Aliases, t: (text
   ];
   candidates.forEach((flow, i) => {
     lines.push(`${i + 1}. ${aliases.of(flow.id, "f")} — ${flow.name}${flow.description ? `: ${t(flow.description)}` : ""}`);
-    const phrases = triggerPhrases(flow, "message");
-    if (phrases.length) lines.push(`   The customer: ${phrases.map(t).join("; ")}`);
+    const { counts, excludes } = splitPhrases(triggerPhrases(flow, "message"));
+    if (counts.length) lines.push(`   The customer: ${counts.map(t).join("; ")}`);
+    if (excludes.length) lines.push(`   Score 0 when: ${excludes.map(t).join("; ")}`);
   });
   lines.push(
     "",
@@ -265,12 +267,14 @@ function mentionsSection<C, D>(flows: Flow<C, D>[], aliases: Aliases, t: (text:
   const lines = [
     "## Things the customer may mention",
     "For each item, answer true when the customer's message clearly brings it up, false otherwise. " +
-      "Be conservative: true needs clear, explicit evidence in the message. The phrases under an item are alternatives; one match is enough.",
+      "Be conservative: true needs clear, explicit evidence in the message. The phrases under an item are alternatives; one match is enough. " +
+      "A 'Does not count when' line overrides a match: if one of those fits, answer false.",
   ];
   for (const flow of flows) {
     lines.push(`- ${aliases.of(flow.id, "f")} — ${flow.name}${flow.description ? `: ${t(flow.description)}` : ""}`);
-    const phrases = triggerPhrases(flow, "mention");
-    if (phrases.length) lines.push(`  Counts when: ${phrases.map(t).join("; ")}`);
+    const { counts, excludes } = splitPhrases(triggerPhrases(flow, "mention"));
+    if (counts.length) lines.push(`  Counts when: ${counts.map(t).join("; ")}`);
+    if (excludes.length) lines.push(`  Does not count when: ${excludes.map(t).join("; ")}`);
     const defs = extractDefs(flow);
     if (defs) {
       lines.push("  When true, also extract:");

package/src/utils/phrases.ts

@@ -0,0 +1,40 @@
+/**
+ * Splitting an AI-judged phrase list into what counts and what rules it out.
+ *
+ * A trigger's phrases are alternatives: one match is enough. That makes the
+ * list useless for saying "but not this" — and "but not this" is what keeps a
+ * classifier honest. A customer answering "pode sim" to an offer of a meeting
+ * is agreeing to the meeting, not asking for a human, and without a way to say
+ * so every cheerful yes reads as a handoff request.
+ *
+ * So a phrase that opens with `!` is an exclusion: it does not make the trigger
+ * fire, it stops it. Exclusions win over matches, and the model is told both
+ * lists separately.
+ */
+
+export interface Phrases {
+  /** Any one of these makes it true. */
+  counts: string[];
+  /** Any one of these makes it false, whatever matched. */
+  excludes: string[];
+}
+
+/**
+ * Split a phrase list on the leading `!`. Blank entries and a bare `"!"` are
+ * dropped: they would render as an empty bullet and mean nothing to the model.
+ */
+export function splitPhrases(phrases: readonly string[]): Phrases {
+  const counts: string[] = [];
+  const excludes: string[] = [];
+  for (const phrase of phrases) {
+    const trimmed = phrase.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith("!")) {
+      const body = trimmed.slice(1).trim();
+      if (body) excludes.push(body);
+      continue;
+    }
+    counts.push(trimmed);
+  }
+  return { counts, excludes };
+}

package/src/utils/template.ts

@@ -5,6 +5,11 @@
  * per-turn context) and `input` (the run's trigger payload). A path that
  * resolves to nothing keeps its placeholder, so a typo stays visible instead
  * of vanishing into an empty string.
+ *
+ * A path that resolves to an EMPTY string is a different case: the host knows
+ * the field and knows it is blank. Then the placeholder goes and `tidy` closes
+ * the gap it left, so "Ola {{context.lead.name}}, tudo bem?" sends
+ * "Ola, tudo bem?" and never "Ola , tudo bem?".
  */
 
 export interface TemplateScope {
@@ -16,10 +21,30 @@ export interface TemplateScope {
 const PLACEHOLDER = /\{\{\s*([^}\s]+)\s*\}\}/g;
 
 export function render(template: string, scope: TemplateScope): string {
-  return template.replace(PLACEHOLDER, (match, path: string) => {
+  let emptied = false;
+  const out = template.replace(PLACEHOLDER, (match, path: string) => {
     const value = lookup(scope, path.split("."));
-    return value === undefined || value === null ? match : stringify(value);
+    if (value === undefined || value === null) return match;
+    const text = stringify(value);
+    if (text === "") emptied = true;
+    return text;
   });
+  return emptied ? tidy(out) : out;
+}
+
+/**
+ * Close the hole an empty value leaves: a doubled space, a space before
+ * punctuation, a space at the end of a line.
+ *
+ * Deliberately narrow. It only runs on a string where something substituted to
+ * "", and it only collapses a run of spaces that follows a visible character,
+ * so indentation in a markdown list survives.
+ */
+function tidy(text: string): string {
+  return text
+    .replace(/(?<=\S)[ \t]{2,}/g, " ")
+    .replace(/ +([,.;:!?\u2026])/g, "$1")
+    .replace(/[ \t]+$/gm, "");
 }
 
 /** `render` over every string inside a value, recursively. Non-strings pass through. */