@falai/agent 2.2.4 → 2.4.2

package/docs/reference/errors.md

@@ -31,6 +31,17 @@ class ToolExecutionError      extends Error {
   cause?: Error;
 }
 class NotImplementedError     extends Error { /* name = "NotImplementedError" */ }
+class ProviderError           extends Error {
+  code: ProviderErrorCode;   // 'rate_limited' | 'overloaded' | 'auth' | 'invalid_request'
+                             // | 'schema_rejected' | 'timeout' | 'network' | 'unknown'
+  provider: string;          // e.g. "openai"
+  cause?: unknown;           // original SDK/HTTP error
+}
+class SessionConflictError    extends Error {
+  sessionId: string;
+  expectedVersion: number;
+  actualVersion: number | undefined;
+}
 
 // Internal — match by `error.name` (not exported from the package barrel)
 class DataValidationError     extends Error { errors: ValidationError[] }
@@ -53,6 +64,8 @@ class ResponseGenerationError extends Error {
 | `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`. |
+| `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. |
 
 ## Examples
@@ -87,7 +100,57 @@ try {
 }
 ```
 
-### 2. The format contract in practice
+### 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`.
+
+```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.";
+  }
+}
+```
+
+### 3. Recovering from a session conflict
+
+`SessionConflictError` means another writer persisted the session between your load and your save. Reload, then retry.
+
+```typescript
+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) {
+    const fresh = await agent.session.getOrCreate(sessionId);
+    return agent.respond({ history, session: fresh });
+  }
+  throw err;
+}
+```
+
+### 4. The format contract in practice
 
 Every thrown message is parseable. The leading `[<ErrorClass>]` token mirrors the class name, the colon separates `<what>` from `<why>`, and the trailing sentence is `<how to fix>`.
 
@@ -120,3 +183,5 @@ Tool input validation, permission denials, and missing-tool warnings are reporte
 - [createAgent](./create-agent.md) — construction-time errors thrown from `new Agent(...)`.
 - [Tool](./tool.md) — handler return shape and the `ToolExecutionError` triggers.
 - [Directive](./directive.md) — the validation rules that surface as `FlowConfigurationError`.
+- [Providers](./providers.md) — the retry/backup pipeline that ends in `ProviderError`.
+- [Persistence adapters](./adapters.md) — the optimistic locking that throws `SessionConflictError`.

package/docs/reference/flow.md

@@ -77,7 +77,7 @@ class Flow<TContext = unknown, TData = unknown> {
 | `id`                  | `string`                                          | no       | derived from `title` | Stable identifier. Auto-generated deterministically from the title when omitted.                                                                                 |
 | `title`               | `string`                                          | yes      | —       | Human-readable name. Shown to the router and used as the default flow id.                                                                          |
 | `description`         | `string`                                          | no       | —       | One-line summary surfaced to the router prompt.                                                                                                    |
-| `when`                | `string \| string[]`                              | no       | —       | AI-evaluated activation condition(s). Strings only — functions belong on `if`. Multiple strings combine with OR semantics.                         |
+| `when`                | `string \| string[]`                              | no       | —       | AI-evaluated activation condition(s). Strings only — functions belong on `if`. Non-`!` strings are OR alternatives; `!` strings are OR exclusions where any match inhibits activation.                         |
 | `if`                  | `(ctx) => boolean \| Promise<boolean>` or array   | no       | —       | Code-evaluated activation condition(s). Free to evaluate. When both are set, `if` runs first; `when` only evaluates if `if` passes.                |
 | `instructions`        | `Instruction<TContext, TData>[]`                  | no       | `[]`    | Flow-scoped instructions. Apply only while this flow is active. See [Instruction](./instruction.md).                                               |
 | `tools`               | `(string \| Tool)[]`                              | no       | `[]`    | Tool ids (resolved via the agent's tool registry) or inline `Tool` objects. Available only while this flow is active.                              |

package/docs/reference/instruction.md

@@ -19,7 +19,7 @@ The set of instructions actually rendered into a given turn's prompt is reported
 interface Instruction<TContext = unknown, TData = unknown> {
   id?: string;
   kind?: 'must' | 'never' | 'should';        // default: 'should'
-  when?: ConditionWhen;                       // AI-evaluated string(s), OR semantics
+  when?: ConditionWhen;                       // AI strings: positives OR, ! exclusions inhibit
   if?: ConditionIf<TContext, TData>;          // code-evaluated function(s), AND semantics
   prompt: Template<TContext, TData>;
   enabled?: boolean;                          // default: true
@@ -48,7 +48,7 @@ interface AppliedInstruction {
 |-------|------|----------|---------|-------|
 | `prompt` | `Template<TContext, TData>` | yes | — | Behavioral text rendered into the prompt under the `## Instructions` section. |
 | `kind` | `'must' \| 'never' \| 'should'` | no | `'should'` | Severity. `'must'` = absolute do, `'never'` = absolute don't, `'should'` = conditional nudge. |
-| `when` | `ConditionWhen` | no | — | AI-evaluated activation string (or array, OR semantics). Functions are not allowed here; use `if`. |
+| `when` | `ConditionWhen` | no | — | AI-evaluated activation string or array. Non-`!` entries are OR alternatives. `!` entries are OR exclusions; any matching exclusion inhibits the instruction. Functions are not allowed here; use `if`. |
 | `if` | `ConditionIf<TContext, TData>` | no | — | Code-evaluated activation function (or array). Free to evaluate. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if `if` passes. |
 | `id` | `string` | no | auto | Stable identifier used in `AppliedInstruction.id`. Auto-generated when omitted. |
 | `enabled` | `boolean` | no | `true` | Set `false` to skip the instruction without removing it from configuration. |
@@ -74,10 +74,10 @@ The same `Instruction` shape attaches at three positions:
 At prompt-build time the composer renders each eligible instruction as a single bullet:
 
 ```
-- [<kind>] [<scope-caption>] <prompt> (apply only when: <when-clause> OR <when-clause>)
+- [<kind>] [<scope-caption>] <prompt> (apply only when: <when-clause> OR <when-clause>; do not apply when: <exclusion-clause>)
 ```
 
-The parenthesized condition is omitted when `when` is not set. Code-evaluated `if` predicates run first; a failing predicate removes the entire bullet before the prompt reaches the model.
+The parenthesized condition is omitted when `when` is not set. If `when` contains only `!` exclusions, the suffix uses only `do not apply when: ...`. Code-evaluated `if` predicates run first; a failing predicate removes the entire bullet before the prompt reaches the model.
 
 Scope captions are fixed by where the instruction was declared:
 

package/docs/reference/providers.md

@@ -1,6 +1,6 @@
 ---
 title: "Providers"
-description: "Strategy classes that connect an Agent to Gemini, OpenAI, Anthropic, or OpenRouter."
+description: "Strategy classes that connect an Agent to Gemini, OpenAI, Anthropic, OpenRouter, or DeepSeek — plus the base class for building your own."
 type: reference
 order: 10
 ---
@@ -21,6 +21,32 @@ Providers are the strategy plug between an `Agent` and a model vendor. Every pro
 | OpenRouter | `OpenRouterProvider` | `OpenRouterProviderOptions` | `openai` (compat) |
 | DeepSeek | `DeepSeekProvider` | `DeepSeekProviderOptions` | `openai` (compat) |
 
+## Capabilities
+
+Every provider declares a required `capabilities: ProviderCapabilities` field — five static flags the engine reads to decide how to drive the vendor (e.g., whether structured output is schema-enforced or prompt-instructed). Custom `AiProvider` implementations **must** declare it.
+
+```typescript
+interface ProviderCapabilities {
+  supportsTools: boolean;              // tool/function calling
+  supportsNativeJsonSchema: boolean;   // native JSON-schema-enforced output (vs. prompt-based JSON instruction)
+  supportsStreaming: boolean;          // streaming responses
+  supportsStreamingToolCalls: boolean; // tool calls surfaced during streaming
+  supportsPromptCaching: boolean;      // prompt caching
+}
+```
+
+The five built-ins:
+
+| Capability | Gemini | OpenAI | Anthropic | OpenRouter | DeepSeek |
+|------------|--------|--------|-----------|------------|----------|
+| `supportsTools` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `supportsNativeJsonSchema` | ✅ | ✅ | ❌ | ✅ | ✅ |
+| `supportsStreaming` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `supportsStreamingToolCalls` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `supportsPromptCaching` | ❌ | ❌ | ✅ | ❌ | ❌ |
+
+The two asymmetries: Anthropic reports `supportsNativeJsonSchema: false` because its JSON output is enforced via a prompt instruction, not a native schema mode — and it is the only built-in that reports `supportsPromptCaching: true`.
+
 ## Use with createAgent
 
 `createAgent({ provider })` accepts any class that implements `AiProvider`. Swap providers by changing the constructor; nothing else in your agent has to move.
@@ -250,6 +276,47 @@ const deepseek = new DeepSeekProvider({
 });
 ```
 
+## Building a custom OpenAI-compatible provider
+
+Many vendors (Groq, Together, Fireworks, …) expose OpenAI-compatible chat-completions APIs. Instead of implementing `AiProvider` from scratch, subclass the exported `OpenAICompatibleProvider` base class — it handles message/history building, tool-call parsing, streaming chunks, backup-model fallback, retries, schema passthrough, and normalized `ProviderError` wrapping. `OpenAIProvider`, `OpenRouterProvider`, and `DeepSeekProvider` are themselves thin subclasses.
+
+A minimal subclass supplies the configured client, naming, and capabilities:
+
+```typescript
+import OpenAI from "openai";
+import {
+  OpenAICompatibleProvider,
+  type ProviderCapabilities,
+} from "@falai/agent";
+
+export class GroqProvider extends OpenAICompatibleProvider {
+  public readonly name = "groq";
+  public readonly capabilities: ProviderCapabilities = {
+    supportsTools: true,
+    supportsNativeJsonSchema: true,
+    supportsStreaming: true,
+    supportsStreamingToolCalls: true,
+    supportsPromptCaching: false,
+  };
+
+  protected readonly logLabel = "GROQ";       // tag in log lines
+  protected readonly displayName = "Groq";    // name in retry/error messages
+
+  constructor(options: { apiKey: string; model: string; backupModels?: string[] }) {
+    super({
+      client: new OpenAI({
+        apiKey: options.apiKey,
+        baseURL: "https://api.groq.com/openai/v1",
+      }),
+      model: options.model,
+      backupModels: options.backupModels,
+    });
+  }
+}
+```
+
+That is a complete, working provider. For genuinely vendor-specific behavior, override the protected hooks — `DeepSeekProvider` is the reference pattern: it overrides `executeStructuredGenerate` (no `responses.parse` API), `structuredResponseFormat` (native `json_schema` enforcement), `configureStreamParams` (usage in stream chunks), and `onStreamDelta` (reasoning content on the delta).
+
 ## Errors
 
 All five providers share the same construction-time guards and runtime failure modes.
@@ -259,15 +326,45 @@ All five providers share the same construction-time guards and runtime failure m
 | `apiKey` is empty or missing | `Error("<vendor> API key is required")` | Thrown from the constructor. |
 | `model` is empty or missing | `Error("Model is required. ...")` | Thrown from the constructor. |
 | Vendor returns no text and no tool calls | `Error("No response from <vendor>")` | Surfaces as a `ResponseGenerationError` once it bubbles through the agent. |
-| Primary and every backup model fail | The last backup error is rethrown | After exhausting `backupModels`. The agent wraps it in `ResponseGenerationError`. |
+| Primary and every backup model fail | `ProviderError` with a normalized `code` | After exhausting retries and `backupModels`. The agent wraps it in `ResponseGenerationError`. |
 | Anthropic streaming with `system: undefined` | Vendor 400 | Set `config.system` or rely on history-derived system messages. |
 
 The retry/backup logic only kicks in for transient errors: HTTP 429 / 500 / 503 (and 529 for Anthropic), `overloaded`-style codes, or messages containing `overloaded`, `unavailable`, `internal error`, or (OpenRouter only) `capacity`. Other errors fail fast.
 
+### `ProviderError`
+
+Terminal failures — after retries and backup models are exhausted — throw the exported `ProviderError` with a normalized `code`, so callers handle failures uniformly regardless of which vendor is configured. The original SDK/HTTP error is preserved as `cause`.
+
+```typescript
+import { ProviderError } from "@falai/agent";
+
+type ProviderErrorCode =
+  | 'rate_limited'      // 429-style throttling
+  | 'overloaded'        // capacity / 503 / 529
+  | 'auth'              // invalid or missing credentials
+  | 'invalid_request'   // vendor rejected the request shape
+  | 'schema_rejected'   // structured-output schema rejected
+  | 'timeout'           // per-attempt timeout exhausted
+  | 'network'           // connection-level failure
+  | 'unknown';          // anything unclassified
+
+try {
+  await provider.generateMessage(input);
+} catch (err) {
+  if (err instanceof ProviderError) {
+    console.error(err.provider, err.code); // e.g. "openai" "rate_limited"
+    console.error(err.cause);              // original SDK error
+  }
+}
+```
+
+When the failure bubbles through `agent.respond(...)`, it is wrapped in `ResponseGenerationError` like every other turn failure — the `ProviderError` is then on `details.originalError`. See [Errors](./errors.md).
+
 ## Related
 
 - [Install](../start/01-install.md) — provider signup and env keys
 - [Architecture](../concepts/architecture.md) — where the provider sits in the engine
 - [createAgent](./create-agent.md) — the `provider` field
 - [Persistence adapters](./adapters.md) — the other strategy plug
-- [Errors](./errors.md) — `ResponseGenerationError` and friends
+- [Errors](./errors.md) — `ProviderError`, `ResponseGenerationError`, and friends
+- [v2.3 → v2.4 migration](../migration/v2-3-to-v2-4.md) — required `capabilities` and the `ProviderError` change

package/docs/reference/signals.md

@@ -88,13 +88,18 @@ interface SignalDirective<TContext = unknown, TData = unknown>
   replyWith?: string | ((ctx: SignalContext<TContext, TData>) => string);
 }
 
+// As reported on the response surface: replyWith already resolved onto reply
+type ResolvedSignalDirective<TContext = unknown, TData = unknown> =
+  Directive<TContext, TData> & { stopOtherSignals?: boolean };
+
 interface SignalFiring<TContext = unknown, TData = unknown> {
   id: string;
   phase: 'pre' | 'post';
   reason?: string;
   extracted?: unknown;
-  directive?: SignalDirective<TContext, TData>;
+  directive?: ResolvedSignalDirective<TContext, TData>;
   handlerError?: string;
+  extractionError?: string;
   durationMs?: number;
 }
 
@@ -130,7 +135,7 @@ interface AgentOptions<TContext, TData> {
 | `id` | `string` | no | auto-generated | Stable identifier within a session. Used for `SignalsState.triggers` keying and on `SignalFiring`. Must be unique across the agent's signals. |
 | `title` | `string` | no | — | Display title shown in logs and traces. |
 | `description` | `string` | no | — | Free-text description; rendered into the classifier prompt. |
-| `when` | `string \| string[]` | no | — | AI-evaluated condition(s). Non-prefixed entries render under "TRIGGER WHEN" (OR semantics — any match can trigger). Entries prefixed with `!` are exclusion conditions rendered under "DO NOT TRIGGER WHEN" (OR semantics — any match inhibits firing). |
+| `when` | `string \| string[]` | no | — | AI-evaluated condition(s), using the same `ConditionWhen` include/exclude syntax as flows, steps, branches, and instructions. Non-prefixed entries render under "TRIGGER WHEN" (OR semantics — any match can trigger). Entries prefixed with `!` are exclusion conditions rendered under "DO NOT TRIGGER WHEN" (OR semantics — any match inhibits firing). |
 | `if` | `SignalPredicate \| SignalPredicate[]` | no | — | Code predicate(s). AND semantics. Free to evaluate. Runs before `when`; if any returns `false`, `when` is skipped (no token cost). |
 | `extract` | `SignalSchema<TExtract>` | no | — | When set, the signal operates in extraction mode. JSON Schema object describing the per-signal `extracted` field merged into the classifier response. The `TExtract` generic carries the resulting type onto `ctx.extracted`. |
 | `phase` | `'pre' \| 'post' \| 'both'` | yes | — | When the signal evaluates. `'pre'` runs in parallel with routing. `'post'` runs after the LLM call, before persistence. `'both'` evaluates in both phases. |
@@ -185,6 +190,10 @@ Extends [`Directive`](./directive.md). All position fields (`goTo`, `goToStep`,
 
 **Post-phase drop rules.** When a signal runs in the post-phase, `appendPrompt`, `injectTools`, and `halt` are dropped with a debug warning — they have no meaning after the LLM call has already completed. Position directives in the post-phase set `session.pendingDirective` for the *next* turn (no mid-turn re-entry).
 
+### `ResolvedSignalDirective`
+
+The directive shape as reported on the response surface (`SignalFiring.directive`). The signal processor resolves `replyWith` onto `reply` and strips it before firings reach `AgentResponse` — so a `ResolvedSignalDirective` is a plain [`Directive`](./directive.md) plus `stopOtherSignals`, with the reply text (if any) always on `reply`. Exported from the package barrel.
+
 ### `SignalFiring`
 
 One entry per signal that fired this turn. Populated in fire order across both phases on `AgentResponse.triggeredSignals` (and on the final chunk of `AgentResponseStreamChunk`). Mirrors the observability framing of `executedSteps` and `appliedInstructions`.
@@ -195,8 +204,9 @@ One entry per signal that fired this turn. Populated in fire order across both p
 | `phase` | `'pre' \| 'post'` | Phase the signal fired in. |
 | `reason` | `string \| undefined` | AI rationale, `'code-only'`, or `'unconditional'`. |
 | `extracted` | `unknown` | Extracted payload when in extraction mode. |
-| `directive` | `SignalDirective \| undefined` | The directive returned (or dispatched) by the handler. |
+| `directive` | `ResolvedSignalDirective \| undefined` | The directive returned (or dispatched) by the handler, with `replyWith` already resolved onto `reply`. |
 | `handlerError` | `string \| undefined` | Error message if the handler threw. The turn continues — handler errors never break a turn. |
+| `extractionError` | `string \| undefined` | Set when an extraction-mode signal matched but the classifier returned no `extracted` payload (model omitted the field or returned `null`). The handler still runs with `extracted: undefined`; this makes the miss observable instead of silent. Independent of `handlerError`. |
 | `durationMs` | `number \| undefined` | Wall-clock duration of the handler invocation. |
 
 ### `SignalsState` and `SignalTriggerState`
@@ -345,6 +355,7 @@ Soft failures handled in-band (no thrown error, turn continues):
 
 - **Handler throws** — recorded as `firings[i].handlerError`; iteration continues with the next signal.
 - **Classifier call fails** — all LLM-conditioned signals in that batch are treated as non-match; code-only and unconditional signals continue normally.
+- **Extraction-mode signal matched but no payload returned** — recorded as `firings[i].extractionError` with a WARN log; the handler still runs with `extracted: undefined`. Usually means the `extract` schema used a keyword the provider ignores (e.g. `nullable: true` instead of `type: ['string', 'null']`), so the model omitted the field.
 - **Post-phase emits pre-LLM-only fields** (`halt` / `appendPrompt` / `injectTools`) — dropped with debug warning.
 - **`behavior: 'cooldown'` with no `cooldownMs`** — debug warning at construction; runtime treats as `'always'`.
 

package/docs/reference/step.md

@@ -96,7 +96,7 @@ interface StepLifecycleHooks<TContext = unknown, TData = unknown> {
 | `auto` | `boolean` | no | `false` | When `true`, the step runs without an LLM call — only `onEnter`, `prepare`, and `branches` execute. Cannot coexist with `prompt`, `collect`, `tools`, or `finalize`. Counts against `maxAutoStepsPerTurn`. |
 | `collect` | `(keyof TData)[]` | no | `[]` | Schema field keys this step is responsible for extracting from the user message. Every key must exist in the agent's `schema`. The engine skips the step automatically when every listed key is already present in `session.data` (pre-extraction). |
 | `requires` | `(keyof TData)[]` | no | `[]` | Prerequisite field keys. The engine refuses to enter the step until every key is present in `session.data`. When fields covered by `requires` are read inside `branches[].if` predicates, they are guaranteed to be defined. |
-| `when` | `string \| string[]` | no | — | AI-evaluated activation strings (OR semantics). Evaluated by the LLM at routing time. Functions are not allowed here — the constructor throws `FlowConfigurationError` if a function is found. |
+| `when` | `string \| string[]` | no | — | AI-evaluated activation strings. Non-`!` strings are OR alternatives; `!` strings are OR exclusions where any match inhibits activation. Evaluated by the LLM at routing time. Functions are not allowed here — the constructor throws `FlowConfigurationError` if a function is found. |
 | `if` | `(ctx) => boolean \| Promise<boolean>` or array | no | — | Code-evaluated activation predicates (AND semantics). Evaluated locally — no LLM cost. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if every `if` predicate passes. |
 | `skip` | `(ctx) => boolean \| Promise<boolean>` or array | no | — | Code-evaluated skip predicates (OR semantics). When any predicate returns `true`, the step is bypassed. Only code predicates — no AI strings. |
 | `tools` | `(string \| Tool<TContext, TData>)[]` | no | `[]` | Tools available during this step. Strings are resolved against the agent's tool registry; objects are inline tools. Stacked on top of agent and flow scopes. |
@@ -130,7 +130,7 @@ or the full `Directive` surface (`appendPrompt`,
 
 For one step, the engine walks this sequence per turn:
 
-1. Evaluate `if` (code, AND) and `when` (AI, OR) — fails skip the step entirely.
+1. Evaluate `if` (code, AND) and `when` (AI: positive OR, `!` exclusions inhibit) — fails skip the step entirely.
 2. Evaluate `skip` (code, OR) — true means bypass and fall through.
 3. Check `requires` — refuse entry if any required field is missing.
 4. Run `onEnter`, then `prepare` / `hooks.prepare`. May emit a `Directive` (pre-LLM fields honored).

package/docs/reference/tool.md

@@ -13,10 +13,12 @@ A `Tool` is a function the agent can invoke during a turn. v2 unifies tools into
 
 `Tool.id` is the sole identifier.
 
+Since v2.4 the generic defaults are `unknown` (previously `any`) on `Tool`, `ToolContext`, `ToolResult`, and `ToolHandler`. Pass explicit type parameters — or let inference flow from `createAgent`'s `schema` — to get typed `ctx.data` and `ctx.context`; untyped tool code that relied on implicit `any` needs explicit generics or a type guard.
+
 ## Signature
 
 ```typescript
-interface Tool<TContext = any, TData = any, TResult = any> {
+interface Tool<TContext = unknown, TData = unknown, TResult = unknown> {
   // Identity
   id: string;
   description?: string;

package/docs/start/05-go-to-production.md

@@ -54,6 +54,7 @@ model AgentSession {
   collectedData     Json?
   pendingDirective  Json?
   signals           Json?
+  version           Int?
   messageCount      Int       @default(0)
   lastMessageAt     DateTime?
   completedAt       DateTime?
@@ -115,6 +116,8 @@ const response = await agent.respond({
 
 Unknown ids start fresh against that id; there is no "not found" error path.
 
+The `version Int?` column enables optimistic locking: when two writers race on one session (parallel webhooks, a double-send), the stale save throws `SessionConflictError` instead of silently overwriting — reload the session and retry. See [Concurrent writers](../guides/persistence.md#concurrent-writers-optimistic-locking).
+
 For the full schema migration story (renaming `pending_transition` to `pendingDirective`, adding the `signals` column) see [persistence adapters reference](../reference/adapters.md#prismaadapter).
 
 ## 2. Stream responses

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "2.2.4",
+  "version": "2.4.2",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/adapters/MemoryAdapter.ts

@@ -11,8 +11,10 @@ import type {
   SessionData,
   SessionRepository,
   SessionStatus,
+  SessionUpdateOptions,
   CreateSessionData,
 } from "../types";
+import { SessionConflictError } from "../types/errors";
 import { cloneDeep } from "../utils/clone";
 import { createSessionId } from "../utils";
 
@@ -92,6 +94,7 @@ class MemorySessionRepository<TData = Record<string, unknown>>
       id,
       status: data.status || "active",
       messageCount: data.messageCount || 0,
+      version: data.version ?? 1,
       createdAt: now,
       updatedAt: now,
     };
@@ -126,14 +129,25 @@ class MemorySessionRepository<TData = Record<string, unknown>>
 
   async update(
     id: string,
-    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>
+    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>,
+    options?: SessionUpdateOptions
   ): Promise<SessionData<TData> | null> {
     const existing = this.sessions.get(id);
     if (!existing) return null;
 
+    // Compare-and-swap: rows without a stored version (pre-2.4) are accepted
+    if (
+      options?.expectedVersion !== undefined &&
+      existing.version !== undefined &&
+      existing.version !== options.expectedVersion
+    ) {
+      throw new SessionConflictError(id, options.expectedVersion, existing.version);
+    }
+
     const updated: SessionData<TData> = {
       ...existing,
       ...data,
+      version: (existing.version ?? options?.expectedVersion ?? 0) + 1,
       updatedAt: new Date(),
     };
 

package/src/adapters/MongoAdapter.ts

@@ -12,7 +12,9 @@ import type {
   SessionStatus,
   CollectedStateData,
   CreateSessionData,
+  SessionUpdateOptions,
 } from "../types";
+import { SessionConflictError } from "../types/errors";
 import { createSessionId } from "../utils";
 
 /**
@@ -144,6 +146,7 @@ class MongoSessionRepository<TData = Record<string, unknown>>
         createSessionId(),
       status: data.status || "active",
       messageCount: data.messageCount || 0,
+      version: data.version ?? 1,
       createdAt: now,
       updatedAt: now,
     };
@@ -173,11 +176,47 @@ class MongoSessionRepository<TData = Record<string, unknown>>
 
   async update(
     id: string,
-    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>
+    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>,
+    options?: SessionUpdateOptions
   ): Promise<SessionData<TData> | null> {
+    if (options?.expectedVersion !== undefined) {
+      const expectedVersion = options.expectedVersion;
+
+      // Compare-and-swap via the filter: docs without a stored version
+      // (pre-2.4) are accepted and adopt expectedVersion as their base
+      const result = await this.collection.updateOne(
+        {
+          id,
+          $or: [
+            { version: { $exists: false } },
+            { version: null },
+            { version: expectedVersion },
+          ],
+        },
+        { $set: { ...data, version: expectedVersion + 1, updatedAt: new Date() } }
+      );
+
+      if (result.matchedCount === 0) {
+        const existing = await this.collection.findOne({ id });
+        if (!existing) return null;
+        throw new SessionConflictError(id, expectedVersion, existing.version);
+      }
+
+      return await this.findById(id);
+    }
+
+    const existing = await this.collection.findOne({ id });
+    if (!existing) return null;
+
     const result = await this.collection.updateOne(
       { id },
-      { $set: { ...data, updatedAt: new Date() } }
+      {
+        $set: {
+          ...data,
+          version: (existing.version ?? 0) + 1,
+          updatedAt: new Date(),
+        },
+      }
     );
 
     if (result.matchedCount === 0) return null;

package/src/adapters/OpenSearchAdapter.ts

@@ -42,7 +42,9 @@ import type {
   MessageData,
   CollectedStateData,
   CreateSessionData,
+  SessionUpdateOptions,
 } from "../types";
+import { SessionConflictError } from "../types/errors";
 
 /**
  * OpenSearch Client interface (minimal typing for the official client)
@@ -200,6 +202,7 @@ export class OpenSearchAdapter<TData = Record<string, unknown>> implements Persi
               pendingDirective: { type: "object", enabled: false },
               signals: { type: "object", enabled: false },
               messageCount: { type: "integer" },
+              version: { type: "integer" },
               createdAt: { type: "date" },
               updatedAt: { type: "date" },
               lastMessageAt: { type: "date" },
@@ -266,6 +269,7 @@ class OpenSearchSessionRepository<TData = Record<string, unknown>>
       id,
       status: data.status || "active",
       messageCount: data.messageCount || 0,
+      version: data.version ?? 1,
       createdAt: now,
       updatedAt: now,
     };
@@ -341,10 +345,28 @@ class OpenSearchSessionRepository<TData = Record<string, unknown>>
 
   async update(
     id: string,
-    updates: Partial<Omit<SessionData<TData>, "id" | "createdAt">>
+    updates: Partial<Omit<SessionData<TData>, "id" | "createdAt">>,
+    options?: SessionUpdateOptions
   ): Promise<SessionData<TData> | null> {
+    // Check-then-set on the stored document — not fully atomic across writers
+    const existing = await this.findById(id);
+    if (!existing) return null;
+
+    if (
+      options?.expectedVersion !== undefined &&
+      existing.version !== undefined &&
+      existing.version !== options.expectedVersion
+    ) {
+      throw new SessionConflictError(
+        id,
+        options.expectedVersion,
+        existing.version
+      );
+    }
+
     const doc: Record<string, unknown> = {
       ...updates,
+      version: (existing.version ?? options?.expectedVersion ?? 0) + 1,
       updatedAt: new Date().toISOString(),
     };
 
@@ -485,6 +507,7 @@ class OpenSearchSessionRepository<TData = Record<string, unknown>>
       currentStep: doc.currentStep as string | undefined,
       collectedData: doc.collectedData as CollectedStateData<TData> | undefined,
       messageCount: (doc.messageCount as number) || 0,
+      version: (doc.version as number | null) ?? undefined,
       createdAt: new Date(doc.createdAt as string),
       updatedAt: new Date(doc.updatedAt as string),
       lastMessageAt: doc.lastMessageAt