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

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,37 @@ 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.";
+/** The step's fixed question follows this reply (`fixedAfter`): the reply answers the lead and leaves the asking to it. */
+const ANSWER_BEFORE_QUESTION =
+  "Answer what the customer's message asks, in the flow of the conversation. Ask nothing yourself: right after your reply, " +
+  "this question goes out word for word, so do not ask it or anything like it:";
 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;
@@ -145,7 +162,8 @@ export class Speak<C = unknown, D = unknown> {
   /** The round loop shared by both entry points: yields deltas, returns the outcome. */
   private async *rounds(req: SpeakRequest<C, D>, streaming: boolean): AsyncGenerator<string, SpeakOutcome> {
     const talk = req.talk;
-    const envelope = buildEnvelope(this.options.fields, "idle" in talk ? [] : talk.pending);
+    // Fields are read by the fixed question's own answer, never by the reply that precedes it.
+    const envelope = buildEnvelope(this.options.fields, "idle" in talk || talk.fixedAfter !== undefined ? [] : talk.pending);
     const { system, turn: prompt } = buildPrompt(this.options, req, envelope);
     const maxLoops = this.options.maxToolLoops ?? DEFAULT_MAX_TOOL_LOOPS;
     const tools = maxLoops > 0 ? req.tools : [];
@@ -154,7 +172,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 +226,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,9 +336,13 @@ 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),
-          pendingSection(talk.pending, options.fields, talk.step.ask ?? {}, scope),
+          `## Flow\n${talk.flow.name}${talk.flow.description ? `: ${render(talk.flow.description, scope)}` : ""}`,
+          ...(talk.fixedAfter !== undefined
+            ? [`${GUIDELINE_HEADING}\n${ANSWER_BEFORE_QUESTION}\n"${talk.fixedAfter}"`]
+            : [
+                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 +353,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 +419,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,35 +24,35 @@ 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_-]+$/;
+const SECTIONS = ["flows", "mentions", "extract", "branches", "fields", "asks"] as const;
 
 export class Understand<C = unknown, D = unknown> {
-  constructor(private readonly options: AgentOptions<C, D>) {}
+  /** Some flow opens a step with a fixed question: whether the lead asked something decides if it waits. */
+  private readonly judgesAsks: boolean;
+
+  constructor(private readonly options: AgentOptions<C, D>) {
+    this.judgesAsks = (options.flows ?? []).some((flow) => flow.steps.some((step) => "question" in step && step.question !== undefined));
+  }
 
   async run(req: UnderstandRequest<C, D>): Promise<Understanding> {
     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);
+    const jsonSchema = buildEnvelope(req, candidates, aliases, this.judgesAsks);
     const { system, turn: prompt } = this.buildPrompt(req, candidates, aliases, jsonSchema);
 
     // Provider failures propagate: in this phase the turn throws and the host retries the input.
@@ -113,45 +114,13 @@ 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}`;
 }
 
 // ── Envelope ────────────────────────────────────────────────────────────
 
-function buildEnvelope<C, D>(req: UnderstandRequest<C, D>, candidates: Flow<C, D>[], aliases: Aliases): StructuredSchema {
+function buildEnvelope<C, D>(req: UnderstandRequest<C, D>, candidates: Flow<C, D>[], aliases: Aliases, judgesAsks: boolean): StructuredSchema {
   const properties: Record<string, StructuredSchema> = {};
 
   if (candidates.length) {
@@ -185,6 +154,9 @@ function buildEnvelope<C, D>(req: UnderstandRequest<C, D>, candidates: Flow<C, D
     for (const [slug, def] of Object.entries(req.fields)) defs[aliases.of(slug, "d")] = def;
     properties.fields = toWireSchema(defs, { nullable: true });
   }
+  if (judgesAsks) {
+    properties.asks = { type: ["boolean", "null"], description: "The message asks something the reply must answer" };
+  }
 
   return { type: "object", properties, required: Object.keys(properties), additionalProperties: false };
 }
@@ -245,8 +217,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 +238,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:");
@@ -316,6 +291,9 @@ const OUTPUT_LINES: Record<Section, string> = {
   extract: "- extract: per item id, an object with the values pulled from the message; null values when the item was not brought up",
   branches: "- branches: true or false per question id",
   fields: "- fields: one value per detail, null when the customer did not give it",
+  asks:
+    "- asks: true when the message asks something the reply has to answer (a question, a request for a price, a photo, " +
+    "whether an item is in stock, a store fact); false when it only answers the assistant, greets or confirms",
 };
 
 /**
@@ -323,7 +301,7 @@ const OUTPUT_LINES: Record<Section, string> = {
  * null for anything extracted, so a prompt-only model never reads a
  * placeholder as a default value.
  */
-const PLACEHOLDER: Record<Section, unknown> = { flows: 0, mentions: false, extract: null, branches: false, fields: null };
+const PLACEHOLDER: Record<Section, unknown> = { flows: 0, mentions: false, extract: null, branches: false, fields: null, asks: false };
 
 function outputSection(schema: StructuredSchema): string {
   const present = SECTIONS.filter((s) => schema.properties?.[s] !== undefined);
@@ -390,12 +368,14 @@ function parseReply(reply: Record<string, unknown>, aliases: Aliases): Understan
   for (const [key, raw] of entries(reply.extract)) {
     if (isRecord(raw)) extract[aliases.real(key)] = given(raw);
   }
+  const asks = coerceField({ type: "boolean" }, reply.asks);
   return {
     flows,
     mentions: booleans(reply.mentions, aliases),
     extract,
     branches: booleans(reply.branches, aliases),
     fields: given(Object.fromEntries(entries(reply.fields).map(([k, v]) => [aliases.real(k), v]))),
+    ...(asks.ok && typeof asks.value === "boolean" ? { asks: asks.value } : {}),
     llmCalls: 1,
   };
 }

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";
@@ -48,6 +48,11 @@ export interface Understanding {
   branches: Record<string, boolean>;
   /** field → raw value the lead gave, or nothing. */
   fields: Record<string, unknown>;
+  /**
+   * The lead's message asks something a reply must answer. Judged only while a flow has a fixed
+   * `question`: one that would go out now waits for the answer when this is not `false`.
+   */
+  asks?: boolean;
   llmCalls: number;
   usage?: TokenUsage;
 }
@@ -61,6 +66,11 @@ export interface TalkRequest<C = unknown, D = unknown> {
   step: StepBase<D> & TalkStep<C, D>;
   /** `step.collect` minus known minus at `maxAsks`, in order. */
   pending: string[];
+  /**
+   * The step's fixed question, rendered. It goes out word for word right after this reply, so the
+   * reply only answers what the lead asked: it asks nothing and reads no field.
+   */
+  fixedAfter?: string;
 }
 
 /** No run holds the floor; the idle speaker answers. */
@@ -70,11 +80,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 +105,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",