@falai/agent 2.2.4 → 2.4.2

package/docs/guides/persistence.md

@@ -9,7 +9,7 @@ order: 5
 
 By default, `createAgent` runs against an in-process `MemoryAdapter`. That is the right choice while you are building — zero setup, instant resets between tests — but it forgets every conversation the moment the process exits. Production needs storage that outlives a deploy, scales to multiple replicas, and lets a session resume by id from any machine.
 
-This guide covers the swap. You will pick an adapter, wire it through `persistence`, resume sessions by `sessionId`, and run the v1 → v2 schema migration if you are upgrading an existing store.
+This guide covers the swap. You will pick an adapter, wire it through `persistence`, resume sessions by `sessionId`, handle concurrent writers with optimistic locking, version your session schema, and run the v1 → v2 schema migration if you are upgrading an existing store.
 
 ## The seven adapters
 
@@ -39,7 +39,7 @@ bun add -d prisma
 bunx prisma init
 ```
 
-**2. Declare the session model.** Two columns matter most: `pendingDirective` and `signals`. The agent serializes its [`Directive`](../reference/directive.md) and signals state into them at the end of every turn and reads them back at the start of the next. Both are required on every adapter's session schema in v2.
+**2. Declare the session model.** Two columns matter most: `pendingDirective` and `signals`. The agent serializes its [`Directive`](../reference/directive.md) and signals state into them at the end of every turn and reads them back at the start of the next. Both are required on every adapter's session schema in v2. The `version` column is optional but recommended — it enables [optimistic locking](#concurrent-writers-optimistic-locking); without it the adapter degrades gracefully and locking stays inactive.
 
 ```prisma
 model AgentSession {
@@ -51,6 +51,7 @@ model AgentSession {
   collectedData     Json?
   pendingDirective  Json?
   signals           Json?
+  version           Int?
   messageCount      Int       @default(0)
   lastMessageAt     DateTime?
   completedAt       DateTime?
@@ -156,6 +157,72 @@ A few things worth noting:
 
 If you need an archive of every session and message (audit logs, search, analytics), pair Redis with a second adapter on a slower path, or pick a durable adapter from the table above directly.
 
+## Concurrent writers: optimistic locking
+
+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";
+
+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;
+  }
+  return false;
+}
+
+try {
+  return await agent.respond({ history, session });
+} catch (err) {
+  if (isSessionConflict(err)) {
+    const fresh = await agent.session.getOrCreate(sessionId); // reload the winning state
+    return agent.respond({ history, session: fresh });
+  }
+  throw err;
+}
+```
+
+Three things you do **not** have to worry about:
+
+- **Same-process concurrency.** Concurrent saves of one session from a single process are serialized through a per-session queue — they never conflict with each other. Conflicts only fire between genuinely independent copies (two processes, or two separately loaded sessions).
+- **Existing rows.** Sessions written by pre-2.4 versions have no stored `version` and are accepted without conflict; the first save stamps them. Memory, Mongo, Redis, and OpenSearch need no schema change at all, and the SQLite/PostgreSQL adapters auto-add the `version` column in `initialize()`.
+- **Opting out.** Prisma users who skip the `version Int?` column simply run without locking — the adapter detects the missing column and degrades gracefully.
+
+The per-adapter storage details live in [persistence adapters](../reference/adapters.md#optimistic-locking); the retry pattern is also covered in [Errors](./error-handling.md).
+
+## Schema versioning: migrate old sessions on load
+
+The locking `version` guards *who* writes; `schemaVersion` guards *what shape* they write. When you rename a schema field or restructure collected data, sessions persisted by the previous deploy still carry the old shape. Declare a `schemaVersion` and a `migrateSession` function, and the agent upgrades stale state at load time:
+
+```typescript
+const agent = createAgent({
+  schema, provider, flows,
+  persistence: {
+    adapter,
+    schemaVersion: 2,
+    migrateSession: (collected, fromVersion) => {
+      // v1 stored `destination`; v2 renamed it to `city`
+      if ((fromVersion ?? 1) < 2) {
+        const { destination, ...rest } = collected.data as { destination?: string };
+        return { ...collected, data: { ...rest, city: destination } };
+      }
+      return collected;
+    },
+  },
+});
+```
+
+How it behaves:
+
+- Every save stamps the configured `schemaVersion` onto the persisted state.
+- On load, when the stored version differs from the configured one (or is missing — pre-versioning rows pass `fromVersion: undefined`), `migrateSession` runs and its return value is used for the turn. The new stamp persists on the next save.
+- The migrator may be async, and must return state valid for the current `schemaVersion`.
+- With a version mismatch but **no** `migrateSession`, the agent logs a warning and loads the state as-is.
+
+Bump `schemaVersion` with every breaking change to your collected-data shape and keep the migrator's old-version branches around — a long-idle session might skip several versions and arrive with any historical `fromVersion`.
+
 ## Schema migration: v1 → v2
 
 If you are upgrading an existing v1 store, the session schema needs two new columns before v2 runs against it:

package/docs/guides/streaming.md

@@ -134,4 +134,6 @@ When the signal aborts, the loop exits cleanly — no exception is thrown by the
 
 For a Stop button, store the `controller` reference for the active stream on the UI side and call `controller.abort()` from the click handler. For server-side hard ceilings, wrap `respondStream` with an `AbortController` whose `setTimeout` fires at your SLO budget.
 
+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.
+
 **Next:** [Errors](./error-handling.md)

package/docs/migration/README.md

@@ -1,12 +1,16 @@
 ---
 title: "Migration"
-description: "Migration guides for upgrading @falai/agent from v1 to v2."
+description: "Migration guides for upgrading @falai/agent between major and minor versions."
 type: overview
 order: 99
 ---
 
 # Migration
 
+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)
+
 Upgrading from `1.x`? The consolidated migration guide covers every breaking change in v2 — including the Route → Flow rename, the Instruction unification, the Tool merge, and the Directive collapse — with rename tables, per-adapter schema migrations, and before/after code for each section.
 
 [Read the v1 → v2 migration guide](./v1-to-v2.md)

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

@@ -0,0 +1,316 @@
+---
+title: "v2.3 → v2.4 migration"
+description: "Every breaking change in v2.4 with before/after code: provider capabilities, ProviderError, optimistic session locking, and the unknown generic defaults."
+type: migration
+order: 2
+---
+
+# v2.3 → v2.4 Migration
+
+**Version:** 2.4.0 — Architecture hardening (concurrency safety, consolidated provider layer, stricter types)
+
+## Summary
+
+v2.4 hardens three surfaces. Sessions gain optimistic locking (`version` + `SessionConflictError`) and user-defined schema versioning (`schemaVersion` + `migrateSession`). The provider layer is consolidated: every `AiProvider` must declare `capabilities`, terminal failures are normalized into `ProviderError`, and the new `OpenAICompatibleProvider` base class is exported. The type surface tightens: generic defaults move from `any` to `unknown`, and a handful of internals leave the public barrel.
+
+If you only use the built-in providers and adapters, the upgrade is usually zero-code: the new `version` column is added automatically (SQLite/PostgreSQL) or needs no schema at all (Memory, Mongo, Redis, OpenSearch), and pre-2.4 rows are accepted without conflict. The sections below cover the cases that do need a change.
+
+---
+
+## Table of Contents
+
+1. [Custom providers must declare `capabilities`](#1-custom-providers-must-declare-capabilities)
+2. [Provider terminal errors are now `ProviderError`](#2-provider-terminal-errors-are-now-providererror)
+3. [Optimistic session locking](#3-optimistic-session-locking)
+4. [Custom `SessionRepository`: `update()` gains `expectedVersion`](#4-custom-sessionrepository-update-gains-expectedversion)
+5. [Generic defaults: `any` → `unknown`](#5-generic-defaults-any--unknown)
+6. [`SignalFiring.directive` is now `ResolvedSignalDirective`](#6-signalfiringdirective-is-now-resolvedsignaldirective)
+7. [Removed from the public barrel](#7-removed-from-the-public-barrel)
+8. [`ResponsePipeline` stored-state API removed](#8-responsepipeline-stored-state-api-removed)
+9. [Behavioral changes to be aware of](#9-behavioral-changes-to-be-aware-of)
+10. [Verification](#verification)
+
+---
+
+## 1. Custom providers must declare `capabilities`
+
+`AiProvider.capabilities: ProviderCapabilities` is now a **required** member. Every custom provider must declare its five static capability flags; the built-ins already do.
+
+```typescript
+import type { AiProvider, ProviderCapabilities } from "@falai/agent";
+
+class MyProvider implements AiProvider {
+  readonly name = "my-provider";
+
+  // New in v2.4 — required
+  readonly capabilities: ProviderCapabilities = {
+    supportsTools: true,
+    supportsNativeJsonSchema: true,
+    supportsStreaming: true,
+    supportsStreamingToolCalls: true,
+    supportsPromptCaching: false,
+  };
+
+  // generateMessage / generateMessageStream as before
+}
+```
+
+If your provider wraps an OpenAI-compatible API (Groq, Together, Fireworks, …), consider subclassing the new exported [`OpenAICompatibleProvider`](../reference/providers.md#building-a-custom-openai-compatible-provider) base class instead of implementing `AiProvider` from scratch — it supplies message building, tool-call parsing, streaming, retries, backup models, and error normalization.
+
+The capability values for the five built-in providers are documented in the [providers reference](../reference/providers.md#capabilities).
+
+---
+
+## 2. Provider terminal errors are now `ProviderError`
+
+Terminal provider failures — i.e. after retries and backup models (if any) are exhausted — now throw `ProviderError` (exported) with a normalized `code` instead of rethrowing the raw SDK error. The original SDK/HTTP error is preserved as `cause`.
+
+```typescript
+type ProviderErrorCode =
+  | 'rate_limited'
+  | 'overloaded'
+  | 'auth'
+  | 'invalid_request'
+  | 'schema_rejected'
+  | 'timeout'
+  | 'network'
+  | 'unknown';
+
+class ProviderError extends Error {
+  readonly code: ProviderErrorCode;
+  readonly provider: string;   // e.g. "openai"
+  readonly cause?: unknown;    // original SDK error
+}
+```
+
+### Before / After
+
+```typescript
+// ─── v2.3: match on raw SDK error shapes ───
+try {
+  await agent.respond(message);
+} catch (err) {
+  if ((err as { status?: number }).status === 429) { /* rate limited */ }
+}
+
+// ─── v2.4: match on the normalized code ───
+import { ProviderError } from "@falai/agent";
+
+try {
+  await agent.respond(message);
+} catch (err) {
+  if (err instanceof ProviderError) {
+    if (err.code === "rate_limited" || err.code === "overloaded") {
+      // backoff and retry
+    }
+    console.error(err.provider, err.code, err.cause); // original SDK error on cause
+  }
+}
+```
+
+> **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.
+
+---
+
+## 3. Optimistic session locking
+
+`SessionState` / `SessionData` carry a `version` number, incremented on every save. A save with a stale version — another writer persisted the session after this one loaded it (concurrent `respond()` calls, parallel webhooks, two tabs) — throws the new `SessionConflictError` instead of silently overwriting state.
+
+```typescript
+import { SessionConflictError } from "@falai/agent";
+
+function isSessionConflict(err: unknown): boolean {
+  if (err instanceof SessionConflictError) return true;
+  // respond() wraps turn failures in ResponseGenerationError —
+  // the conflict is then on details.originalError
+  if (err instanceof Error && err.name === "ResponseGenerationError") {
+    const details = (err as { details?: { originalError?: unknown } }).details;
+    return details?.originalError instanceof SessionConflictError;
+  }
+  return false;
+}
+
+try {
+  await agent.respond({ history, session });
+} catch (err) {
+  if (isSessionConflict(err)) {
+    // Reload the session and retry — another writer won the race.
+    const fresh = await agent.session.getOrCreate(sessionId);
+    return agent.respond({ history, session: fresh });
+  }
+  throw err;
+}
+```
+
+`SessionConflictError` carries `sessionId`, `expectedVersion`, and `actualVersion`. Recommended handling: reload the session, retry the operation.
+
+### What you need to migrate, per adapter
+
+| Adapter | Action |
+|---------|--------|
+| `MemoryAdapter` | Nothing. |
+| `MongoAdapter` | Nothing — documents gain `version` on next save. |
+| `RedisAdapter` | Nothing — `version` rides inside the JSON value. |
+| `OpenSearchAdapter` | Nothing — `version` is a document field. |
+| `SQLiteAdapter` | Nothing — `initialize()` auto-adds the `version` column. |
+| `PostgreSQLAdapter` | Nothing — `initialize()` auto-adds the `version` column. |
+| `PrismaAdapter` | Add `version Int?` to your session model (see below). |
+
+Rows written by pre-2.4 versions have no stored `version` and are **accepted without conflict** — there is no backfill to run. The first v2.4 save stamps them.
+
+### Prisma
+
+```diff
+model AgentSession {
+  id                String    @id
+  // ...
+  pendingDirective  Json?
+  signals           Json?
++ version           Int?
+}
+```
+
+Run `npx prisma migrate dev --name v2-4-session-version`. Without the column, the adapter detects its absence on the first write and degrades gracefully — everything works, but optimistic locking stays **inactive** until you add it.
+
+### Same-process concurrency
+
+Concurrent saves of one session from the same process are serialized through a per-session queue and never conflict with each other. `SessionConflictError` only fires for genuinely independent copies — two processes, or two separately loaded sessions.
+
+---
+
+## 4. Custom `SessionRepository`: `update()` gains `expectedVersion`
+
+The `SessionRepository.update()` signature gained an optional third parameter:
+
+```typescript
+// ─── v2.3 ───
+update(id: string, data: Partial<...>): Promise<SessionData<TData> | null>;
+
+// ─── v2.4 ───
+update(
+  id: string,
+  data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>,
+  options?: { expectedVersion?: number }  // SessionUpdateOptions
+): Promise<SessionData<TData> | null>;
+```
+
+Two valid implementations:
+
+- **Compare-and-swap (recommended).** When `options.expectedVersion` is provided, throw `SessionConflictError` if the stored `version` differs (rows with no stored version are accepted), and increment `version` by one on every successful update. See `MemoryAdapter` for the reference implementation.
+- **Ignore it.** Don't read `options` at all — your store simply opts out of optimistic locking, exactly like pre-2.4 behavior.
+
+---
+
+## 5. Generic defaults: `any` → `unknown`
+
+The default type parameters on `Agent`, `Tool`, `ToolContext`, `ToolResult`, and `ToolHandler` changed from `any` to `unknown`. `ToolHistoryItem.content` is also `unknown` (was `any`).
+
+Typed code is unaffected — if you pass explicit generics or let inference flow from `schema`, nothing changes. Untyped tool code that relied on implicit `any` may now need explicit type parameters or a type guard:
+
+```typescript
+// ─── v2.3: compiled because TData defaulted to any ───
+const tool: Tool = {
+  id: "lookup",
+  handler: async (ctx) => {
+    return ctx.data.orderId.trim(); // ctx.data was any
+  },
+};
+
+// ─── v2.4: declare the generics… ───
+const tool: Tool<MyContext, MyData> = {
+  id: "lookup",
+  handler: async (ctx) => {
+    return ctx.data.orderId?.trim();
+  },
+};
+
+// ─── …or narrow the unknown ───
+handler: async (ctx) => {
+  const data = ctx.data as Partial<MyData>;
+  return data.orderId?.trim();
+},
+```
+
+---
+
+## 6. `SignalFiring.directive` is now `ResolvedSignalDirective`
+
+`SignalFiring.directive` was typed `SignalDirective`; it is now `ResolvedSignalDirective` (exported). The difference: `replyWith` has already been resolved onto `reply` and stripped by the time a firing reaches the response surface — which was already the runtime behavior; the type now says so.
+
+```typescript
+// ─── v2.3 ───
+for (const firing of response.triggeredSignals ?? []) {
+  firing.directive?.replyWith; // typed as present, never was at runtime
+}
+
+// ─── v2.4 ───
+for (const firing of response.triggeredSignals ?? []) {
+  firing.directive?.reply;     // resolved reply text, if any
+}
+```
+
+---
+
+## 7. Removed from the public barrel
+
+These internals are no longer exported. They locked the architecture into semver and had no supported external use:
+
+| Removed export | Kind | Replacement |
+|---|---|---|
+| `DirectiveChainTracker` | class | Internal — remove direct imports. |
+| `DirectiveChainEntry` | type | Internal — remove direct imports. |
+| `StreamingToolExecutor` | class | Internal — remove direct imports. |
+
+If you imported any of these, the conversation-control surface you want is `Directive`, `agent.dispatch()`, and the documented hooks.
+
+---
+
+## 8. `ResponsePipeline` stored-state API removed
+
+`ResponsePipeline` (internal, but reachable in v2.3 via subclassing tricks) no longer holds mutable turn state. Removed:
+
+- `setContext()` / `setCurrentSession()` / `getStoredContext()` / `getCurrentSession()`
+- `updateDataFlow()`
+
+Context and session are now passed explicitly through the pipeline; `determineNextStep` takes a required `context` parameter. If you depended on these, pass state explicitly instead of reading it back from the pipeline.
+
+---
+
+## 9. Behavioral changes to be aware of
+
+Not breaking in the type sense, but observable at runtime:
+
+- **`session.data` is the single source of truth for collected data.** The bidirectional sync between the Agent's internal copy and the session is gone. `agent.getCollectedData()` / `agent.getData()` read from the live session; `agent.updateCollectedData()` writes into it. Data set before any session exists (including `initialData`) is staged and seeds the first created session; loading an existing session discards staged data in favor of the stored state.
+- **Passing an explicit `session` to `respond()` no longer merges the managed session's data into it.** That was cross-session state leakage; sessions you pass in are now used as-is.
+- **Failed-turn rollback.** If `respond()` / `stream()` throws mid-turn, the in-memory session is restored to its pre-turn snapshot (the user message added by `chat()` / `stream()` before the turn is retained). Persisted state is from the previous turn — a failed turn no longer leaves a partially mutated session.
+- **Deterministic compaction.** When `compaction` is configured, it now runs at end-of-turn finalize on every `respond()` / `chat()` / `stream()`. Previously it only ran inside `session.addMessage()`, so respond-only integrations grew history unboundedly.
+
+---
+
+## Verification
+
+After migrating, confirm no legacy references remain. Run from your repo root:
+
+```bash
+rg -n '\b(DirectiveChainTracker|DirectiveChainEntry|StreamingToolExecutor|updateDataFlow|getStoredContext)\b' \
+  --glob '**/*.ts' \
+  --glob '!node_modules/**' \
+  --glob '!dist/**'
+```
+
+Expected output: **zero matches**. Then run the type checker — it will flag missing `capabilities` on custom providers, the new `update()` signature on custom repositories, and any implicit-`any` tool code:
+
+```bash
+npx tsc --noEmit
+# or
+bun run typecheck
+```
+
+For Prisma users: confirm the `version Int?` column exists if you want locking active.
+
+## Cross-References
+
+- [CHANGELOG](../../CHANGELOG.md) — full v2.4 release notes
+- [Persistence](../guides/persistence.md) — locking and schema-versioning recipes
+- [Providers](../reference/providers.md) — capabilities matrix and `OpenAICompatibleProvider`
+- [Errors](../reference/errors.md) — `ProviderError` and `SessionConflictError`

package/docs/reference/adapters.md

@@ -37,8 +37,13 @@ interface PersistenceAdapter<TData> {
 
 interface PersistenceConfig<TData> {
   adapter: PersistenceAdapter<TData>;
-  autoSave?: boolean;   // default: true
-  userId?: string;      // attached to created sessions/messages
+  autoSave?: boolean;       // default: true
+  userId?: string;          // attached to created sessions/messages
+  schemaVersion?: number;   // stamps persisted state; see "Schema versioning"
+  migrateSession?: (       // upgrades state written under an older schemaVersion
+    collectedData: CollectedStateData<TData>,
+    fromVersion: number | undefined
+  ) => CollectedStateData<TData> | Promise<CollectedStateData<TData>>;
 }
 ```
 
@@ -46,6 +51,8 @@ The `SessionRepository` write methods accept a `CollectedStateData` payload that
 
 ```typescript
 interface CollectedStateData<TData> {
+  /** User-defined schema version of the agent that wrote this state. */
+  schemaVersion?: number;
   data: Partial<TData>;
   flowHistory: SessionState<TData>["flowHistory"];
   history?: SessionState<TData>["history"];
@@ -64,6 +71,43 @@ Two columns deserve special attention:
 
 Both are **required columns** on every adapter's session schema. v1 schemas had a `pending_transition` column instead; v2 replaces it. See the per-adapter migration notes below and the consolidated [v1 → v2 migration](../migration/v1-to-v2.md).
 
+## 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:
+
+```typescript
+interface SessionUpdateOptions {
+  /** Reject the update with SessionConflictError if the stored `version` differs. */
+  expectedVersion?: number;
+}
+
+update(
+  id: string,
+  data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>,
+  options?: SessionUpdateOptions
+): Promise<SessionData<TData> | null>;
+```
+
+When the agent saves a session and another writer bumped the stored `version` since this copy was loaded (concurrent `respond()` calls from two processes, parallel webhooks, two tabs), the save throws the exported [`SessionConflictError`](./errors.md) — carrying `sessionId`, `expectedVersion`, and `actualVersion` — instead of silently overwriting the winner's state. Recommended handling: reload the session and retry. Same-process concurrent saves of one session are serialized through a per-session queue and never conflict with each other.
+
+What each adapter needs:
+
+| Adapter | `version` storage | Migration from pre-2.4 |
+|---------|-------------------|------------------------|
+| `MemoryAdapter` | in-memory field | None. |
+| `MongoAdapter` | document field | None — added on next save. |
+| `RedisAdapter` | inside the JSON value | None. |
+| `OpenSearchAdapter` | document field | None. |
+| `SQLiteAdapter` | `version INTEGER` column | None — `initialize()` auto-adds the column. |
+| `PostgreSQLAdapter` | `version INTEGER` column | None — `initialize()` auto-adds the column. |
+| `PrismaAdapter` | your model's `version Int?` | Add `version Int?` to your session model. Without it the adapter detects the missing column and degrades gracefully — locking stays inactive. |
+
+Rows written by pre-2.4 versions have no stored `version` and are **accepted without conflict**; the first v2.4 save stamps them. If you implement a custom `SessionRepository`, honor `options.expectedVersion` as a compare-and-swap (see `MemoryAdapter` for the reference implementation) or ignore the parameter to opt out of locking.
+
+## Schema versioning
+
+Independent of the locking `version`, `CollectedStateData.schemaVersion` tracks the **user-defined shape** of your persisted state. Configure `persistence.schemaVersion` and the agent stamps it on every save; on load, a session written under a different (or missing) version is passed through `persistence.migrateSession` before use. See the [persistence guide](../guides/persistence.md#schema-versioning-migrate-old-sessions-on-load) for the recipe.
+
 ### Wiring with `sessionId`
 
 Pass `sessionId` to the agent constructor or directly to a `respond` call to resume a conversation by id:
@@ -148,7 +192,7 @@ interface PrismaAdapterOptions {
 
 ### Schema requirements
 
-Your `Session` model must declare `pendingDirective` and `signals` JSON columns alongside the standard fields:
+Your `Session` model must declare `pendingDirective` and `signals` JSON columns alongside the standard fields. Add `version Int?` to enable [optimistic locking](#optimistic-locking):
 
 ```prisma
 model AgentSession {
@@ -161,6 +205,7 @@ model AgentSession {
   collectedData     Json?
   pendingDirective  Json?
   signals           Json?
+  version           Int?
   messageCount      Int       @default(0)
   lastMessageAt     DateTime?
   completedAt       DateTime?
@@ -169,7 +214,7 @@ model AgentSession {
 }
 ```
 
-If your existing schema lacks these columns, see [v1 → v2 migration](../migration/v1-to-v2.md) for the column rename and DDL.
+`version` is optional — the adapter detects a missing column on the first write and degrades gracefully, leaving locking inactive. The other columns are required; if your existing schema lacks them, see [v1 → v2 migration](../migration/v1-to-v2.md) for the column rename and DDL.
 
 ### Examples
 
@@ -318,7 +363,7 @@ interface PostgreSQLAdapterOptions {
 
 ### Schema requirements
 
-`initialize()` creates tables with the v2 columns. Migrating from v1:
+`initialize()` creates tables with the v2 columns and auto-adds the `version` column to tables created by pre-2.4 versions — no manual DDL for the locking upgrade. Migrating from v1:
 
 ```sql
 ALTER TABLE agent_sessions DROP COLUMN IF EXISTS pending_transition;
@@ -369,7 +414,7 @@ interface SQLiteAdapterOptions {
 
 ### Schema requirements
 
-`initialize()` creates the v2 tables. Migrating from v1 (SQLite 3.35+):
+`initialize()` creates the v2 tables and auto-adds the `version` column to tables created by pre-2.4 versions — no manual DDL for the locking upgrade. Migrating from v1 (SQLite 3.35+):
 
 ```sql
 ALTER TABLE agent_sessions DROP COLUMN pending_transition;
@@ -462,10 +507,11 @@ const agent = createAgent({
 
 ## Errors
 
-Adapter errors propagate from the underlying driver — the agent does not wrap them. Your `try`/`catch` sees the native vendor error (e.g., `PrismaClientKnownRequestError`, `MongoServerError`, `ioredis.ReplyError`).
+Adapter errors propagate from the underlying driver — the agent does not wrap them. Your `try`/`catch` sees the native vendor error (e.g., `PrismaClientKnownRequestError`, `MongoServerError`, `ioredis.ReplyError`). The one framework-owned exception is `SessionConflictError`.
 
 | When | Error | Why |
 |------|-------|-----|
+| A save carries a stale `version` — a concurrent writer persisted the session first | `SessionConflictError` (exported) | Reload the session and retry. See [Optimistic locking](#optimistic-locking). |
 | `pendingDirective` or `signals` column missing on a v1 schema | Driver-specific column-not-found error | Run the v2 migration shown above for your adapter. |
 | `findById` returns `null` for a `sessionId` you passed to `createAgent` | None — a new session is created with that id | Treat unknown ids as "first turn." |
 | `initialize()` not called on Postgres / SQLite / OpenSearch | Driver-specific table/index-not-found error on first write | Call `await adapter.initialize()` once on boot, or run the equivalent DDL yourself. |
@@ -478,4 +524,6 @@ Adapter errors propagate from the underlying driver — the agent does not wrap
 - [createAgent](./create-agent.md) — the `persistence` and `sessionId` fields
 - [Directive](./directive.md) — what `pendingDirective` stores
 - [Signals](./signals.md) — what the `signals` column stores
+- [Errors](./errors.md) — `SessionConflictError` fields and recovery
 - [v1 → v2 migration](../migration/v1-to-v2.md) — column renames and DDL diffs
+- [v2.3 → v2.4 migration](../migration/v2-3-to-v2-4.md) — the `version` column and `update()` signature change

package/docs/reference/branches.md

@@ -19,7 +19,7 @@ Branches resolve **after** the step's post-LLM phase (tool execution, `finalize`
 
 ```typescript
 interface BranchEntry<TContext = unknown, TData = unknown> {
-  /** AI-evaluated condition. String or array of strings (OR semantics). */
+  /** AI condition: positives OR, ! exclusions inhibit. */
   when?: string | string[];
 
   /** Code predicate. Function or array of functions (AND semantics). */
@@ -64,7 +64,7 @@ interface BranchPredicateContext<TContext = unknown, TData = unknown> {
 
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
-| `when` | `string \| string[]` | no | — | AI-evaluated condition. Arrays use OR semantics. Reuses the same machinery as `step.when`. Only evaluated if `if` passes (or is absent). Costs LLM tokens. |
+| `when` | `string \| string[]` | no | — | AI-evaluated condition. Non-`!` strings are OR alternatives; `!` strings are OR exclusions where any match inhibits the branch. Reuses the same machinery as `step.when`. Only evaluated if `if` passes (or is absent). Costs LLM tokens. |
 | `if` | `BranchPredicate \| BranchPredicate[]` | no | — | Code predicate. Free to evaluate. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if all `if` predicates pass. |
 | `then` | `string \| Directive` | yes | — | Target. See [Resolution of `then`](#resolution-of-then) below. |
 | `label` | `string` | no | — | Optional label surfaced in event traces and flow visualization. |

package/docs/reference/create-agent.md

@@ -59,9 +59,9 @@ interface AgentOptions<TContext = unknown, TData = unknown> {
 | `name` | `string` | yes | — | Display name surfaced in logs and prompt sections. |
 | `goal` | `string` | no | — | One-line objective rendered into the system prompt. |
 | `persona` | `Template<TContext>` | no | — | Who the agent is and how it communicates — role, tone, and self-concept. Rendered into the system prompt. |
-| `provider` | `AiProvider` | yes | — | Strategy instance: `GeminiProvider`, `OpenAIProvider`, `AnthropicProvider`, or `OpenRouterProvider`. |
+| `provider` | `AiProvider` | yes | — | Strategy instance: `GeminiProvider`, `OpenAIProvider`, `AnthropicProvider`, `OpenRouterProvider`, `DeepSeekProvider`, or your own (must declare `capabilities`). |
 | `schema` | `StructuredSchema` | no | — | Single source of truth for `TData`. Every `collect` key in every step must reference a property defined here. |
-| `initialData` | `Partial<TData>` | no | — | Pre-populates `session.data` when the agent is constructed. |
+| `initialData` | `Partial<TData>` | no | — | Staged at construction and seeds `session.data` when the first session is created. Loading an existing session keeps the stored data instead. |
 | `flows` | `FlowOptions<TContext, TData>[]` | no | `[]` | Conversation flows. May also be added later via `agent.createFlow(...)`. |
 | `tools` | `Tool<TContext, TData, unknown>[]` | no | `[]` | Agent-scoped tools. Each tool's `Tool.id` must be unique. |
 | `instructions` | `Instruction<TContext, TData>[]` | no | `[]` | Behavioral statements discriminated by `kind: 'must' \| 'never' \| 'should'`. Scoped at agent, flow, or step level. |
@@ -71,7 +71,7 @@ interface AgentOptions<TContext = unknown, TData = unknown> {
 | `context` | `TContext` | no | — | Static ambient data (user info, env, etc.) available to every hook and tool. |
 | `contextProvider` | `ContextProvider<TContext>` | no | — | Async context loader. Use instead of `context` when ambient data must be fetched per turn. |
 | `hooks` | `ContextLifecycleHooks<TContext, TData>` | no | — | `beforeRespond`, `onContextUpdate`, `onDataUpdate` — fire around every turn. |
-| `persistence` | `PersistenceConfig<TData>` | no | in-memory | Session storage. Omit for `MemoryAdapter`. |
+| `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. |
 | `maxAutoStepsPerTurn` | `number` | no | `10` | Cap on consecutive `auto: true` steps per turn. Throws `FlowConfigurationError` when exceeded. |