@falai/agent 4.0.0-alpha.2 → 4.0.0-alpha.4

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/Speak.ts

@@ -78,8 +78,17 @@ function deferralOf(error: unknown): Deferral {
   // A usage window that says when it reopens is worth exactly one wake, then.
   // Without that number, waiting is guessing, and the ladder guesses in minutes
   // at a limit measured in hours.
-  const retryable = RETRY_KINDS.has(kind) || (kind === "quota" && reset !== undefined);
-  return { code: DEFER_CODE[kind], retryable, ...(reset !== undefined ? { resetAtMs: reset } : {}) };
+  const inferred = RETRY_KINDS.has(kind) || (kind === "quota" && reset !== undefined);
+  // Unless the provider said so outright. `x-should-retry` is the one answer
+  // nobody has to infer, and core already puts it above its own transience
+  // test — a 503 that says don't costs five wakes and ten model calls here if
+  // this reads the kind instead.
+  const stated = error instanceof ProviderError ? error.shouldRetry : undefined;
+  return {
+    code: DEFER_CODE[kind],
+    retryable: stated ?? inferred,
+    ...(reset !== undefined ? { resetAtMs: reset } : {}),
+  };
 }
 /** Gemini rejects any other envelope property name. */
 const WIRE_NAME = /^[a-zA-Z0-9_-]+$/;

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 };
+}