@falai/agent 2.6.1 → 3.0.0

package/docs/migration/v2-6-to-v2-7.md

@@ -0,0 +1,246 @@
+---
+title: "v2.6 → v2.7 migration"
+description: "What changed in v2.7: per-turn message/allowedFlows params, the default history bound, finalize-before-persist ordering, soft-failing tools, bare error propagation, and provider client injection."
+type: migration
+order: 3
+---
+
+# v2.6 → v2.7 Migration
+
+**Version:** 2.7.0 — Consumer-fit release surface and correctness batch (tool directives end-to-end, hook desugaring, retry classification, error propagation)
+
+## Summary
+
+v2.7 is mostly **additive**: `respond()` / `respondStream()` gain `message` and `allowedFlows` parameters and return richer observability (`endedFlows`, `metadata.tokensUsed`), providers accept a pre-configured SDK `client`, and `restoreSession` joins the public barrel. Four behavior changes are worth calling out even though none changes a type signature: the default history bound is now active, step `finalize` runs before persistence, crashed tools report failure to the model instead of throwing, and session load failures propagate.
+
+If your integration passes explicit histories and catches errors broadly, the upgrade is usually zero-code. The sections below cover each case.
+
+---
+
+## Table of Contents
+
+1. [New turn parameters: `message` and `allowedFlows`](#1-new-turn-parameters-message-and-allowedflows)
+2. [`AgentResponse` gains `endedFlows` and `metadata.tokensUsed`](#2-agentresponse-gains-endedflows-and-metadatatokensused)
+3. [Default history bound is active (400)](#3-default-history-bound-is-active-400)
+4. [Step `finalize` now runs BEFORE persistence](#4-step-finalize-now-runs-before-persistence)
+5. [Crashed tools soft-fail to the model](#5-crashed-tools-soft-fail-to-the-model)
+6. [Tool directives work end-to-end](#6-tool-directives-work-end-to-end)
+7. [Errors propagate typed and bare](#7-errors-propagate-typed-and-bare)
+8. [Step hooks: shorthand and `hooks.*` both run](#8-step-hooks-shorthand-and-hooks-both-run)
+9. [Provider `client` injection and retry classification](#9-provider-client-injection-and-retry-classification)
+10. [`restoreSession` exported](#10-restoresession-exported)
+11. [Behavioral changes to be aware of](#11-behavioral-changes-to-be-aware-of)
+
+---
+
+## 1. New turn parameters: `message` and `allowedFlows`
+
+Both `respond()` and `respondStream()` accept two new optional fields on the shared params object.
+
+**`message`** — pass the user's turn instead of appending it to the history yourself. The engine appends it to what the model sees this turn *and* records it on the returned session's history, then appends the assistant reply on top. Callers who hold sessions no longer maintain history arrays by hand.
+
+**`allowedFlows`** — restricts this turn's *routing* candidates to the given flow ids/titles. Directive targets (`goTo` etc.) still resolve against the full registry. Use for entry-pin funnels instead of cloning or filtering agents.
+
+```typescript
+// ─── v2.6: caller owns the user turn ───
+history.push({ role: "user", content: userInput });
+const response = await agent.respond({ history });
+
+// ─── v2.7: the engine owns appending ───
+const response = await agent.respond({
+  history,
+  message: userInput,
+  allowedFlows: ["order"],   // optional routing pin
+});
+// response.session.history already carries user + assistant turns
+```
+
+Existing calls that pass pre-built `history` arrays keep working unchanged.
+
+---
+
+## 2. `AgentResponse` gains `endedFlows` and `metadata.tokensUsed`
+
+`respond()` can now tell you directly which flows left their active position during the turn:
+
+```typescript
+interface EndedFlow {
+  flowId: string;
+  title?: string;
+  reason: StoppedReason;   // 'completed' | 'last_step' | 'goto' | …
+}
+
+interface AgentResponse<TData> {
+  // …existing fields…
+  endedFlows?: EndedFlow[];          // completions, redirects, resets
+  metadata?: { tokensUsed?: number }; // provider-reported usage for the primary generation call
+}
+```
+
+Before, you re-derived exits from `executedSteps` plus session-cursor inspection; `endedFlows` removes the guesswork. `metadata.tokensUsed` is present only when the provider reports usage, and covers only the turn's primary generation call (routing and extraction sub-calls are not included). On streaming turns, provider usage rides on chunk `metadata`; stream chunks do not carry `endedFlows`.
+
+---
+
+## 3. Default history bound is active (400)
+
+A hard bound now applies to `session.history` even when you configure no compaction: entries beyond `maxHistoryMessages` (default **400**) are trimmed at end-of-turn finalize — and on interim auto-saves — always keeping whole assistant/tool pairs together. Each trim logs a warning recommending compaction for summarization.
+
+```typescript
+const agent = createAgent({
+  // …
+  maxHistoryMessages: 1000,  // raise the bound…
+  // …or configure compaction for summarization instead of truncation:
+  // compaction: { maxTokens: 8000 },
+});
+```
+
+Set `maxHistoryMessages: 0` to disable bounding entirely (previous unbounded behavior). Long-running `chat()` / `stream()` sessions can no longer grow until the provider context limit bricks them.
+
+---
+
+## 4. Step `finalize` now runs BEFORE persistence
+
+The step `finalize` hook previously ran after the auto-save, so state writes it made could miss the persisted row when the conversation ended on that turn. The order inside end-of-turn finalization is now:
+
+1. History bound + deterministic compaction
+2. **`finalize` hook** — its state writes land on this turn's session
+3. **Auto-save to persistence**
+4. Live-session sync
+
+No code change is needed — but hooks that "didn't stick" across restarts now do, and a control-flow directive returned by `finalize` queues for the start of the next turn as before.
+
+---
+
+## 5. Crashed tools soft-fail to the model
+
+A tool handler that throws used to surface as an error escaping `respond()`. It is now reported **to the model** as a failed tool result — a `role: "tool"` message shaped `{"success":false,"error":"…"}` — so the model can react to the failed call instead of the turn dying (or worse, a fabricated success confirming an action that never happened). Unknown tool names behave the same way.
+
+```typescript
+// The turn survives; the model sees the failure and can apologize/retry.
+handler: () => {
+  throw new Error("upstream API is down");
+},
+```
+
+If you relied on catching handler crashes out of `respond()`, catch them inside the handler instead and return `{ success: false, error }` — same signal to the model, explicit in your code.
+
+---
+
+## 6. Tool directives work end-to-end
+
+Directives emitted by tools now reliably reach the engine (previously they could be collected and dropped):
+
+- `ctx.dispatch(directive)` mid-handler and returning `{ directive }` are equivalent.
+- State fields (`dataUpdate`, `contextUpdate`) apply immediately.
+- A `reply` directive short-circuits the remaining tool loop — its verbatim text becomes the final message with no follow-up LLM call.
+- Control-flow fields queue on `session.pendingDirective` and steer the next turn (same deferred semantics as `agent.dispatch()`).
+
+See [Tool → Directive wiring](../reference/tool.md#directive-wiring-and-turn-semantics).
+
+---
+
+## 7. Errors propagate typed and bare
+
+Two related changes to how turn failures reach your `catch`:
+
+- **`ProviderError` propagates bare out of `respond()`** — `instanceof ProviderError` works directly; no unwrapping through `ResponseGenerationError.details.originalError`. Same for `SessionConflictError`.
+- **`ResponseGenerationError` is exported** and exposes the original error on the native `.cause` (as well as `details.originalError`). All other turn failures still wrap into it.
+
+```typescript
+// ─── v2.6: unwrap through details ───
+catch (err) {
+  const original = (err as { details?: { originalError?: unknown } }).details?.originalError;
+  if (original instanceof ProviderError) { /* … */ }
+}
+
+// ─── v2.7: instanceof survives ───
+import { ProviderError, ResponseGenerationError } from "@falai/agent";
+
+catch (err) {
+  if (err instanceof ProviderError) {
+    // err.code, err.provider, err.cause — branch directly
+  }
+  if (err instanceof ResponseGenerationError) {
+    // err.cause is the original error
+  }
+}
+```
+
+On streaming turns, errors arrive wrapped as `ResponseGenerationError` on the final chunk's `error` field (with the original on `.cause`) rather than thrown.
+
+---
+
+## 8. Step hooks: shorthand and `hooks.*` both run
+
+Declaring a top-level `prepare`/`finalize` alongside `hooks.prepare`/`hooks.finalize` used to silently pick one. Now **both run** — the shorthand first, then the hook — with their directive returns merged via Algorithm 4. One new validation: combining a *tool-form* handler (a tool id or `Tool` object) with a function `hooks.*` entry throws `FlowConfigurationError` at construction, since a single position cannot compose a tool reference with a function.
+
+```typescript
+{
+  id: "enrich",
+  prepare: (context, data) => ({ dataUpdate: { tier: lookupTier(context, data?.email) } }),
+  hooks: {
+    // ALSO runs — after the shorthand above, results merged
+    prepare: ({ data }) => {
+      if (data.tier === "blocked") return { halt: true, reply: "Account on hold." };
+    },
+  },
+}
+```
+
+---
+
+## 9. Provider `client` injection and retry classification
+
+**`AnthropicProvider` and `GeminiProvider` accept a `client` option** — a pre-configured SDK client that overrides the internally-constructed one. Intended for tests injecting scripted transports; production callers should keep passing `apiKey`.
+
+Retry semantics are now uniform and documented: deterministic failures (auth 401/403, invalid request 400/404/422, caller aborts) fail fast without burning the retry budget; retriable failures are rate limits, overloads, timeouts, and network faults. `retryConfig.timeout` also bounds time-to-first-token on streaming calls, so a stream that opens and then stalls is treated as failed and retried before the first delta is committed.
+
+---
+
+## 10. `restoreSession` exported
+
+`restoreSession<TData>(state)` joins the public barrel as the canonical inverse of `createPersistedState(session)` — restore a persisted blob verbatim (collected data and completed-flow history survive the round trip). Prefer it over the ambiguous `createSession(state)` overload in custom persistence code.
+
+```typescript
+import { createPersistedState, restoreSession } from "@falai/agent";
+
+await store.put(id, JSON.stringify(createPersistedState(session)));
+const restored = restoreSession<MyData>(JSON.parse(await store.get(id)));
+```
+
+---
+
+## 11. Behavioral changes to be aware of
+
+Not breaking in the type sense, but observable at runtime:
+
+- **`SessionManager` load failures propagate.** A failed `sessionRepository.findById` (transient DB error) used to be swallowed and fall through to creating a blank session — which then saved over the existing row, erasing the conversation. The error now throws out of `getOrCreate()` / the first turn. A *missing* row still creates a new session as before.
+- **`MemoryAdapter` state writes now match the SQL adapters.** `updateStatus` / `updateCollectedData` / `updateFlowStep` bump `version` + `updatedAt` exactly like SQLite/PostgreSQL (previously Memory mutated in place without either), and `incrementMessageCount` refreshes timestamps without moving `version`. If you asserted on `MemoryAdapter` versions in your own tests, they may shift by design; all adapters are pinned to one contract in `tests/adapter-contract.test.ts`.
+- **`agent.dispatch` persists when an adapter is configured.** Previously the queued directive was memory-only until the next turn's auto-save — lost if the process ended first (webhook/cron callers). With an adapter + autoSave (the defaults) dispatch now saves immediately through the per-session save queue, so the directive survives process boundaries, and a stale session copy throws `SessionConflictError` instead of silently clobbering another writer. No adapter, or `autoSave: false`: unchanged memory-only behavior.
+- **Failed-turn rollback is unchanged**, but combined with §7 more failures now arrive as typed instances you can branch on rather than wrapped messages to string-match.
+
+---
+
+## Verification
+
+After migrating, run the type checker — it will flag any code that depended on `ResponseGenerationError` being name-matched only, or on provider options that have since widened:
+
+```bash
+bun run typecheck
+```
+
+To confirm the behavior changes land as described, the relevant suites are:
+
+```bash
+bun test tests/consumer-fit-api.test.ts   # message/allowedFlows, endedFlows, bare error propagation
+bun test tests/tool-loop-correctness.test.ts  # soft-failing tools
+bun test tests/directive-wiring.test.ts   # tool directives + finalize-before-persist ordering
+```
+
+## Cross-References
+
+- [createAgent reference](../reference/create-agent.md) — `maxHistoryMessages`, turn parameters, response surface
+- [Providers reference](../reference/providers.md) — `client` option and retry classification
+- [Errors reference](../reference/errors.md) — bare `ProviderError`, exported `ResponseGenerationError`
+- [Tool reference](../reference/tool.md) — directive wiring and soft-fail semantics
+- [Adapters reference](../reference/adapters.md) — `createPersistedState` / `restoreSession`

package/docs/reference/adapters.md

@@ -73,7 +73,7 @@ Both are **required columns** on every adapter's session schema. v1 schemas had
 
 ## Optimistic locking
 
-Every session row carries a `version: number` (on `SessionData` / `SessionState`), incremented by the repository on every update. `SessionRepository.update()` takes an optional compare-and-swap guard:
+Every session row carries a `version: number` (on `SessionData` / `SessionState`), incremented by the repository on every update. One deliberate exception: `incrementMessageCount` is bookkeeping — it refreshes the timestamps but never moves `version`, because count bumps run alongside `saveSessionState`'s compare-and-swap on every turn and would otherwise manufacture false conflicts. The state-writer helpers (`updateStatus`, `updateCollectedData`, `updateFlowStep`) go through `update()` and do bump it, identically on every built-in adapter. `SessionRepository.update()` takes an optional compare-and-swap guard:
 
 ```typescript
 interface SessionUpdateOptions {
@@ -126,6 +126,20 @@ await agent.respond({ history: [{ role: "user", content: "Hi again" }] });
 
 The engine looks the id up via `sessionRepository.findById`, hydrates the full `SessionState` (including `pendingDirective` and `signals`), and continues the turn against the restored state. Unknown ids create a new session with that id — there's no "not found" error path.
 
+### Session helpers for custom persistence code
+
+When you read or write session rows outside the agent (admin tooling, batch jobs), two exported helpers keep the round trip lossless:
+
+- `createPersistedState(session)` — strips transient pre-LLM directive fields (`appendPrompt`, `injectTools`, `halt`) before writing; call it (or an adapter that already does) before serializing.
+- `restoreSession<TData>(state)` — the canonical inverse: rebuilds a `SessionState` from a persisted blob verbatim, so collected data and completed-flow history survive the round trip. Prefer it over the ambiguous `createSession(state)` overload.
+
+```typescript
+import { createPersistedState, restoreSession } from "@falai/agent";
+
+await store.put(id, JSON.stringify(createPersistedState(session)));
+const session = restoreSession<MyData>(JSON.parse(await store.get(id)));
+```
+
 ## MemoryAdapter
 
 The implicit default. Omit `persistence` entirely to use it; instantiate explicitly only when you want to inspect or clear the store from tests.

package/docs/reference/branches.md

@@ -97,6 +97,8 @@ For each entry in declaration order:
 
 If no entry matches, branches return `undefined` and resolution falls through to linear `nextStep` / AI step selection. This is the same fall-through used when `branches` is omitted entirely.
 
+A matched entry outranks implicit flow completion. Branches are evaluated before the terminus check, so a step with no linear successor — normally the end of the flow — stays alive as long as one of its entries resolves a position. `then: '<own step id>'` is therefore how a flow parks: the step re-renders each turn until a condition sends the conversation elsewhere. Only a fall-through (no entry matched) or an explicit `then: { complete: true }` ends the flow there.
+
 The code-first ordering is deliberate: `if` is free, `when` costs tokens. Running `if` first short-circuits the AI call when the predicate already disqualifies the entry.
 
 ### Resolution of `then`

package/docs/reference/create-agent.md

@@ -42,6 +42,7 @@ interface AgentOptions<TContext = unknown, TData = unknown> {
   persistence?: PersistenceConfig<TData>;
   knowledgeBase?: Record<string, unknown>;
   flowSwitchMargin?: number;
+  maxHistoryMessages?: number;
   maxAutoStepsPerTurn?: number;
   maxDirectiveChain?: number;
   maxToolLoops?: number;
@@ -75,6 +76,7 @@ interface AgentOptions<TContext = unknown, TData = unknown> {
 | `persistence` | `PersistenceConfig<TData>` | no | in-memory | Session storage: `adapter`, `autoSave`, `userId`, plus `schemaVersion` / `migrateSession` for upgrading state written by older deployments. Omit for `MemoryAdapter`. |
 | `knowledgeBase` | `Record<string, unknown>` | no | — | Arbitrary JSON inlined into the prompt as background knowledge. |
 | `flowSwitchMargin` | `number` | no | `15` | Margin (0–100) the best alternative flow must exceed the current flow's score by before switching. Higher values make the agent stickier. |
+| `maxHistoryMessages` | `number` | no | `400` | Hard bound on `session.history`. Applied at end-of-turn finalize (and on interim auto-saves): the oldest entries are trimmed — never splitting an assistant/tool pair — and a warning is logged. Use `compaction` for summarization instead of truncation; set `0` to disable bounding entirely. |
 | `maxAutoStepsPerTurn` | `number` | no | `10` | Cap on consecutive `auto: true` steps per turn. Throws `FlowConfigurationError` when exceeded. |
 | `maxDirectiveChain` | `number` | no | `10` | Cap on chained directives per turn (e.g., `goTo` → `onEnter` emits `goTo` → …). Throws `FlowConfigurationError` when exceeded. |
 | `maxToolLoops` | `number` | no | `5` | Cap on tool-call follow-up rounds per turn, after the initial tool batch. Stops executing further tool calls when reached. Applies to both `respond()` and streaming. An explicit `0` disables tool loops. |
@@ -166,6 +168,32 @@ const agent = createAgent({
 });
 ```
 
+## Turn parameters and response surface
+
+`respond()` / `respondStream()` share one params object (`RespondParams`). Beyond the required `history`, two per-turn knobs matter:
+
+| Param | Type | Notes |
+|-------|------|-------|
+| `message` | `string` | The user's message for this turn. When set, the engine appends it to the history the model sees **and** to the returned session's history, then appends the assistant reply on top — callers who hold sessions no longer maintain history arrays by hand. Empty replies are not recorded. |
+| `allowedFlows` | `string[]` | Restricts this turn's **routing** candidates to these flow ids/titles. Directive targets (`goTo` etc.) still resolve against the full registry. Use for entry-pin funnels instead of cloning/filtering agents. |
+
+On the result side, `AgentResponse` carries:
+
+- `endedFlows?: EndedFlow[]` — flows that left their active position this turn (completions, redirects, resets), each as `{ flowId, title?, reason }`. Lets consumers stop re-deriving exits from `executedSteps` + cursor inspection. Streaming chunks do not carry `endedFlows`.
+- `metadata.tokensUsed?` — provider-reported usage for the turn's primary generation call (routing and extraction sub-calls are not included); present only when the provider reports usage. On streaming turns the same value rides on chunk `metadata`.
+
+```typescript
+const response = await agent.respond({
+  history,
+  message: "I'd like the vegetarian menu",
+  allowedFlows: ["order"],
+});
+
+for (const ended of response.endedFlows ?? []) {
+  console.log(`flow "${ended.title ?? ended.flowId}" ended (${ended.reason})`);
+}
+```
+
 ## Errors
 
 `createAgent` runs the same construction-time validation as `new Agent(...)`.

package/docs/reference/directive.md

@@ -74,7 +74,7 @@ Exactly **zero or one** position field may be set per directive. Setting two or
 | `abort` | `string` (reason) | `{ reason, clearSession? }` | End the conversation. The string form is sugar for `{ reason: <string> }`. When `clearSession: true`, the session is cleared at the next persistence write. `reply` cannot co-exist with `abort` — an aborted conversation cannot deliver a reply. |
 | `reset` | `true` | `{ step?, clearData?, reason? }` | Restart the current flow. `step` re-enters at a specific step (default: initial). `clearData: true` clears every field declared in the flow's `requiredFields` and `optionalFields`. |
 
-Each object form carries an optional `reason: string`. The reason is **observability-only** — it appears in the per-turn directive chain log and `AgentResponse.directiveChain` so traces are self-explaining, and it is stored on the corresponding event so post-mortems can read it. It does not influence routing, merging, or any pipeline decision.
+Each object form carries an optional `reason: string`. The reason is **observability-only** — it appears in the per-turn directive-chain debug log so traces are self-explaining. It does not influence routing, merging, or any pipeline decision.
 
 ### State writes
 

package/docs/reference/errors.md

@@ -9,7 +9,7 @@ order: 12
 
 > **Where this is introduced:** [Errors](../guides/error-handling.md)
 
-`@falai/agent` throws typed `Error` subclasses for every failure mode the framework owns. Catch them by class to discriminate construction errors from runtime errors, and by `error.name` when classes that are not exported (e.g. `DataValidationError`, `ResponseGenerationError`) need to be matched.
+`@falai/agent` throws typed `Error` subclasses for every failure mode the framework owns. Catch them by class to discriminate construction errors from runtime errors, and by `error.name` when a class that is not exported (`DataValidationError`) needs to be matched.
 
 Every thrown message follows the same format contract:
 
@@ -32,7 +32,7 @@ class ToolExecutionError      extends Error {
 }
 class NotImplementedError     extends Error { /* name = "NotImplementedError" */ }
 class ProviderError           extends Error {
-  code: ProviderErrorCode;   // 'rate_limited' | 'overloaded' | 'auth' | 'invalid_request'
+  kind: ErrorKind;   // 'rate' | 'overload' | 'quota' | 'entitlement' | 'auth' | 'context' | …
                              // | 'schema_rejected' | 'timeout' | 'network' | 'unknown'
   provider: string;          // e.g. "openai"
   cause?: unknown;           // original SDK/HTTP error
@@ -42,10 +42,8 @@ class SessionConflictError    extends Error {
   expectedVersion: number;
   actualVersion: number | undefined;
 }
-
-// Internal — match by `error.name` (not exported from the package barrel)
-class DataValidationError     extends Error { errors: ValidationError[] }
 class ResponseGenerationError extends Error {
+  cause?: unknown;           // native `cause` — the original error
   details?: {
     originalError?: unknown;
     params?: Record<string, unknown>;
@@ -53,6 +51,9 @@ class ResponseGenerationError extends Error {
     context?: Record<string, unknown>;
   };
 }
+
+// Internal — match by `error.name` (not exported from the package barrel)
+class DataValidationError     extends Error { errors: ValidationError[] }
 ```
 
 ## Fields
@@ -63,8 +64,8 @@ class ResponseGenerationError extends Error {
 | `ToolCreationError` | A `Tool` fails registration (invalid schema, duplicate id, builder threw). | `toolId`, `cause` | Repair the tool definition. Not user-facing. |
 | `ToolExecutionError` | A handler throws, all retries fail, or `validateInput` cannot correct invalid args. | `toolId`, `executionContext`, `cause` | Surface a user-friendly message; optionally `agent.dispatch({ goTo: '<recovery-flow>' })`. |
 | `DataValidationError` | `agent.respond(...)` collects values that violate the declared `schema`. | `errors: ValidationError[]` | Re-prompt for the offending fields, then retry. |
-| `ResponseGenerationError` | The provider call fails or the response cannot be parsed. | `details.phase`, `details.originalError` | Retry with backoff, fall back to a different provider, or surface a soft failure to the user. |
-| `ProviderError` | A provider call fails terminally — retries and `backupModels` exhausted. Normalized across all vendors. | `code`, `provider`, `cause` (original SDK error) | Match on `code`: backoff for `rate_limited`/`overloaded`, fix credentials for `auth`, fail fast otherwise. Inside a turn it surfaces on `ResponseGenerationError.details.originalError`. |
+| `ResponseGenerationError` | A turn fails for any reason other than a typed error the framework rethrows bare (see `ProviderError` below) — provider call failure, malformed structured output, hook failure. Exported; also carries the original error on the native `.cause`. | `cause`, `details.phase`, `details.originalError` | Retry with backoff, fall back to a different provider, or surface a soft failure to the user. |
+| `ProviderError` | A provider call fails terminally — retries and `backupModels` exhausted. Normalized across all vendors. Propagates **bare** out of `respond()` (`instanceof` survives — no unwrapping needed). Streaming turns surface it wrapped on the final chunk's `error`. | `kind`, `provider`, `status`, `body`, `cause` | Match on `kind`: back off for `rate`/`overload`, top up for `quota`, fix credentials for `auth`, compact for `context`, fail fast otherwise. |
 | `SessionConflictError` | A session save carries a stale `version` — another writer persisted the session after this one loaded it (concurrent `respond()` calls, parallel webhooks, two tabs). | `sessionId`, `expectedVersion`, `actualVersion` | Reload the session and retry the operation, or surface the conflict. |
 | `NotImplementedError` | A reserved option is set to a value this version does not support (e.g. `routerMode: 'embedding'` in v2.0). | `message` | Use a supported value. |
 
@@ -75,6 +76,7 @@ class ResponseGenerationError extends Error {
 ```typescript
 import {
   FlowConfigurationError,
+  ResponseGenerationError,
   ToolExecutionError,
   NotImplementedError,
 } from "@falai/agent";
@@ -93,7 +95,9 @@ try {
   if (err instanceof Error && err.name === "DataValidationError") {
     return "I need you to clarify a few details — let's try that again.";
   }
-  if (err instanceof Error && err.name === "ResponseGenerationError") {
+  if (err instanceof ResponseGenerationError) {
+    // err.cause is the original error — e.g. a provider SDK failure.
+    log.warn({ cause: err.cause, phase: err.details?.phase }, err.message);
     return "I'm having trouble reaching the model. Please retry.";
   }
   throw err;
@@ -102,38 +106,33 @@ try {
 
 ### 2. Matching provider failures by normalized code
 
-Terminal provider failures throw `ProviderError` with a vendor-agnostic `code`. Inside a turn, the agent wraps it in `ResponseGenerationError` — unwrap via `details.originalError`.
+`ProviderError` propagates **bare** out of `respond()` — catch it with `instanceof`, no unwrapping. The original SDK/HTTP error is on `.cause`.
 
 ```typescript
 import { ProviderError } from "@falai/agent";
 
-function asProviderError(err: unknown): ProviderError | undefined {
-  if (err instanceof ProviderError) return err;
-  if (err instanceof Error && err.name === "ResponseGenerationError") {
-    const original = (err as { details?: { originalError?: unknown } }).details?.originalError;
-    if (original instanceof ProviderError) return original;
-  }
-  return undefined;
-}
-
-const providerError = asProviderError(err);
-if (providerError) {
-  switch (providerError.code) {
-    case "rate_limited":
-    case "overloaded":
-      return retryWithBackoff();         // transient — wait and retry
-    case "auth":
-      throw providerError;               // config bug — crash loudly
-    default:
-      log.error({ cause: providerError.cause }, providerError.message);
-      return "I'm having trouble reaching the model. Please retry.";
+try {
+  const response = await agent.respond({ history });
+} catch (err) {
+  if (err instanceof ProviderError) {
+    switch (err.kind) {
+      case "rate":
+      case "overload":
+        return retryWithBackoff();         // transient — wait and retry
+      case "auth":
+        throw err;                          // config bug — crash loudly
+      default:
+        log.error({ cause: err.cause }, err.message);
+        return "I'm having trouble reaching the model. Please retry.";
+    }
   }
+  throw err;
 }
 ```
 
 ### 3. Recovering from a session conflict
 
-`SessionConflictError` means another writer persisted the session between your load and your save. Reload, then retry.
+`SessionConflictError` means another writer persisted the session between your load and your save. Like `ProviderError`, it propagates bare out of `respond()`. Reload, then retry.
 
 ```typescript
 import { SessionConflictError } from "@falai/agent";
@@ -141,8 +140,7 @@ import { SessionConflictError } from "@falai/agent";
 try {
   await agent.respond({ history, session });
 } catch (err) {
-  const original = (err as { details?: { originalError?: unknown } }).details?.originalError;
-  if (err instanceof SessionConflictError || original instanceof SessionConflictError) {
+  if (err instanceof SessionConflictError) {
     const fresh = await agent.session.getOrCreate(sessionId);
     return agent.respond({ history, session: fresh });
   }