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

package/src/core/Speak.ts

@@ -32,6 +32,7 @@ import { render, type TemplateScope } from "../utils/template.js";
 import { addUsage, readUsage } from "../utils/usage.js";
 import type { Deferral, SpeakOutcome, SpeakRequest, SpeakStreamChunk } from "./contracts.js";
 import {
+  Aliases,
   describeField,
   factsSection,
   instructionsSection,
@@ -78,21 +79,33 @@ 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_-]+$/;
 
 const GUIDELINE_HEADING = "## Guideline for your reply (adapt to the conversation)";
 const DEFAULT_GUIDELINE =
   "Collect what is still missing below, in the flow of the conversation, one or two things per message.";
+/** A step with no prompt and nothing left to collect: the step an `onEnd: 'stay'` run answers from. */
+const ANSWER_GUIDELINE = "Answer the customer's message, in the flow of the conversation.";
 const TOOLS_SECTION =
   "## Tools\nCall the tools provided when you need to look something up or act before answering. Once you have what you need, answer the customer.";
 const FINAL_SECTION =
   "## Wrap up\nAnswer the customer now, using the tool results in the conversation. Do not call any tools.";
 const SPEAK_FIRST =
   "## Situation\nThere is no new message from the customer. You speak first: open naturally, do not answer a question nobody asked.";
+/** The retry wake after a provider failure, when the customer's last message is still unanswered. */
+const ANSWER_PENDING =
+  "## Situation\nThe customer's last message, in the conversation above, has no answer yet. Answer it now.";
 
 interface ToolCall {
   toolName: string;
@@ -154,7 +167,6 @@ export class Speak<C = unknown, D = unknown> {
     let history: History = req.history;
     const fields: Record<string, unknown> = {};
     const data: Record<string, unknown> = {};
-    const toolCalls: ToolCall[] = [];
     let llmCalls = 0;
     let usage: TokenUsage | undefined;
     let message = "";
@@ -209,14 +221,13 @@ export class Speak<C = unknown, D = unknown> {
       }
       history = [...history, ...executed.items];
       Object.assign(data, executed.data);
-      toolCalls.push(...read.toolCalls);
     }
 
     if (!message.trim()) {
       logger.warn(`[Speak] the model returned no message after ${llmCalls} call(s); deferring.`);
       return { deferred: UNAVAILABLE, llmCalls, ...(usage ? { usage } : {}) };
     }
-    return { spoken: { message, fields, data, toolCalls, llmCalls, ...(usage ? { usage } : {}) } };
+    return { spoken: { message, fields, data, llmCalls, ...(usage ? { usage } : {}) } };
   }
 
   /** One provider call. Streaming yields clean message deltas; both paths return the same shape. */
@@ -320,8 +331,8 @@ function buildPrompt<C, D>(
     "idle" in talk
       ? [guideline(talk.idle.prompt)]
       : [
-          `## Flow\n${talk.flow.name}${talk.flow.description ? `: ${talk.flow.description}` : ""}`,
-          guideline(talk.step.prompt ?? DEFAULT_GUIDELINE),
+          `## Flow\n${talk.flow.name}${talk.flow.description ? `: ${render(talk.flow.description, scope)}` : ""}`,
+          guideline(talk.step.prompt ?? (talk.pending.length ? DEFAULT_GUIDELINE : ANSWER_GUIDELINE)),
           pendingSection(talk.pending, options.fields, talk.step.ask ?? {}, scope),
           // `Partial<D>` is a mapped type; the guard is how it reaches an index-signature parameter without a cast.
           factsSection(options.fields, isRecord(req.data) ? req.data : {}),
@@ -333,17 +344,42 @@ function buildPrompt<C, D>(
       inline,
       ...body,
       instructionsSection([{ caption: "[Always]", items: req.instructions }], scope),
-      inputSection(req.input),
+      inputSection(req.input, req.history),
+      saidSection(req.said),
       formatSection(envelope, options.fields),
     ),
   };
 }
 
-/** The customer's latest text, quoted. Without one, on anything but a message, the assistant opens the exchange. */
-function inputSection(input: SpeakRequest["input"]): string | null {
+/**
+ * The customer's latest text, quoted. Without one, on anything but a message,
+ * the assistant opens the exchange. The one exception is the retry of a step
+ * the provider failed, while the history still ends with the customer's
+ * message: that message gets its answer. A history that merely ends with a
+ * customer message is not enough, because a host may skip a message on
+ * purpose (an away message, a filtered first contact) and a follow-up must
+ * not answer it.
+ */
+function inputSection(input: SpeakRequest["input"], history: History): string | null {
   const text = input.text?.trim();
   if (text) return `## Customer's latest message\n"${text}"`;
-  return input.kind === "message" ? null : SPEAK_FIRST;
+  if (input.kind === "message") return null;
+  return input.retry && history.at(-1)?.role === "user" ? ANSWER_PENDING : SPEAK_FIRST;
+}
+
+/**
+ * What this turn already sent before the reply. It sits after the customer's message because that is
+ * when it went out; `history` stops before the turn, so it is the only place the model sees it.
+ */
+function saidSection(said: SpeakRequest["said"]): string | null {
+  const lines = said.map(({ text, media }) =>
+    `- ${[text.trim() && `"${text.trim()}"`, media && `[media: ${media.slug}]`].filter(Boolean).join(" ")}`);
+  if (!lines.length) return null;
+  return [
+    "## Already sent",
+    "You already sent these messages this turn, in this order, and your reply goes out right after them. Do not repeat what they say.",
+    ...lines,
+  ].join("\n");
 }
 
 /** The envelope restated in words, for providers that follow the schema by prompt only. */
@@ -374,16 +410,14 @@ function formatSection(envelope: Envelope, fields: FieldDefs): string {
 // ── Envelope ────────────────────────────────────────────────────────────
 
 function buildEnvelope(fields: FieldDefs, pending: string[]): Envelope {
+  const aliases = new Aliases(["message"]);
   const wire = new Map<string, string>();
   const defs: FieldDefs = { message: { type: "string" } };
-  pending.forEach((slug, i) => {
-    // ponytail: a slug spelled like the reply key or with characters Gemini rejects
-    // rides under an alias; the table maps it back. Ceiling: a real slug named
-    // `field_N` could collide with an alias. Upgrade: bump the alias until free.
-    const name = WIRE_NAME.test(slug) && slug !== "message" ? slug : `field_${i}`;
+  for (const slug of pending) {
+    const name = aliases.of(slug, "field_");
     wire.set(slug, name);
     defs[name] = fields[slug] ?? { type: "string" };
-  });
+  }
   return { schema: toWireSchema(defs, { nullable: true }), wire };
 }
 

package/src/core/Understand.ts

@@ -6,9 +6,10 @@
  * hands back raw values keyed by their real ids. It never writes session
  * data: Runner validates, coerces and applies.
  *
- * Two shortcuts cost zero calls: a single eligible message flow with nothing
- * else to judge starts outright, and a turn with nothing AI-conditioned
- * returns an empty Understanding.
+ * Zero calls when there is nothing to judge: no candidate flow, or only the
+ * floor's own, and no mention, branch or field. A lone eligible message flow
+ * starts unscored only when no catch-all passes and `idle` is `'silent'`;
+ * Runner decides that and sends no request. Otherwise this call scores it.
  *
  * The envelope is built for two kinds of provider at once. Gemini enforces
  * the schema, so every section is a closed object with every property
@@ -23,19 +24,17 @@ 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";
 import type { UnderstandRequest, Understanding } from "./contracts.js";
-import { describeField, factsSection, joinSections, stablePrefix } from "./Prompt.js";
+import { Aliases, describeField, factsSection, joinSections, stablePrefix } from "./Prompt.js";
 
 export const UNDERSTAND_SCHEMA_NAME = "understand";
 
 const SECTIONS = ["flows", "mentions", "extract", "branches", "fields"] as const;
 
-/** Gemini rejects any other character in a property name. */
-const SAFE_KEY = /^[a-zA-Z0-9_-]+$/;
-
 export class Understand<C = unknown, D = unknown> {
   constructor(private readonly options: AgentOptions<C, D>) {}
 
@@ -43,12 +42,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);
@@ -113,38 +109,6 @@ function candidateFlows<C, D>(req: UnderstandRequest<C, D>): Flow<C, D>[] {
   return [...seen.values()];
 }
 
-/**
- * Envelope property names for ids the schema cannot carry. A safe id keeps
- * its own name; anything else (run ids carry `#`, `:` and `/`) gets a short
- * alias, mapped back when the reply is parsed.
- */
-class Aliases {
-  private readonly byReal = new Map<string, string>();
-  private readonly byAlias = new Map<string, string>();
-  private n = 0;
-
-  of(real: string, prefix = "k"): string {
-    const seen = this.byReal.get(real);
-    if (seen) return seen;
-    const alias = SAFE_KEY.test(real) && !this.byAlias.has(real) ? real : this.fresh(prefix);
-    this.byAlias.set(alias, real);
-    this.byReal.set(real, alias);
-    return alias;
-  }
-
-  /** Unknown aliases come back as they are; Runner drops keys it does not know. */
-  real(alias: string): string {
-    return this.byAlias.get(alias) ?? alias;
-  }
-
-  private fresh(prefix: string): string {
-    let alias: string;
-    do alias = `${prefix}${++this.n}`;
-    while (this.byAlias.has(alias));
-    return alias;
-  }
-}
-
 function branchKey(branch: { runId: string; stepId: string; index: number }): string {
   return `${branch.runId}/${branch.stepId}/${branch.index}`;
 }
@@ -245,8 +209,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 +230,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/core/contracts.ts

@@ -8,7 +8,7 @@
  */
 
 import type { TokenUsage } from "../types/ai.js";
-import type { Idle } from "../types/agent.js";
+import type { Idle, OutboundMessage } from "../types/agent.js";
 import type { FieldDef, Flow, Instruction, StepBase, TalkStep } from "../types/flow.js";
 import type { History } from "../types/history.js";
 import type { Run, StepOutcomeCode } from "../types/session.js";
@@ -70,11 +70,19 @@ export interface IdleRequest<C = unknown, D = unknown> {
 
 export interface SpeakRequest<C = unknown, D = unknown> {
   talk: TalkRequest<C, D> | IdleRequest<C, D>;
-  /** What started this turn. A wake has no text: the assistant speaks first. */
-  input: { kind: InputKind; text?: string };
+  /**
+   * What started this turn. A wake has no text: the assistant speaks first, unless `retry` says this
+   * talk step failed at the provider and is running again, with the customer's message still unanswered.
+   */
+  input: { kind: InputKind; text?: string; retry?: boolean };
   context: C;
   data: Partial<D>;
   history: History;
+  /**
+   * What this turn already sent before the reply, in order: a `say`, a fixed question. `history` ends
+   * before the turn, so without these the model cannot see them and says the same thing again.
+   */
+  said: OutboundMessage[];
   now: Date;
   /** Already filtered by their `if`; `when` stays for the prompt. */
   instructions: Instruction<C, D>[];
@@ -87,7 +95,6 @@ export interface Spoken {
   fields: Record<string, unknown>;
   /** Data patches returned by tools, merged in call order. */
   data: Record<string, unknown>;
-  toolCalls: Array<{ toolName: string; arguments: Record<string, unknown> }>;
   llmCalls: number;
   usage?: TokenUsage;
 }

package/src/index.ts

@@ -111,7 +111,6 @@ export type {
   ConditionSpec,
   DoStep,
   Duration,
-  EmittedEvent,
   EndReason,
   Event,
   EventDef,
@@ -137,6 +136,7 @@ export type {
   ParamDef,
   ParamDefs,
   Participant,
+  PendingWakesInput,
   Pred,
   PredCtx,
   ProviderCapabilities,

package/src/persistence/OpenSearchStore.ts

@@ -39,6 +39,7 @@ export interface OpenSearchClient {
 }
 
 export interface OpenSearchStoreOptions {
+  client: OpenSearchClient;
   /** Index name. Default `agent_sessions`. */
   indices?: { sessions?: string };
   /** Create the index with its mappings on `initialize()`. Default true. */
@@ -58,8 +59,8 @@ export class OpenSearchStore<D = unknown> implements Store<D> {
   private readonly autoCreateIndices: boolean;
   private readonly refresh: Refresh;
 
-  constructor(client: OpenSearchClient, options: OpenSearchStoreOptions = {}) {
-    this.client = client;
+  constructor(options: OpenSearchStoreOptions) {
+    this.client = options.client;
     this.index = options.indices?.sessions ?? "agent_sessions";
     this.autoCreateIndices = options.autoCreateIndices ?? true;
     this.refresh = options.refresh ?? false;

package/src/persistence/RedisStore.ts

@@ -23,7 +23,7 @@ export interface RedisStoreOptions {
   redis: RedisClient;
   /** Prefix of every key. Default `agent:`. */
   keyPrefix?: string;
-  /** Seconds a session lives after its last save; `0` keeps it forever. Default 7 days. */
+  /** Seconds a session lives after its last save; `0` keeps it forever. Default 7 days. Keep it above your longest wait: an expired session loses its parked runs and claims. */
   sessionTTL?: number;
 }
 

package/src/providers/AnthropicProvider.ts

@@ -30,11 +30,8 @@ export interface AnthropicProviderOptions {
   /** Idle-stream deadline and retry budget */
   retryConfig?: { timeout?: number; retries?: number };
   /**
-   * Replacement `fetch`, for tests that script the wire.
-   *
-   * v3 note: this replaces the injected SDK client. There is no SDK now, so a
-   * test drives the same bytes the provider really receives rather than an
-   * SDK's idea of them.
+   * Replacement `fetch`, for tests that script the wire. There is no vendor
+   * SDK, so a test drives the same bytes the provider really receives.
    */
   fetchImpl?: typeof fetch;
 }
@@ -50,10 +47,8 @@ export class AnthropicProvider extends ProviderAdapter {
   };
 
   constructor(options: AnthropicProviderOptions) {
-    if (!options.apiKey) throw new Error("Anthropic API key is required");
-    if (!options.model) {
-      throw new Error("Model is required. Example: 'claude-sonnet-5' or 'claude-opus-5'");
-    }
+    if (!options.apiKey) throw new Error(`[AnthropicProvider] apiKey is empty: the provider cannot authenticate. Pass { apiKey: process.env.ANTHROPIC_API_KEY } and check the variable is set.`);
+    if (!options.model) throw new Error(`[AnthropicProvider] model is empty: there is no default. Pass one, e.g. { model: "claude-sonnet-5" }.`);
 
     super({
       provider: createAnthropicProvider({

package/src/providers/DeepSeekProvider.ts

@@ -51,10 +51,8 @@ export class DeepSeekProvider extends OpenAICompatibleProvider {
   };
 
   constructor(options: DeepSeekProviderOptions) {
-    if (!options.apiKey) throw new Error("DeepSeek API key is required");
-    if (!options.model) {
-      throw new Error("Model is required. Example: 'deepseek-chat' or 'deepseek-reasoner'");
-    }
+    if (!options.apiKey) throw new Error(`[DeepSeekProvider] apiKey is empty: the provider cannot authenticate. Pass { apiKey: process.env.DEEPSEEK_API_KEY } and check the variable is set.`);
+    if (!options.model) throw new Error(`[DeepSeekProvider] model is empty: there is no default. Pass one, e.g. { model: "deepseek-chat" }.`);
 
     super({
       id: "deepseek",

package/src/providers/FallbackAiProvider.ts

@@ -38,7 +38,7 @@ export class FallbackAiProvider implements AiProvider {
 
   constructor(options: FallbackAiProviderOptions) {
     if (!options.providers || options.providers.length === 0) {
-      throw new Error("FallbackAiProvider requires at least one provider");
+      throw new Error("[FallbackAiProvider] providers is empty: there is nothing to call. Pass at least one, e.g. { providers: [primary, backup] }.");
     }
 
     this.name = `fallback(${options.providers.map((p) => p.name).join("->")})`;

package/src/providers/GeminiProvider.ts

@@ -40,8 +40,7 @@ export interface GeminiProviderOptions {
   config?: RequestConfig;
   /** Idle-stream deadline and retry budget */
   retryConfig?: { timeout?: number; retries?: number };
-  /** Replacement `fetch`, for tests that script the wire. Replaces v2's
-   *  injected SDK client — see {@link AnthropicProviderOptions.fetchImpl}. */
+  /** Replacement `fetch`, for tests that script the wire — see {@link AnthropicProviderOptions.fetchImpl}. */
   fetchImpl?: typeof fetch;
 }
 
@@ -56,10 +55,8 @@ export class GeminiProvider extends ProviderAdapter {
   };
 
   constructor(options: GeminiProviderOptions) {
-    if (!options.apiKey) throw new Error("Gemini API key is required");
-    if (!options.model) {
-      throw new Error("Model is required. Example: 'gemini-3.1-pro-preview'");
-    }
+    if (!options.apiKey) throw new Error(`[GeminiProvider] apiKey is empty: the provider cannot authenticate. Pass { apiKey: process.env.GEMINI_API_KEY } and check the variable is set.`);
+    if (!options.model) throw new Error(`[GeminiProvider] model is empty: there is no default. Pass one, e.g. { model: "gemini-2.5-flash" }.`);
 
     super({
       provider: createGeminiProvider({

package/src/providers/GenericOpenAICompatibleProvider.ts

@@ -97,18 +97,18 @@ class GenericOpenAICompatibleProvider extends OpenAICompatibleProvider {
 
   constructor(options: OpenAICompatibleOptions) {
     if (!options.name) {
-      throw new Error("An OpenAI-compatible provider needs a `name`.");
+      throw new Error('[OpenAICompatibleProvider] name is empty: it labels the provider in logs and errors. Pass one, e.g. { name: "ollama" }.');
     }
     if (!options.baseURL) {
-      throw new Error(`[${options.name}] A \`baseURL\` is required.`);
+      throw new Error(`[${options.name}] baseURL is empty: there is no server to call. Pass one, e.g. { baseURL: "http://localhost:11434/v1" }.`);
     }
     if (!options.apiKey) {
       throw new Error(
-        `[${options.name}] An \`apiKey\` is required — use any non-empty string for servers that ignore it.`
+        `[${options.name}] apiKey is empty: the provider cannot authenticate. Pass your key, or any non-empty string for a server that ignores it.`
       );
     }
     if (!options.model) {
-      throw new Error(`[${options.name}] A \`model\` is required.`);
+      throw new Error(`[${options.name}] model is empty: there is no default. Pass the id your server serves, e.g. { model: "llama3.3" }.`);
     }
 
     super({

package/src/providers/OpenAIProvider.ts

@@ -39,14 +39,13 @@ export class OpenAIProvider extends OpenAICompatibleProvider {
     supportsNativeJsonSchema: true,
     supportsStreaming: true,
     supportsStreamingToolCalls: true,
-    // v3: the shape auto-caches repeated prefixes and now reports the hit
-    // count, which the old adapter never read.
+    // The shape auto-caches repeated prefixes and reports the hit count.
     supportsPromptCaching: true,
   };
 
   constructor(options: OpenAIProviderOptions) {
-    if (!options.apiKey) throw new Error("OpenAI API key is required");
-    if (!options.model) throw new Error("Model is required. Example: 'gpt-5.6' or 'gpt-5.5'");
+    if (!options.apiKey) throw new Error(`[OpenAIProvider] apiKey is empty: the provider cannot authenticate. Pass { apiKey: process.env.OPENAI_API_KEY } and check the variable is set.`);
+    if (!options.model) throw new Error(`[OpenAIProvider] model is empty: there is no default. Pass one, e.g. { model: "gpt-5.6" }.`);
 
     super({
       id: "openai",

package/src/providers/OpenRouterProvider.ts

@@ -59,8 +59,10 @@ export class OpenRouterProvider extends OpenAICompatibleProvider {
   };
 
   constructor(options: OpenRouterProviderOptions) {
-    if (!options.apiKey) throw new Error("OpenRouter API key is required");
-    if (!options.model) throw new Error("Model is required. See https://openrouter.ai/models");
+    if (!options.apiKey) throw new Error(`[OpenRouterProvider] apiKey is empty: the provider cannot authenticate. Pass { apiKey: process.env.OPENROUTER_API_KEY } and check the variable is set.`);
+    if (!options.model) {
+      throw new Error(`[OpenRouterProvider] model is empty: there is no default. Pass one, e.g. { model: "anthropic/claude-sonnet-5" }; the ids are listed at https://openrouter.ai/models.`);
+    }
 
     super({
       id: "openrouter",

package/src/providers/ProviderAdapter.ts

@@ -61,11 +61,9 @@ export interface RetryConfig {
   /**
    * How long a stream may stay SILENT before it is considered wedged.
    *
-   * In v2 this was a total wall-clock cap on a non-streaming call, so a healthy
-   * but long generation died at the one-minute mark. It now bounds silence
-   * instead: time to the first byte, and the gap between any two after it. A
-   * request that never gets a reply still fails at the same moment; one that is
-   * steadily producing tokens is left alone.
+   * It bounds silence, not the whole call: time to the first byte, and the gap
+   * between any two after it. A request that never gets a reply fails at that
+   * moment; one that is steadily producing tokens is left alone, however long.
    */
   timeout: number;
   /** Retries AFTER the first attempt, so `0` still performs one call. */
@@ -90,10 +88,8 @@ export function resolveRetryConfig(input?: { timeout?: number; retries?: number
 /**
  * Request defaults sent with every call.
  *
- * Only the fields every supported shape has. In v2 each provider took its own
- * vendor's SDK parameter type here — which is how one vendor's package ended
- * up in the dependency tree of consumers who used a different vendor, and how
- * a field set on one provider silently vanished on another.
+ * Only the fields every supported shape has, so a field set on one provider
+ * means the same on another and no vendor's package enters the dependency tree.
  */
 export interface RequestConfig {
   temperature?: number;
@@ -104,7 +100,9 @@ export interface RequestConfig {
    * 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
+   * sent, so the model decides — `medium` on GPT-5 and older, and on
+   * OpenRouter GLM 5.3 Flash thinks on most of the hosts that serve it. Set
+   * `"none"` where a turn must not think; 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
@@ -290,6 +288,8 @@ export abstract class ProviderAdapter implements AiProvider {
   public abstract readonly capabilities: ProviderCapabilities;
 
   protected readonly provider: Provider;
+  /** `provider` without the fallback chain: the one model this adapter was built for. */
+  private readonly primary: Provider;
   protected readonly primaryModel: string;
   protected readonly backupModels: string[];
   protected readonly retryConfig: RetryConfig;
@@ -304,6 +304,7 @@ export abstract class ProviderAdapter implements AiProvider {
     this.primaryModel = init.model;
     this.backupModels = init.backupModels ?? [];
     this.retryConfig = resolveRetryConfig(init.retryConfig);
+    this.primary = init.provider;
 
     if (init.fallbacks && init.fallbacks.length > 0) {
       const coreProviders: Provider[] = [
@@ -337,9 +338,14 @@ export abstract class ProviderAdapter implements AiProvider {
    * boot when it is `null` — that model cannot serve this framework's turns).
    * Log `calls`: `0/3 and 3/3` is what makes the next model swap's regression
    * obvious. Costs `samples × 2` short calls, and errors propagate.
+   *
+   * It asks the primary alone, never the fallback chain. The answer configures
+   * this adapter's model; a call the chain handed to a fallback would score
+   * another model as this one. Each fallback is an adapter of its own: probe it
+   * the same way.
    */
   async probeJsonWithTools(opts?: ProbeOptions): Promise<JsonWithToolsProbe> {
-    return probeJsonWithTools(this.provider, {
+    return probeJsonWithTools(this.primary, {
       model: this.primaryModel,
       ...(opts ?? {}),
     });
@@ -468,8 +474,7 @@ export abstract class ProviderAdapter implements AiProvider {
               tokensUsed: acc.promptTokens + (acc.completionTokens ?? 0),
               promptTokens: acc.promptTokens,
               completionTokens: acc.completionTokens,
-              // New in v3: the cache-hit subset of the prompt, which the old
-              // adapters never read and which is billed far cheaper.
+              // The cache-hit subset of the prompt, billed far cheaper.
               cachedInputTokens: acc.cachedInputTokens,
             }
           : {}),

package/src/providers/ZaiProvider.ts

@@ -51,7 +51,7 @@ export class ZaiProvider extends ProviderAdapter {
   };
 
   constructor(options: ZaiProviderOptions) {
-    if (!options.apiKey) throw new Error("Z.ai Coding Plan API key is required");
+    if (!options.apiKey) throw new Error(`[ZaiProvider] apiKey is empty: the provider cannot authenticate. Pass { apiKey: process.env.ZAI_API_KEY } and check the variable is set.`);
 
     const model = options.model ?? "glm-5.3-flash";
     super({

package/src/types/agent.ts

@@ -78,8 +78,12 @@ export interface AgentOptions<C = unknown, D = unknown> {
 
 // ── turn() input ────────────────────────────────────────────────────────
 
-/** The host's reason the assistant cannot speak. Zero calls unless `understand: true`. */
-export type Silenced = string | { reason: string; understand?: boolean };
+/**
+ * The host's reason the assistant cannot speak. Zero calls unless `understand: true`.
+ * A talk or `say` step a run reaches under it ends the run; with `skip: true` the step is
+ * skipped and the run goes on, for a gate that only stops messages (a closed channel window).
+ */
+export type Silenced = string | { reason: string; understand?: boolean; skip?: boolean };
 
 type ContextField<C> = undefined extends C ? { context?: C } : { context: C };
 
@@ -87,7 +91,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 +116,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 +138,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;
@@ -134,7 +149,7 @@ export interface ScheduleEntry {
 export type EndReason = "end" | "flow" | "reset" | "skipped" | "failed" | "replaced";
 
 export interface TurnResult<D = unknown> {
-  /** Version unchanged; the host bumps it on save. */
+  /** Version unchanged by a turn; `Store.save` bumps it and returns the saved session. */
   session: Session<D>;
   /** False: save nothing, send nothing. */
   changed: boolean;