@falai/agent 4.0.0-alpha.1 → 4.0.0-alpha.10

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";
@@ -43,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);
@@ -245,8 +243,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 +264,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/index.ts

@@ -137,6 +137,7 @@ export type {
   ParamDef,
   ParamDefs,
   Participant,
+  PendingWakesInput,
   Pred,
   PredCtx,
   ProviderCapabilities,

package/src/providers/ProviderAdapter.ts

@@ -101,11 +101,16 @@ export interface RequestConfig {
   maxTokens?: number;
   stopSequences?: string[];
   /**
-   * How hard the model thinks, bound as this provider's default. Absent means
-   * the model's own dynamic thinking, which is what every shape does when the
-   * field is never sent — so `"none"` is the only way to say *don't*, and it
-   * matters most under a small `maxTokens`, where thinking tokens come out of
-   * the same budget as the answer and can consume all of it.
+   * How hard the model thinks, bound as this provider's default. What absent
+   * means is the shape's own business, not one rule: on Gemini it is the
+   * model's dynamic thinking; on the OpenAI and OpenRouter dialects nothing is
+   * sent and not thinking is the default anyway; on the Anthropic shape — so
+   * `AnthropicProvider` and `ZaiProvider` — `@providerkit/core` resolves an
+   * absent effort to `"none"`, and Z.ai is sent an explicit disabled marker
+   * because its endpoint reads silence as thinking ON. Set a level to ask for
+   * thinking where it is off; it matters most under a small `maxTokens`, where
+   * thinking tokens come out of the same budget as the answer and can consume
+   * all of it.
    */
   effort?: Effort;
 }

package/src/providers/ZaiProvider.ts

@@ -6,10 +6,12 @@
  * `@providerkit/core` (adapter + preset); this file is the constructor, the
  * family default for cheap high-volume work.
  *
- * Dialect notes (measured 2026-09-13, see the core preset for detail):
- * model ids are BARE (`glm-5.3-flash`, not `z-ai/glm-5.3-flash`), and
- * "no thinking" must be an explicit marker — silence means the model default,
- * which is thinking ON.
+ * Dialect notes (see the core preset for detail): model ids are BARE
+ * (`glm-5.3-flash`, not `z-ai/glm-5.3-flash`), and the endpoint reads an
+ * absent `thinking` field as thinking ON, so the preset says "no" out loud.
+ * That makes thinking OFF here by default (measured 2026-09-21: a call with no
+ * `config.effort` sends `thinking: { type: "disabled" }`); ask for it with
+ * `config: { effort: 'high' }`.
  */
 
 import { createZaiCodingProvider, type FallbackOptions, type Provider } from "@providerkit/core";

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 } }`. */
@@ -108,6 +112,13 @@ export type TurnKind =
 
 export type TurnInput<C = unknown, D = unknown> = TurnBase<C, D> & TurnKind;
 
+/** A saved session and the host inputs a turn on it would carry: what `pendingWakes` reads. */
+export type PendingWakesInput<C = unknown, D = unknown> = ContextField<C> & {
+  session: Session<D>;
+  anchors?: TurnBase<C, D>["anchors"];
+  claims?: TurnBase<C, D>["claims"];
+};
+
 // ── turn() result ───────────────────────────────────────────────────────
 
 export interface OutboundMessage {
@@ -123,7 +134,7 @@ export interface OutboundMessage {
   stepId?: string;
 }
 
-/** A wake to enqueue with `jobId = key`; at fire time call `turn({ wake: key })`. */
+/** A wake to enqueue, keyed by `key` (encode it as a queue job id: BullMQ refuses a `:`); at fire time call `turn({ wake: key })`. */
 export interface ScheduleEntry {
   key: string;
   at: Date;

package/src/types/index.ts

@@ -10,6 +10,7 @@ export type {
   EndReason,
   Idle,
   OutboundMessage,
+  PendingWakesInput,
   ScheduleEntry,
   Silenced,
   TurnBase,

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,14 @@
  * 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 the host answered with nothing is a different case: it 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?". Two things count as blank: an empty string, and
+ * a path that walks THROUGH a null — `context.lead` being `null` means there
+ * is no lead, so "the lead's name" is blank, not mistyped. A null at the end of
+ * a path is still unknown: a field that collected nothing keeps its braces.
  */
 
 export interface TemplateScope {
@@ -15,11 +23,38 @@ export interface TemplateScope {
 
 const PLACEHOLDER = /\{\{\s*([^}\s]+)\s*\}\}/g;
 
+/** The path ran into a `null` on its way down: the container the host named is absent. */
+const ABSENT = Symbol("absent");
+
 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 === ABSENT) {
+      emptied = true;
+      return "";
+    }
+    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. */
@@ -37,7 +72,8 @@ export function renderDeep<T>(value: T, scope: TemplateScope): T {
 function lookup(root: unknown, keys: string[]): unknown {
   let current = root;
   for (const key of keys) {
-    if (current === null || typeof current !== "object") return undefined;
+    if (current === null) return ABSENT;
+    if (typeof current !== "object") return undefined;
     current = (current as Record<string, unknown>)[key];
   }
   return current;