@falai/agent 4.0.0-alpha.8 → 4.0.0

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,
@@ -90,18 +91,23 @@ function deferralOf(error: unknown): Deferral {
     ...(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 lead asked something on a step with a fixed question (`fixedQuestion`): one reply answers it and asks the question. */
+const ANSWER_THEN_FIXED = "Answer what the customer's message asks, then ask the step's question below, in the same message.";
 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 +160,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.fixedQuestion !== 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 : [];
@@ -163,7 +170,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 = "";
@@ -175,6 +181,7 @@ export class Speak<C = unknown, D = unknown> {
         ...(system ? { system } : {}),
         history,
         context: req.context,
+        sessionId: req.sessionId,
         tools: offerTools ? wireTools : undefined,
         parameters: { jsonSchema: envelope.schema, schemaName: "speak" },
       };
@@ -218,14 +225,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. */
@@ -329,9 +335,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.fixedQuestion !== undefined
+            ? [`${GUIDELINE_HEADING}\n${ANSWER_THEN_FIXED}`]
+            : [
+                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 : {}),
         ];
@@ -342,17 +352,57 @@ function buildPrompt<C, D>(
       inline,
       ...body,
       instructionsSection([{ caption: "[Always]", items: req.instructions }], scope),
-      inputSection(req.input),
+      inputSection(req.input, req.history),
+      saidSection(req.said),
+      "idle" in talk ? null : fixedQuestionSection(talk.fixedQuestion),
       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 step's fixed question, for the reply to end with. It sits last, after the customer's message: in the
+ * middle of the prompt, a voice instruction ("end with a question") outranked it and the reply asked its own.
+ */
+function fixedQuestionSection(question: string | undefined): string | null {
+  if (question === undefined) return null;
+  return [
+    "## The step's question",
+    `"${question}"`,
+    "End your message with this question, in these words. Change them only where your answer already covered part of it " +
+      "or where they would contradict your answer. Ask nothing else.",
+  ].join("\n");
 }
 
 /** The envelope restated in words, for providers that follow the schema by prompt only. */
@@ -383,16 +433,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
@@ -28,17 +29,19 @@ import { coerceField, isKnown, pendingFields, toWireSchema } from "../utils/sche
 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);
@@ -49,7 +52,7 @@ export class Understand<C = unknown, D = unknown> {
     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.
@@ -58,6 +61,7 @@ export class Understand<C = unknown, D = unknown> {
       ...(system ? { system } : {}),
       history: req.history,
       context: req.context,
+      sessionId: req.sessionId,
       parameters: { jsonSchema, schemaName: UNDERSTAND_SCHEMA_NAME },
     });
 
@@ -111,45 +115,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) {
@@ -183,6 +155,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 };
 }
@@ -317,6 +292,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",
 };
 
 /**
@@ -324,7 +302,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);
@@ -391,12 +369,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";
@@ -20,6 +20,8 @@ export type InputKind = "message" | "wake" | "event" | "start";
 
 /** Everything the understand call may judge this turn. Runner filters by `if` and `repeat` first. */
 export interface UnderstandRequest<C = unknown, D = unknown> {
+  /** The session's id: the model call carries it, so a gateway can keep the conversation on one cached route. */
+  sessionId: string;
   text: string;
   history: History;
   context: C;
@@ -48,6 +50,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 +68,12 @@ 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, when the lead's message asked something. The reply answers it
+   * and asks this question in the same message, in the owner's words where they fit. It reads no field:
+   * the understand call already read the lead's message.
+   */
+  fixedQuestion?: string;
 }
 
 /** No run holds the floor; the idle speaker answers. */
@@ -69,12 +82,22 @@ export interface IdleRequest<C = unknown, D = unknown> {
 }
 
 export interface SpeakRequest<C = unknown, D = unknown> {
+  /** See `UnderstandRequest.sessionId`. */
+  sessionId: string;
   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 +110,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",