@falai/agent 4.0.0-alpha.13 → 4.0.0-alpha.15

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,8 +91,6 @@ 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 =
@@ -104,6 +103,9 @@ 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;
@@ -165,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 = "";
@@ -220,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. */
@@ -331,7 +331,7 @@ function buildPrompt<C, D>(
     "idle" in talk
       ? [guideline(talk.idle.prompt)]
       : [
-          `## Flow\n${talk.flow.name}${talk.flow.description ? `: ${talk.flow.description}` : ""}`,
+          `## 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.
@@ -344,17 +344,26 @@ function buildPrompt<C, D>(
       inline,
       ...body,
       instructionsSection([{ caption: "[Always]", items: req.instructions }], scope),
-      inputSection(req.input),
+      inputSection(req.input, req.history),
       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;
 }
 
 /** The envelope restated in words, for providers that follow the schema by prompt only. */
@@ -385,16 +394,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,15 +29,12 @@ 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_-]+$/;
-
 export class Understand<C = unknown, D = unknown> {
   constructor(private readonly options: AgentOptions<C, D>) {}
 
@@ -111,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}`;
 }

package/src/core/contracts.ts

@@ -70,8 +70,11 @@ 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;
@@ -87,7 +90,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,

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;
@@ -290,6 +286,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 +302,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 +336,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 +472,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

@@ -145,7 +145,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;

package/src/types/ai.ts

@@ -8,12 +8,10 @@ import type { HistoryItem } from "./history.js";
 /**
  * How hard the model thinks before answering.
  *
- * v3 takes `@providerkit/core`'s effort union, which every provider speaks:
- * "none" | "low" | "medium" | "high" | "max". Absent means the provider's own
- * default and is never sent. v2's "minimal" is spelled "low"; `summary` and
- * `includeThoughts` are gone because they are no longer choices — the shapes
- * that need them get them switched on whenever an effort is set, which is the
- * only setting that ever produced reasoning output.
+ * `@providerkit/core`'s effort union, which every provider speaks: "none" |
+ * "low" | "medium" | "high" | "max". Absent means the provider's own default
+ * and is never sent. The shapes that need a thought summary switched on get it
+ * whenever an effort is set, so there is no separate setting for it.
  */
 export interface ReasoningConfig {
   effort?: Effort;

package/src/types/compaction.ts

@@ -9,6 +9,7 @@ import type { HistoryItem } from "./history.js";
  * Configuration for the compaction engine.
  *
  * Validation constraints:
+ * - `maxTokens` must be > 0
  * - `compactionThreshold` must be between 0.5 and 0.95
  * - `preserveRecentCount` must be >= 2
  * - `maxToolResultChars` must be > 0

package/src/types/errors.ts

@@ -5,16 +5,11 @@
 /**
  * The normalized provider failure, and the kinds it comes in.
  *
- * v3 re-exports these from `@providerkit/core` rather than keeping a second
- * copy. The taxonomy is wider there — thirteen kinds named by what actually
- * fixes them, where this package had eight — so a caller can now tell an
+ * `ProviderError` comes from `@providerkit/core` and is re-exported here. Its
+ * thirteen kinds are named by what fixes them, so a caller can tell an
  * exhausted balance from a per-minute throttle, a plan that never included the
- * API from a wrong key, and an outgrown context window from a bad request.
- *
- * Breaking: the kind lives on `error.kind`, not `error.code`, and the spellings
- * changed with the taxonomy (`rate_limited` is `rate`, `overloaded` is
- * `overload`, `invalid_request` splits into `invalid`, `context`, `model` and
- * `content`). `schema_rejected` is gone: nothing ever produced it.
+ * API from a wrong key, and an outgrown context window from a bad request. The
+ * kind lives on `error.kind`.
  */
 export { ProviderError } from "@providerkit/core";
 export type { ErrorKind } from "@providerkit/core";
@@ -33,9 +28,13 @@ export class SessionConflictError extends Error {
         public readonly actualVersion: number | undefined,
     ) {
         super(
-            `[SessionConflictError] Session "${sessionId}" was modified concurrently: ` +
-            `expected version ${expectedVersion}, found ${actualVersion ?? 'none'}. ` +
-            `Reload the session and retry the operation.`
+            // A row that vanished between load and save (a TTL expiry, a delete) is not a race.
+            actualVersion === undefined && expectedVersion > 0
+                ? `[SessionConflictError] Session "${sessionId}" is gone from the store: it was at version ${expectedVersion} ` +
+                  `and has since been deleted or expired. Load it again; a load that finds nothing starts a new conversation.`
+                : `[SessionConflictError] Session "${sessionId}" was modified concurrently: ` +
+                  `expected version ${expectedVersion}, found ${actualVersion ?? 'none'}. ` +
+                  `Reload the session and retry the operation.`
         );
         this.name = 'SessionConflictError';
     }

package/src/types/history.ts

@@ -176,13 +176,3 @@ export interface Event<
   /** Unique event identifier */
   id?: string;
 }
-
-/**
- * An emitted event (staged for inclusion)
- */
-export interface EmittedEvent<
-  TData = MessageEventData | ToolEventData | StatusEventData
-> extends Event<TData> {
-  /** Whether this event has been committed */
-  committed?: boolean;
-}

package/src/types/index.ts

@@ -85,7 +85,6 @@ export type {
 
 export type {
   AssistantHistoryItem,
-  EmittedEvent,
   Event,
   History,
   HistoryItem,

package/src/types/session.ts

@@ -127,7 +127,7 @@ export interface StepOutcome {
 export interface Session<D = unknown> {
   id: string;
   v: 4;
-  /** Optimistic-concurrency version; the host bumps it on save. */
+  /** Optimistic-concurrency version. A turn leaves it unchanged; `Store.save` bumps it and returns the saved session. */
   version: number;
   data: Partial<D>;
   /** Live runs only. */

package/src/utils/clock.ts

@@ -34,7 +34,7 @@ export function fakeClock(iso: string): FakeClock {
 
 function parseIso(iso: string): number {
   const ms = Date.parse(iso);
-  if (Number.isNaN(ms)) throw new Error(`fakeClock: "${iso}" is not a date.`);
+  if (Number.isNaN(ms)) throw new Error(`[fakeClock] "${iso}" is not a date: Date.parse cannot read it. Pass ISO text, e.g. "2026-09-20T10:00:00.000Z".`);
   return ms;
 }