@falai/agent 2.6.1 → 2.7.0

package/docs/guides/error-handling.md

@@ -27,13 +27,17 @@ The format applies to framework-thrown errors. If you write a custom tool or hoo
 |-------|-------------|------------|
 | `FlowConfigurationError` | Misconfigured agent: duplicate ids, unknown `collect` keys, malformed `Directive`, branch targets that don't resolve, auto-step cycles, function on `when`. | Don't. Surface in CI. |
 | `DataValidationError` | A user message produces a value that violates the declared `schema`. | Re-prompt the user for the offending fields. |
-| `ToolExecutionError` | A tool handler throws, all retries fail, or `validateInput` cannot correct invalid args. | User-friendly message, optional retry, optional `agent.dispatch` to a recovery flow. |
-| `ResponseGenerationError` | Anything inside the turn fails — provider call, parsing, persistence. Wraps the underlying error in `details.originalError`. | Inspect `details.originalError` first; backoff retry, fall back, or surface a soft failure. |
+| `ToolExecutionError` | The framework's config-driven tools (data enrichment / API call / computation configs) fail after internal retries. A plain handler that throws does **not** throw this — it soft-fails a failure result back to the model instead (see Pattern 3). | User-friendly message, optional retry, optional `agent.dispatch` to a recovery flow. |
+| `ResponseGenerationError` | Anything inside the turn fails — provider call, parsing, persistence. Wraps the underlying error in `details.originalError`, also reachable as the native `err.cause`. | Inspect `.cause` first; backoff retry, fall back, or surface a soft failure. |
 | `ProviderError` | A provider call fails terminally — retries and `backupModels` exhausted. Normalized `code` across all vendors; original SDK error on `cause`. | Match on `code`: backoff for `rate_limited` / `overloaded`, fix credentials for `auth`. |
 | `SessionConflictError` | A session save carries a stale `version` — another writer persisted the session after this one loaded it. | Reload the session and retry the turn. |
 | `NotImplementedError` | A reserved option is set to a value this version does not support (e.g. `routerMode: 'embedding'` in v2.0). | Use a supported value. Same posture as `FlowConfigurationError`. |
 
-`FlowConfigurationError`, `ToolExecutionError`, `ProviderError`, `SessionConflictError`, and `NotImplementedError` are exported from `@falai/agent` and matchable with `instanceof`. `DataValidationError` and `ResponseGenerationError` are internal — match them by `error.name`.
+`FlowConfigurationError`, `ToolExecutionError`, `ProviderError`, `SessionConflictError`, `ResponseGenerationError`, and `NotImplementedError` are exported from `@falai/agent` and matchable with `instanceof`. Only `DataValidationError` is internal — match it by `error.name`.
+
+How errors reach your `catch` depends on the class. `ProviderError` and `SessionConflictError` propagate **bare** out of `respond()` — no wrapping — so you can branch on them directly. Everything else thrown inside a turn arrives wrapped in a `ResponseGenerationError` whose native `.cause` (and `details.originalError`) holds the original. On the streaming path, errors are not thrown at all: they land on the terminal chunk's `error` field, wrapped the same way.
+
+The provider stack classifies every failure as retriable or deterministic before spending budget: rate limits, overload, timeouts, and network faults retry with backoff; auth failures, invalid requests, and caller aborts fail fast because retrying would only repeat the outcome. By the time an error reaches your code, that machinery is exhausted.
 
 One framing that makes recovery simpler: **a failed turn has no effect**. If `respond()` or `stream()` throws mid-turn, the in-memory session is rolled back to its pre-turn snapshot (the user message added by `chat()`/`stream()` before the turn is retained), and persisted state is whatever the previous turn saved. There is no partially mutated session to repair — retrying the turn is always safe.
 
@@ -43,32 +47,35 @@ Wrap every `agent.respond` and `agent.respondStream` call site. Narrow by class,
 
 ```typescript
 import {
-  FlowConfigurationError,
+  ProviderError,
+  SessionConflictError,
   ToolExecutionError,
-  NotImplementedError,
+  ResponseGenerationError,
 } from "@falai/agent";
 
 try {
   const response = await agent.respond({ history, session });
   return response.message;
 } catch (err) {
-  if (err instanceof FlowConfigurationError) throw err;     // bug — bubble up
-  if (err instanceof NotImplementedError) throw err;        // config bug — bubble up
-  if (err instanceof ToolExecutionError) {
-    log.warn({ toolId: err.toolId, cause: err.cause }, err.message);
+  // Typed operational errors propagate bare from respond() — narrow directly.
+  if (err instanceof SessionConflictError) throw err;      // see Pattern 5
+  if (err instanceof ProviderError) throw err;             // see Pattern 4
+
+  // Everything else thrown inside the turn arrives wrapped in a
+  // ResponseGenerationError; unwrap via `.cause` and narrow the original.
+  const cause = err instanceof ResponseGenerationError ? err.cause : err;
+  if (cause instanceof ToolExecutionError) {
+    log.warn({ toolId: cause.toolId }, cause.message);
     return "Sorry — that action failed. Try again in a moment.";
   }
-  if (err instanceof Error && err.name === "DataValidationError") {
+  if (cause instanceof Error && cause.name === "DataValidationError") {
     return "I need a couple of details cleared up — let's try that again.";
   }
-  if (err instanceof Error && err.name === "ResponseGenerationError") {
-    return "I'm having trouble reaching the model. Please retry.";
-  }
   throw err;
 }
 ```
 
-The two unrecoverable classes — `FlowConfigurationError` and `NotImplementedError` — get rethrown so the process crashes loudly. The other three return a graceful message. Anything unexpected falls through to the outer rethrow.
+The two bare classes rethrow to dedicated recovery paths. Wrapped errors narrow through `.cause` — a `ToolExecutionError` gets a soft message, a `DataValidationError` a clarifying question (Pattern 2). Anything unexpected falls through to the outer rethrow. Configuration bugs (`FlowConfigurationError`, `NotImplementedError`) belong in CI, not the request path — see Pattern 6.
 
 ## Pattern 2: DataValidationError → re-prompt
 
@@ -76,8 +83,9 @@ A `DataValidationError` carries an `errors: ValidationError[]` array naming the
 
 ```typescript
 } catch (err) {
-  if (err instanceof Error && err.name === "DataValidationError") {
-    const fields = (err as { errors: { path: string; message: string }[] }).errors
+  const cause = err instanceof ResponseGenerationError ? err.cause : err;
+  if (cause instanceof Error && cause.name === "DataValidationError") {
+    const fields = (cause as { errors: { path: string; message: string }[] }).errors
       .map((e) => `${e.path} (${e.message})`)
       .join(", ");
     return `I couldn't read these from your message: ${fields}. Mind clarifying?`;
@@ -88,15 +96,18 @@ A `DataValidationError` carries an `errors: ValidationError[]` array naming the
 
 The framework does not retry by itself — the next user turn is the retry. Keep `session` alive between turns so the partial collection survives.
 
-## Pattern 3: ToolExecutionError → message, retry, or dispatch
+## Pattern 3: tool failures — soft-fail, then message, retry, or dispatch
 
-Tool failures have three shapes. Pick by what the failing tool was doing.
+First, what does *not* happen: a crashed handler does not crash the turn. When a tool handler throws — or a gate like `checkPermissions` denies the call — the executor catches it and feeds the model a failure result (`{"success": false, "error": "..."}`) as the tool's output. The model sees the failure honestly and can apologize, retry, or route around it; the turn continues. A thrown `ToolExecutionError` reaching your `catch` comes from the framework's config-driven tools (data enrichment, API call, computation configs), not from an ordinary handler.
+
+When you do catch one, three shapes exist. Pick by what the failing tool was doing. In each, unwrap through `.cause` first — config-tool failures surface wrapped, like everything else from inside the turn.
 
 **Soft failure — speak and continue.** A read-only tool that timed out: tell the user, let the conversation move on.
 
 ```typescript
-if (err instanceof ToolExecutionError) {
-  log.warn({ toolId: err.toolId }, err.message);
+const cause = err instanceof ResponseGenerationError ? err.cause : err;
+if (cause instanceof ToolExecutionError) {
+  log.warn({ toolId: cause.toolId }, cause.message);
   return "I couldn't fetch that just now. Want to try again?";
 }
 ```
@@ -108,7 +119,8 @@ for (let attempt = 0; attempt < 2; attempt++) {
   try {
     return (await agent.respond({ history, session })).message;
   } catch (err) {
-    if (err instanceof ToolExecutionError && attempt === 0) {
+    const cause = err instanceof ResponseGenerationError ? err.cause : err;
+    if (cause instanceof ToolExecutionError && attempt === 0) {
       await new Promise((r) => setTimeout(r, 250));
       continue;
     }
@@ -120,8 +132,9 @@ for (let attempt = 0; attempt < 2; attempt++) {
 **Recovery flow.** Hard failures — a payment tool that hit a permanent denial — should redirect into a recovery flow rather than echo the error. Dispatch a directive against the session so the *next* turn enters the recovery flow.
 
 ```typescript
-if (err instanceof ToolExecutionError && err.toolId === "charge_card") {
-  await agent.dispatch(session, { goTo: "PaymentRecovery" });
+const cause = err instanceof ResponseGenerationError ? err.cause : err;
+if (cause instanceof ToolExecutionError && cause.toolId === "charge_card") {
+  await agent.dispatch({ goTo: "PaymentRecovery" }, session);
   return "I hit a snag with that payment. Let me walk you through it.";
 }
 ```
@@ -130,34 +143,23 @@ The dispatched [`Directive`](../reference/directive.md) lands in `session.pendin
 
 ## Pattern 4: ProviderError → match the code, backoff or fallback provider
 
-Terminal provider failures throw `ProviderError` with a normalized `code` (`rate_limited`, `overloaded`, `auth`, `invalid_request`, `schema_rejected`, `timeout`, `network`, `unknown`) — the same shape whether you run Gemini, OpenAI, Anthropic, OpenRouter, or DeepSeek. Inside a turn it arrives wrapped in `ResponseGenerationError`; unwrap via `details.originalError`. Retry with backoff for transient codes; fall back to a second provider only if the primary keeps failing.
+Terminal provider failures throw `ProviderError` with a normalized `code` (`rate_limited`, `overloaded`, `auth`, `invalid_request`, `schema_rejected`, `timeout`, `network`, `unknown`) — the same shape whether you run Gemini, OpenAI, Anthropic, OpenRouter, or DeepSeek. From `respond()` it propagates **bare** — narrow with `instanceof` directly, no unwrapping. On the streaming path it arrives on the terminal chunk's `error`, wrapped in a `ResponseGenerationError` whose `.cause` holds the original.
+
+Before an error ever reaches you, the provider stack has classified it: transient failures (`rate_limited`, `overloaded`, `timeout`, `network`) consumed the retry budget and any `backupModels`; deterministic ones (`auth`, `invalid_request`, caller aborts) failed fast without burning retries. So by catch time, retrying the same call is usually pointless — fall back to a second provider or surface the failure.
 
 ```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;
-}
-
 async function respondWithFallback(history: HistoryItem[], session: Session) {
   for (let attempt = 0; attempt < 3; attempt++) {
     try {
       return await primaryAgent.respond({ history, session });
     } catch (err) {
-      const providerError = asProviderError(err);
-      if (providerError?.code === "auth" || providerError?.code === "invalid_request") {
+      if (!(err instanceof ProviderError)) throw err;
+      if (err.code === "auth" || err.code === "invalid_request") {
         throw err; // config bug — retrying won't help
       }
-      if (providerError) {
-        await new Promise((r) => setTimeout(r, 200 * 2 ** attempt));
-        continue;
-      }
-      throw err;
+      await new Promise((r) => setTimeout(r, 200 * 2 ** attempt));
     }
   }
   return fallbackAgent.respond({ history, session });
@@ -173,13 +175,12 @@ With a durable adapter, every save is a compare-and-swap on the session's `versi
 The error names `sessionId`, `expectedVersion`, and `actualVersion`. The recovery is mechanical: reload the session, retry the turn. The failed turn rolled back, so there is nothing to clean up.
 
 ```typescript
-import { SessionConflictError } from "@falai/agent";
+import { ResponseGenerationError, SessionConflictError } from "@falai/agent";
 
 function isSessionConflict(err: unknown): boolean {
-  if (err instanceof SessionConflictError) return true;
-  if (err instanceof Error && err.name === "ResponseGenerationError") {
-    const original = (err as { details?: { originalError?: unknown } }).details?.originalError;
-    return original instanceof SessionConflictError;
+  if (err instanceof SessionConflictError) return true; // bare from respond()
+  if (err instanceof ResponseGenerationError) {
+    return err.cause instanceof SessionConflictError; // wrapped on the stream path
   }
   return false;
 }

package/docs/guides/flow-control.md

@@ -351,7 +351,14 @@ await agent.dispatch({ goTo: "Billing", reply: "Transferring you now." }, sessio
 The call validates the directive (`flow.validate`), confirms any
 `goTo`-named flow exists (throws `FlowConfigurationError` if not),
 strips pre-LLM-only fields, writes `pendingDirective` onto the
-session, and persists if an adapter is configured.
+session, and returns the updated session. With a persistence adapter
+configured (and `autoSave` on — the default), dispatch also persists
+immediately, so a webhook's redirect survives even if the next turn
+runs in a different process; the save compare-and-swaps on the session
+version, so a stale copy throws `SessionConflictError` rather than
+clobbering another writer. Without an adapter (or with
+`autoSave: false`) the directive is memory-only until the next turn's
+auto-save — persisting sooner is then the caller's job.
 
 `pendingDirective` is **single-shot** — consumed exactly once and
 cleared. Calling `dispatch` again before the next turn overwrites the

package/docs/guides/instructions.md

@@ -98,7 +98,9 @@ The format is fixed. The kind prefix is always present (defaulting to `[should]`
 Every `respond()` call returns an `appliedInstructions` array listing exactly which instructions were rendered into that turn's prompt. The set is deterministic — it comes from the prompt composer, not the model — so you can use it for observability, audits, and tests. For an instruction with `when`, inclusion means the conditional instruction reached the model; it does not claim that the model judged the condition true:
 
 ```typescript
-const response = await agent.respond("I want to book a room.");
+const response = await agent.respond({
+  history: [{ role: "user", content: "I want to book a room." }],
+});
 
 for (const a of response.appliedInstructions ?? []) {
   console.log(`${a.scope}${a.scopeRef ? `:${a.scopeRef}` : ""} → ${a.id}`);
@@ -113,7 +115,9 @@ Each `AppliedInstruction` carries the firing instruction's `id`, the originating
 The same array lands on the final chunk of `respondStream`:
 
 ```typescript
-for await (const chunk of agent.respondStream("I want to book a room.")) {
+for await (const chunk of agent.respondStream({
+  history: [{ role: "user", content: "I want to book a room." }],
+})) {
   if (chunk.done) {
     console.log("rendered:", chunk.appliedInstructions);
   }
@@ -189,11 +193,16 @@ Because the set is deterministic, you can assert against it directly:
 ```typescript
 import { test, expect } from "bun:test";
 
+// Seed the condition state at construction — `initialData` pre-populates
+// session.data before the first turn.
+const agent = createAgent({
+  /* ...same scaffold, with the payment step configured as above... */
+  initialData: { lastChargeStatus: "declined" },
+});
+
 test("payment step renders the no-retry rule when the card was declined", async () => {
-  const response = await agent.respond("Try again.", {
-    sessionId: "s_1",
-    initialContext: {},
-    initialData: { lastChargeStatus: "declined" },
+  const response = await agent.respond({
+    history: [{ role: "user", content: "Try again." }],
   });
 
   const ids = response.appliedInstructions?.map(a => a.id) ?? [];

package/docs/guides/persistence.md

@@ -120,6 +120,14 @@ const response = await agent.respond({
 
 `getOrCreate` returns the stored `SessionState` (collected data, flow position, `pendingDirective`, signals state) — or creates a fresh session with that id if nothing exists yet. Unknown ids are not an error path; they are the start of a new conversation pinned to that id.
 
+If you load a persisted session blob yourself — a custom cache, a queue payload, a row fetched outside the adapter's normal path — pass it through [`restoreSession`](../reference/adapters.md) instead of hand-shaping a `SessionState`. It is the named inverse of `createPersistedState`: it takes the persisted slice and returns a fully-shaped `SessionState`, including a completed-flow blob whose collected state must survive the round trip.
+
+```typescript
+import { restoreSession } from "@falai/agent";
+
+const session = restoreSession(await myCache.get(sessionId));
+```
+
 A practical id shape: `<userId>:<threadId>`. Keep it stable across restarts and replicas. The adapter does the rest.
 
 ## Recipe 3: Redis for fast, ephemeral sessions
@@ -162,13 +170,12 @@ If you need an archive of every session and message (audit logs, search, analyti
 Once sessions span processes, two writers can race on one id — parallel webhooks, a double-send from a chat widget, two browser tabs. Every save is a compare-and-swap on the session's `version` (incremented on each save): the loser's save throws `SessionConflictError` instead of silently overwriting the winner's state. The error carries `sessionId`, `expectedVersion`, and `actualVersion`; the recovery is mechanical — reload, retry.
 
 ```typescript
-import { SessionConflictError } from "@falai/agent";
+import { ResponseGenerationError, SessionConflictError } from "@falai/agent";
 
 function isSessionConflict(err: unknown): boolean {
-  if (err instanceof SessionConflictError) return true;
-  if (err instanceof Error && err.name === "ResponseGenerationError") {
-    const original = (err as { details?: { originalError?: unknown } }).details?.originalError;
-    return original instanceof SessionConflictError;
+  if (err instanceof SessionConflictError) return true; // bare from respond()
+  if (err instanceof ResponseGenerationError) {
+    return err.cause instanceof SessionConflictError; // wrapped on the stream path
   }
   return false;
 }

package/docs/guides/streaming.md

@@ -136,4 +136,14 @@ For a Stop button, store the `controller` reference for the active stream on the
 
 If the turn fails — the generator surfaces an error chunk — it has no lasting effect: the in-memory session rolls back to its pre-turn snapshot (the user message added by `stream()` before the turn is retained), and persisted state is whatever the previous turn saved. Retrying is always safe.
 
+## Reliability: retries, backups, and the first-chunk deadline
+
+Streaming inherits the same resilience machinery as non-streaming calls — provider `retryConfig` and `backupModels` — with stream-specific rules:
+
+- **Retry only before the first chunk.** A stream that fails before yielding anything (a connection error, an empty completion, a stalled open) is retried on the same model up to `retryConfig.retries` times. Once a delta has reached your renderer, the stream is committed: any later failure propagates instead of retrying, so a retry can never emit a token your consumer has already seen.
+- **First-chunk deadline.** `retryConfig.timeout` doubles as the time-to-first-token budget. If the provider opens a stream but produces no first chunk within it, the attempt counts as failed and the retry and backup machinery takes over. Only the first chunk is bounded — later chunks are unbounded, so a long-but-healthy stream is never cut off.
+- **Transparent backup-model switch.** With `backupModels` configured, a model that fails mid-stream — even after deltas were delivered — falls through to the next model, whose chunks flow through unchanged. The switchover happens between chunks; no error reaches the consumer unless every model fails.
+
+These knobs live on the provider constructor, not on `respondStream` — see [Providers](../reference/providers.md) for `retryConfig` and `backupModels`.
+
 **Next:** [Errors](./error-handling.md)

package/docs/migration/README.md

@@ -7,6 +7,10 @@ order: 99
 
 # Migration
 
+Upgrading from `2.6.x`? The v2.7 guide covers the consumer-fit release surface — `message`/`allowedFlows` turn parameters, `endedFlows` and `metadata.tokensUsed`, provider `client` injection, and the exported `restoreSession` — plus the behavior changes to know: the default 400-message history bound, finalize-before-persist ordering, soft-failing tools, bare typed-error propagation, and session load failures that now throw.
+
+[Read the v2.6 → v2.7 migration guide](./v2-6-to-v2-7.md)
+
 Upgrading from `2.3.x`? The v2.4 guide covers the concurrency-safety and provider-layer changes — required `AiProvider.capabilities`, normalized `ProviderError`, optimistic session locking with `SessionConflictError`, the `unknown` generic defaults, and the internals removed from the public barrel — with before/after code and per-adapter notes.
 
 [Read the v2.3 → v2.4 migration guide](./v2-3-to-v2-4.md)

package/docs/migration/v2-3-to-v2-4.md

@@ -109,6 +109,8 @@ try {
 ```
 
 > **Note:** when the failure surfaces through `agent.respond(...)`, it is wrapped in `ResponseGenerationError` like every other turn failure — the `ProviderError` is then on `details.originalError`. Code calling a provider directly sees the `ProviderError` itself.
+>
+> **v2.7 update:** this wrapping no longer happens — `ProviderError` now propagates **bare** out of `respond()` (`instanceof` survives). See the [v2.6 → v2.7 guide](./v2-6-to-v2-7.md#7-errors-propagate-typed-and-bare).
 
 ---
 
@@ -144,6 +146,8 @@ try {
 
 `SessionConflictError` carries `sessionId`, `expectedVersion`, and `actualVersion`. Recommended handling: reload the session, retry the operation.
 
+> **v2.7 update:** the unwrapping fallback below is no longer needed — `SessionConflictError` (like `ProviderError`) now propagates bare out of `respond()`. The direct `instanceof` check is sufficient. See the [v2.6 → v2.7 guide](./v2-6-to-v2-7.md#7-errors-propagate-typed-and-bare).
+
 ### What you need to migrate, per adapter
 
 | Adapter | Action |

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.