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

package/src/core/Runner.ts

@@ -8,7 +8,7 @@
  *   begin ─▶ understandRequest ─(Understand)─▶ decide ─▶ advance ─(Speak)─▶ settle ─▶ finish
  */
 
-import type { AgentOptions, EndReason, TurnInput, TurnResult } from "../types/agent.js";
+import type { AgentOptions, EndReason, PendingWakesInput, ScheduleEntry, TurnBase, TurnInput, TurnResult } from "../types/agent.js";
 import type { TokenUsage } from "../types/ai.js";
 import type { ActionResult, Branch, DoStep, Duration, Flow, IfStep, Next, Pred, PredCtx, Repeat, SayStep, Step, StepBase, TalkStep, Trigger, WaitEventStep, WaitStep } from "../types/flow.js";
 import type { History } from "../types/history.js";
@@ -49,7 +49,7 @@ export type What =
 
 /** The mutable per-turn state. `session` is a deep copy; the input is never touched. */
 export interface Turn<C = unknown, D = unknown> {
-  readonly input: TurnInput<C, D>;
+  readonly input: TurnBase<C, D>;
   readonly what: What;
   readonly kind: InputKind;
   /** Message id, wake key, event key or start key: the trigger key of runs started this turn. */
@@ -171,11 +171,26 @@ export class Runner<C = unknown, D = unknown> {
   // ── Load + Ingest ─────────────────────────────────────────────────────
 
   begin(input: TurnInput<C, D>): Turn<C, D> {
-    const now = (this.options.clock ?? (() => new Date()))();
+    const now = this.now();
+    const turn = this.open(input, describe(input, now.toISOString()), now);
+    if (turn.what.kind === "wake" && !input.session) {
+      this.ignore(turn, "no-session", turn.what.key);
+      return turn;
+    }
+    turn.ingesting = true;
+    this.ingest(turn);
+    turn.ingesting = false;
+    return turn;
+  }
+
+  private now(): Date {
+    return (this.options.clock ?? (() => new Date()))();
+  }
+
+  private open(input: TurnBase<C, D>, what: What, now: Date): Turn<C, D> {
     const nowIso = now.toISOString();
-    const what = describe(input, nowIso);
     const silenced = typeof input.silenced === "string" ? input.silenced : input.silenced?.reason;
-    const turn: Turn<C, D> = {
+    return {
       input,
       what,
       kind: what.kind,
@@ -204,14 +219,17 @@ export class Runner<C = unknown, D = unknown> {
       speakDone: false,
       queue: [],
     };
-    if (what.kind === "wake" && !input.session) {
-      this.ignore(turn, "no-session", what.key);
-      return turn;
-    }
-    turn.ingesting = true;
-    this.ingest(turn);
-    turn.ingesting = false;
-    return turn;
+  }
+
+  /** Every wake the session waits on: each parked run's own, then each silence flow's since the assistant last spoke. */
+  pendingWakes(input: PendingWakesInput<C, D>): ScheduleEntry[] {
+    // No input arrives, so nothing reads `what`: the inert wake shape only fills the field.
+    const turn = this.open({ ...input, sessionId: input.session.id }, { kind: "wake", key: "" }, this.now());
+    // `park` always sets both; the type leaves them optional, so a hand-built blob without them has no wake to give.
+    const parked = turn.session.runs.flatMap(({ status, waiting }) =>
+      status === "waiting" && waiting?.key && waiting.until ? [{ key: waiting.key, at: new Date(waiting.until) }] : [],
+    );
+    return [...parked, ...this.silenceWakes(turn)];
   }
 
   private ingest(turn: Turn<C, D>): void {
@@ -407,9 +425,11 @@ export class Runner<C = unknown, D = unknown> {
     }
     session.runs.push(run);
     turn.started.push({ runId: run.id, flowId: flow.id, anchor, dedupeKey });
-    const after = opts.trigger && "event" in opts.trigger ? opts.trigger.after : undefined;
-    if (after) {
-      const at = this.snap(turn, new Date(turn.now.getTime() + parseDuration(after)), opts.trigger && "event" in opts.trigger ? opts.trigger.businessHours : undefined);
+    const eventTrigger = opts.trigger && "event" in opts.trigger ? opts.trigger : undefined;
+    const after = eventTrigger?.after;
+    const at = this.snap(turn, new Date(turn.now.getTime() + (after ? parseDuration(after) : 0)), eventTrigger?.businessHours);
+    // With no `after`, only a closed hour parks the start: inside working hours the snap returns now.
+    if (after || at.getTime() > turn.now.getTime()) {
       this.park(turn, run, { kind: "timer", key: `${run.id}:start:${at.getTime()}` }, at);
       this.outcome(turn, run, { kind: "wait", status: "waiting", code: "awaiting-trigger", until: at.toISOString() });
     }
@@ -508,8 +528,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 +581,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 +632,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);
@@ -1139,14 +1166,21 @@ export class Runner<C = unknown, D = unknown> {
     return new Date(reset !== undefined && reset > ladder ? reset : ladder);
   }
 
-  /** The assistant spoke last: every silence flow passing `if` and `repeat` gets a wake. */
+  /** The assistant spoke this turn: its silence wakes replace the ones its last words set. */
   private armSilence(turn: Turn<C, D>): void {
+    const previous = turn.original?.lastAssistantAt;
+    if (turn.session.lastAssistantAt === previous) return;
+    turn.schedule.push(...this.silenceWakes(turn, previous));
+  }
+
+  /** The assistant spoke last: every silence flow passing `if` and `repeat` gets a wake. */
+  private silenceWakes(turn: Turn<C, D>, previous?: string): ScheduleEntry[] {
     const { session } = turn;
     const { lastAssistantAt, lastUserAt } = session;
-    if (!lastAssistantAt || lastAssistantAt === turn.original?.lastAssistantAt) return;
-    if (lastUserAt && Date.parse(lastUserAt) > Date.parse(lastAssistantAt)) return;
+    if (!lastAssistantAt) return [];
+    if (lastUserAt && Date.parse(lastUserAt) > Date.parse(lastAssistantAt)) return [];
     const ms = Date.parse(lastAssistantAt);
-    const previous = turn.original?.lastAssistantAt;
+    const wakes: ScheduleEntry[] = [];
     for (const flow of this.flows.values()) {
       const trigger = (flow.on ?? []).find((t): t is SilenceTrigger<C, D> => "silence" in t);
       if (!trigger) continue;
@@ -1154,12 +1188,13 @@ export class Runner<C = unknown, D = unknown> {
       if (trigger.if && !this.holds(trigger.if, turn, this.draftRun(turn, flow, "silence", key))) continue;
       if (!this.repeatAllows(turn, flow, trigger, key)) continue;
       const at = this.snap(turn, new Date(ms + parseDuration(trigger.silence)), trigger.businessHours);
-      turn.schedule.push({
+      wakes.push({
         key: `silence:${flow.id}:${session.id}:${ms}`,
         at,
         ...(previous ? { replaces: `silence:${flow.id}:${session.id}:${Date.parse(previous)}` } : {}),
       });
     }
+    return wakes;
   }
 
   // ── Return (design §4.8) ──────────────────────────────────────────────

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;