@falai/agent 2.6.1 → 2.7.0

package/docs/reference/create-agent.md

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

package/docs/reference/directive.md

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

package/docs/reference/errors.md

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

package/docs/reference/providers.md

@@ -63,11 +63,11 @@ import {
 
 const provider =
   process.env.PROVIDER === "openai"
-    ? new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: "gpt-5.5" })
+    ? new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: "gpt-5.6" })
     : process.env.PROVIDER === "anthropic"
-    ? new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY!, model: "claude-sonnet-4-6" })
+    ? new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY!, model: "claude-sonnet-5" })
     : process.env.PROVIDER === "openrouter"
-    ? new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY!, model: "anthropic/claude-sonnet-4.6" })
+    ? new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY!, model: "anthropic/claude-sonnet-5" })
     : process.env.PROVIDER === "deepseek"
     ? new DeepSeekProvider({ apiKey: process.env.DEEPSEEK_API_KEY!, model: "deepseek-chat" })
     : new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY!, model: "gemini-3.1-pro-preview" });
@@ -88,6 +88,7 @@ interface GeminiProviderOptions {
   backupModels?: string[];
   config?: Partial<GenerateContentConfig>; // from @google/genai
   retryConfig?: { timeout?: number; retries?: number };
+  client?: GoogleGenAI;                    // pre-configured SDK client override
 }
 ```
 
@@ -95,12 +96,13 @@ interface GeminiProviderOptions {
 
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
-| `apiKey` | `string` | yes | — | Throws if empty. |
+| `apiKey` | `string` | yes* | — | Throws if empty (unless `client` is set). |
 | `model` | `string` | yes | — | Use the model id, e.g. `"gemini-3.1-pro-preview"`. |
-| `backupModels` | `string[]` | no | `[]` | Tried in order on 429/500/503/overload errors. |
+| `backupModels` | `string[]` | no | `[]` | Tried in order on retriable failures (rate limits, overload, timeouts, network). |
 | `config` | `Partial<GenerateContentConfig>` | no | — | Vendor-typed defaults (e.g. `temperature`, `systemInstruction`). |
-| `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
+| `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. On streams it also bounds time-to-first-token. |
 | `retryConfig.retries` | `number` | no | `3` | Total attempts before giving up. |
+| `client` | `GoogleGenAI` | no | — | Pre-configured SDK client; overrides the internally-constructed one. Intended for tests injecting scripted transports; production callers should pass `apiKey`. |
 
 ### Example
 
@@ -136,7 +138,7 @@ interface OpenAIProviderOptions {
 |-------|------|----------|---------|-------|
 | `apiKey` | `string` | yes | — | Throws if empty. |
 | `organization` | `string` | no | — | Forwarded as `OpenAI-Organization`. |
-| `model` | `string` | yes | — | e.g. `"gpt-5.5"`, `"gpt-5.4"`. |
+| `model` | `string` | yes | — | e.g. `"gpt-5.6"`, `"gpt-5.4-mini"`. |
 | `backupModels` | `string[]` | no | `[]` | Tried in order on overload/rate-limit errors. |
 | `config` | OpenAI params | no | — | Defaults for `temperature`, `top_p`, etc. |
 | `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
@@ -147,7 +149,7 @@ interface OpenAIProviderOptions {
 ```typescript
 const openai = new OpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY!,
-  model: "gpt-5.5",
+  model: "gpt-5.6",
   organization: "org_abc",
   config: { temperature: 0.2 },
 });
@@ -166,6 +168,7 @@ interface AnthropicProviderOptions {
   backupModels?: string[];
   config?: Partial<Omit<MessageCreateParamsNonStreaming, "model" | "messages">>;
   retryConfig?: { timeout?: number; retries?: number };
+  client?: Anthropic;                      // pre-configured SDK client override
 }
 ```
 
@@ -173,19 +176,20 @@ interface AnthropicProviderOptions {
 
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
-| `apiKey` | `string` | yes | — | Throws if empty. |
-| `model` | `string` | yes | — | e.g. `"claude-sonnet-4-6"`, `"claude-opus-4-7"`. |
-| `backupModels` | `string[]` | no | `[]` | Tried in order on 429/500/503/529/overload. |
+| `apiKey` | `string` | yes* | — | Throws if empty (unless `client` is set). |
+| `model` | `string` | yes | — | e.g. `"claude-sonnet-5"`, `"claude-opus-5"`. |
+| `backupModels` | `string[]` | no | `[]` | Tried in order on retriable failures (rate limits, overload incl. 529, timeouts, network). |
 | `config` | Anthropic params | no | — | Defaults for `max_tokens`, `system`, etc. The provider sets `max_tokens=4096` if neither `config.max_tokens` nor `parameters.maxOutputTokens` is set. |
-| `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
+| `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. On streams it also bounds time-to-first-token. |
 | `retryConfig.retries` | `number` | no | `3` | Total attempts. |
+| `client` | `Anthropic` | no | — | Pre-configured SDK client; overrides the internally-constructed one. Intended for tests injecting scripted transports; production callers should pass `apiKey`. |
 
 ### Example
 
 ```typescript
 const anthropic = new AnthropicProvider({
   apiKey: process.env.ANTHROPIC_API_KEY!,
-  model: "claude-sonnet-4-6",
+  model: "claude-sonnet-5",
   config: { max_tokens: 8192 },
 });
 ```
@@ -215,7 +219,7 @@ interface OpenRouterProviderOptions {
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
 | `apiKey` | `string` | yes | — | Throws if empty. |
-| `model` | `string` | yes | — | OpenRouter model id, e.g. `"anthropic/claude-sonnet-4.6"`. See [openrouter.ai/models](https://openrouter.ai/models). |
+| `model` | `string` | yes | — | OpenRouter model id, e.g. `"anthropic/claude-sonnet-5"`. See [openrouter.ai/models](https://openrouter.ai/models). |
 | `backupModels` | `string[]` | no | `[]` | Tried in order on overload/capacity errors. |
 | `siteUrl` | `string` | no | `""` | Sent as `HTTP-Referer` for OpenRouter rankings. |
 | `siteName` | `string` | no | `""` | Sent as `X-Title` for OpenRouter rankings. |
@@ -228,8 +232,8 @@ interface OpenRouterProviderOptions {
 ```typescript
 const openrouter = new OpenRouterProvider({
   apiKey: process.env.OPENROUTER_API_KEY!,
-  model: "anthropic/claude-sonnet-4.6",
-  backupModels: ["openai/gpt-5.5", "google/gemini-3.1-pro-preview"],
+  model: "anthropic/claude-sonnet-5",
+  backupModels: ["openai/gpt-5.6", "google/gemini-3.1-pro-preview"],
   siteName: "My App",
 });
 ```
@@ -326,10 +330,10 @@ 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 | `ProviderError` with a normalized `code` | After exhausting retries and `backupModels`. The agent wraps it in `ResponseGenerationError`. |
+| Primary and every backup model fail | `ProviderError` with a normalized `code` | After exhausting retries and `backupModels`. Propagates bare out of `respond()`. |
 | 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.
+The retry/backup logic only kicks in for **transient** errors: rate limits (429), overload/availability (500/503, Anthropic's 529, `overloaded`-style codes and messages such as `overloaded`, `unavailable`, `internal error`, or OpenRouter's `capacity`), timeouts, and network faults. Deterministic failures — auth (401/403), invalid requests (400/404/422), and caller aborts — fail fast without burning the retry budget. On streaming calls, only failures *before the first chunk* are retried; `retryConfig.timeout` doubles as the time-to-first-token deadline so a stream that opens and stalls is treated as failed.
 
 ### `ProviderError`
 
@@ -358,7 +362,7 @@ try {
 }
 ```
 
-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).
+When the failure surfaces through `agent.respond(...)`, the `ProviderError` propagates **bare** — catch it with `instanceof`, no unwrapping. (On streaming turns, errors arrive wrapped as `ResponseGenerationError` on the final chunk's `error` field, with the original on `.cause`.) See [Errors](./errors.md).
 
 ## Related
 

package/docs/reference/step.md

@@ -101,30 +101,33 @@ interface StepLifecycleHooks<TContext = unknown, TData = unknown> {
 | `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. |
 | `instructions` | `Instruction<TContext, TData>[]` | no | `[]` | Step-scoped behavioural statements (`kind: 'must' \| 'never' \| 'should'`). Active only while this step is current. See [Instruction](./instruction.md). |
-| `prepare` | function, tool id, or `Tool` object | no | — | **Shorthand** pre-LLM hook. Receives `(context, data?)` and returns `void \| PrepareResult`. For full directive control, use `hooks.prepare` instead. |
-| `finalize` | function, tool id, or `Tool` object | no | — | **Shorthand** post-LLM hook. Same shape as `prepare`. For full directive control, use `hooks.finalize` instead. |
-| `hooks` | `StepLifecycleHooks<TContext, TData>` | no | — | Full lifecycle callbacks: `onEnter`, `prepare`, `finalize`, `onExit`. See the table below. |
+| `prepare` | function, tool id, or `Tool` object | no | — | Pre-LLM hook. Receives `(context, data?)` and returns `void \| PrepareResult` (a Directive may be returned too). `PrepareResult` includes the pre-LLM augmentation fields `appendPrompt: string[]` and `injectTools: Tool[]` — honored by auto steps; other step kinds drop them with a loud warning. |
+| `finalize` | function, tool id, or `Tool` object | no | — | Post-generation hook, runs before persistence. Same shape as `prepare`. A returned `goTo`/`goToStep`/`reset`/`complete` redirects the **next** turn; state writes land immediately. |
+| `hooks` | `StepLifecycleHooks<TContext, TData>` | no | — | Alternative spelling of `prepare`/`finalize` (`hooks.prepare`, `hooks.finalize`). Both spellings run when declared together — shorthand first, then the hook, returns merged via Algorithm 4. |
 | `branches` | `BranchEntry<TContext, TData>[]` | no | — | Explicit source-local fork. Evaluated after `finalize`, before linear successor selection. The first entry whose `if`/`when` passes wins; its `then` resolves to a step id, a flow id, or a `Directive`. See [Branches](./branches.md). |
 
 ### Lifecycle hooks
 
-The lifecycle has four positions. Two of them — `prepare` and
-`finalize` — are also reachable through the top-level shorthand
-fields, with a smaller return type.
+Two hook positions exist per step: `prepare` (before generation) and
+`finalize` (after generation, before persistence). Each is reachable
+through a top-level field, a `hooks.*` entry, or both — declaring both
+runs them in sequence (shorthand first) with their returns merged by
+Algorithm 4 (`flow.merge`).
 
-| Hook | When it fires | `hooks.<name>` returns | Top-level shorthand returns | Use it for |
-|------|---------------|------------------------|------------------------------|------------|
-| `onEnter` | Before any other work the first time the step becomes current. | `void \| Directive` | n/a (no shorthand) | Append per-turn prompt context, inject one-turn tools, or short-circuit with `halt + reply`. |
-| `prepare` | Right before the LLM call, after `onEnter`. | `void \| Directive` | `void \| PrepareResult` | Mutate session data, fetch external context, halt the LLM call. |
-| `finalize` | After the LLM call and tool loop complete. | `void \| Directive` | `void \| PrepareResult` | Validate collected data, redirect with `goTo` / `goToStep`, complete the flow. |
-| `onExit` | When the step is left (next step entered, flow completed, aborted). | `void` | n/a | Emit telemetry. Cannot influence flow control. |
+| Position | When it fires | May return | Use it for |
+|----------|---------------|------------|------------|
+| `prepare` / `hooks.prepare` | Before routing on the step's turn (non-auto steps). | `void \| PrepareResult` | Write session/context state, redirect the current turn with `goToStep`/`goTo`/`reset` (queued as `pendingDirective` and applied by routing this turn). |
+| `finalize` / `hooks.finalize` | After generation completes, BEFORE the session is persisted. | `void \| PrepareResult` | Validate collected data, write state, queue a redirect for the next turn (`pendingDirective`), e.g. `{ complete: { next: { goTo: 'Checkout' } } }`. |
 
-`PrepareResult` is the shorthand return — a flat object with the
-common Directive fields (`dataUpdate`, `contextUpdate`, `goTo`,
-`goToStep`, `complete`, `halt`, `reply`). Use `hooks.<name>` when you
-need the full `HookContext` (with `session`, `history`, `dispatch`)
-or the full `Directive` surface (`appendPrompt`,
-`injectTools`, `abort`, `reset`).
+Handler directives merge through the canonical algorithm and are
+validated with `flow.validate`. State writes
+(`dataUpdate`/`contextUpdate`) apply immediately to the turn session,
+so auto-save captures them even if this is the conversation's last
+turn.
+
+Note for **auto steps**: their `prepare` runs inside the auto-chain,
+where pre-LLM fields (`appendPrompt`, `injectTools`, `halt`, `reply`)
+are honored directly.
 
 ### Resolution within a step
 
@@ -133,12 +136,12 @@ For one step, the engine walks this sequence per turn:
 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).
+4. Run `prepare` / `hooks.prepare`. Its merged directive applies state writes immediately; position fields queue as `pendingDirective` for this turn's routing.
 5. **LLM step**: call the LLM with the step's prompt, tools, and instructions; tool loop runs until completion. **Auto step**: skip the LLM call. **Reply step**: render `reply` as the verbatim assistant message.
-6. Run `finalize` / `hooks.finalize`. May emit a `Directive`.
+6. Run `finalize` / `hooks.finalize` (before persistence). State writes land now; position fields queue for the next turn.
 7. Evaluate `branches`. The first entry whose `if`/`when` passes wins; its `then` resolves to a step id, a flow id, or a full `Directive`. If no entry matches, fall through.
 8. Linear successor / AI step selection.
-9. Run `onExit` for the step we are leaving.
+9. Persist the session (auto-save) after finalize has run.
 
 ## Examples
 
@@ -317,6 +320,10 @@ following are thrown synchronously when the agent is built:
   `reset`).
 - `FlowConfigurationError` — a `branches[i].then` Directive contains
   an empty `goTo: {}`.
+- `FlowConfigurationError` — a tool-based `prepare`/`finalize` (tool id
+  or `Tool` object) is combined with `hooks.prepare`/`hooks.finalize`.
+  A step can only have one handler per position — remove one or inline
+  the tool call inside a function.
 
 Runtime errors that surface from a step's hook execution include
 `DataValidationError` (invalid collected data), `ToolExecutionError`

package/docs/reference/tool.md

@@ -251,15 +251,24 @@ export const bookHotel: Tool<Ctx, Data, { id: string }> = {
 };
 ```
 
+## Directive wiring and turn semantics
+
+Tool-emitted directives work end-to-end: both `ctx.dispatch(directive)` calls and `{ directive }` returns are collected during execution, merged via Algorithm 4, and delivered to the engine in the same turn.
+
+- **State fields** (`dataUpdate`, `contextUpdate`) apply immediately.
+- **A `reply` directive short-circuits the tool loop** — its verbatim text becomes the final assistant message with no follow-up LLM call.
+- **Control-flow fields** (`goTo`, `goToStep`, `reset`, …) queue on `session.pendingDirective` and steer the *next* turn (same deferred semantics as `agent.dispatch()`).
+
+A handler that **throws** (or a call to an unregistered tool) never crashes the turn: the executor reports a failure result *to the model* — a `role: "tool"` message shaped `{"success":false,"error":"…"}` — so it can react to the failed call instead of the framework fabricating a success.
+
 ## Errors
 
-Misuse surfaces as typed errors from the executor:
+Misuse surfaces as typed errors from registration-time validation; execution-time problems degrade to failed tool results rather than thrown errors:
 
-- `ToolExecutionError` — handler threw, returned `success: false`, exceeded `maxResultSizeChars` after compaction, or the tool was invoked with arguments that fail `validateInput` and cannot be corrected.
+- `ToolCreationError` — invalid tool definition at registration (missing id/handler, duplicate id, bad schema).
 - `FlowConfigurationError` — a returned `directive` is malformed (e.g., two position fields set, or `goTo` references an unknown flow/step).
-- `DataValidationError` — `dataUpdate` violates the agent schema.
-
-Permission denials (`checkPermissions` returning `allowed: false`) are surfaced as a structured tool result with `success: false` and `error: <reason>` rather than a thrown error — this keeps the AI's reasoning loop intact.
+- Execution failures — a thrown handler, `success: false` return, permission denial, failed `validateInput`, timeout, or unknown tool name all become structured `success: false` tool results surfaced to the model, keeping the AI's reasoning loop intact.
+- `DataValidationError` — `dataUpdate` violates the agent schema (logged; the call reports failure instead of applying the write).
 
 ## Related
 

package/docs/start/02-first-agent.md

@@ -32,7 +32,9 @@ const agent = createAgent({
   }],
 });
 
-const response = await agent.respond("Hi, I'm Alice");
+const response = await agent.respond({
+  history: [{ role: "user", content: "Hi, I'm Alice" }],
+});
 console.log(response.message);
 ```
 
@@ -110,14 +112,16 @@ requiredFields: ["name"],
 
 For this agent, completion happens on the first turn. For a longer flow, the gate would force more steps before the model wraps up.
 
-### `agent.respond(message)`
+### `agent.respond(params)`
 
 ```typescript
-const response = await agent.respond("Hi, I'm Alice");
+const response = await agent.respond({
+  history: [{ role: "user", content: "Hi, I'm Alice" }],
+});
 console.log(response.message);
 ```
 
-`respond(message)` runs one turn end to end: load (or create) the session, route to a flow, extract data, walk auto-step chains, call the LLM, deliver the assistant message, persist. It returns an `AgentResponse` with the fields you usually want on hand:
+`respond(params)` runs one turn end to end: route to a flow, extract data, walk auto-step chains, call the LLM, deliver the assistant message, persist. `params` takes `history` (required — the conversation so far as `{ role, content }[]`) and optionally `session`, `contextOverride`, and `signal`. When no session is passed, the agent manages one internally; pass an explicit session (see below) for server-side, multi-conversation use. It returns an `AgentResponse` with the fields you usually want on hand:
 
 | Field | Type | What it is |
 |-------|------|------------|

package/docs/start/03-collect-data.md

@@ -147,16 +147,15 @@ The pattern is consistent: the schema describes the universe of possible data, e
 Run the file with a single message that contains all three fields:
 
 ```typescript
-const session = { id: "demo-session" };
-
-const response = await agent.respond(
-  "I want a hotel in Lisbon for two people next Friday.",
-  session,
-);
+const response = await agent.respond({
+  history: [
+    { role: "user", content: "I want a hotel in Lisbon for two people next Friday." },
+  ],
+});
 
 console.log(response.message);
-console.log(response.data);
-console.log(response.currentStep?.id);
+console.log(response.session?.data);
+console.log(response.session?.currentStep?.id);
 ```
 
 The output is roughly:
@@ -176,7 +175,13 @@ Three things happened in one turn:
 Try a message with one missing field:
 
 ```typescript
-await agent.respond("Book me a hotel in Lisbon next Friday.", session);
+await agent.respond({
+  history: [
+    { role: "user", content: "I want a hotel in Lisbon" },
+    { role: "assistant", content: "Sure — when do you travel?" },
+    { role: "user", content: "Book me a hotel in Lisbon next Friday." },
+  ],
+});
 ```
 
 The extractor populates `city` and `checkIn`. `ask_city` and `ask_check_in` both skip — their `collect` keys are present. `ask_guests` does *not* skip — `guests` is undefined — so the engine enters it and the assistant asks how many people are travelling.
@@ -184,7 +189,11 @@ The extractor populates `city` and `checkIn`. `ask_city` and `ask_check_in` both
 Try the inverse: a message with only one field.
 
 ```typescript
-await agent.respond("I'd like to go to Lisbon.", session);
+await agent.respond({
+  history: [
+    { role: "user", content: "I'd like to go to Lisbon." },
+  ],
+});
 ```
 
 The extractor populates `city` only. `ask_city` skips, `ask_check_in` enters next (its `requires: ["city"]` is satisfied), and the assistant asks for the check-in date. Three turns later, the same `confirm` step runs.

package/examples/01-quickstart.ts

@@ -7,7 +7,7 @@ if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
 
 const agent = createAgent({
     name: "Greeter",
-    provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY, model: "gemini-3.1-flash-lite" }),
+    provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY, model: "gemini-3.5-flash-lite" }),
     schema: { type: "object", properties: { name: { type: "string" } } },
     flows: [{
         title: "Greet",

package/examples/02-data-extraction.ts

@@ -40,7 +40,7 @@ const agent = createAgent<Record<string, never>, BookingData>({
     name: "Booking Agent",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "gemini-3.1-flash-lite",
+        model: "gemini-3.5-flash-lite",
     }),
     schema,
     flows: [

package/examples/03-tools.ts

@@ -99,7 +99,7 @@ const agent = createAgent<AppContext, AppData>({
     name: "BookingAgent",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "gemini-3.1-flash-lite",
+        model: "gemini-3.5-flash-lite",
     }),
     schema: {
         type: "object",

package/examples/04-instructions.ts

@@ -22,7 +22,7 @@ const agent = createAgent<unknown, SupportData>({
     name: "SupportBot",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY,
-        model: "gemini-3.1-flash-lite",
+        model: "gemini-3.5-flash-lite",
     }),
     schema: {
         type: "object",

package/examples/05-branching.ts

@@ -13,7 +13,7 @@ interface Data { intent: string; query: string; answer: string }
 
 const provider = new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
-    model: "gemini-3.1-flash-lite",
+    model: "gemini-3.5-flash-lite",
 });
 
 // ─── Steps with branches ─────────────────────────────────────────────────────

package/examples/06-flow-control.ts

@@ -19,7 +19,7 @@ const agent = createAgent<{}, AppData>({
     name: "FlowControlDemo",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "gemini-3.1-flash-lite",
+        model: "gemini-3.5-flash-lite",
     }),
     schema: {
         type: "object",
@@ -45,8 +45,8 @@ const agent = createAgent<{}, AppData>({
                     // When the user confirms, complete with a chained directive
                     // that moves to the "Checkout" flow.
                     hooks: {
-                        finalize: ({ data }) => {
-                            if (data.confirmed) {
+                        finalize: (_context, data) => {
+                            if (data?.confirmed) {
                                 const d: Directive<{}, AppData> = {
                                     complete: { next: { goTo: "Checkout" }, reason: "User confirmed" },
                                 };

package/examples/07-streaming.ts

@@ -18,7 +18,7 @@ const agent = createAgent<{}, AppData>({
     name: "StreamingDemo",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "gemini-3.1-flash-lite",
+        model: "gemini-3.5-flash-lite",
     }),
     schema: {
         type: "object",

package/examples/08-persistence.ts

@@ -7,7 +7,7 @@ if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
 
 const provider = new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY,
-    model: "gemini-3.1-flash-lite",
+    model: "gemini-3.5-flash-lite",
 });
 
 const schema = {

package/examples/09-signals.ts

@@ -100,7 +100,7 @@ const agent = createAgent<AppContext, AppData>({
     name: "SupportAgent",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "gemini-3.1-flash-lite",
+        model: "gemini-3.5-flash-lite",
     }),
     context: { supportTier: "free" },
     schema: {