@falai/agent 2.6.1 → 3.0.0

package/docs/reference/providers.md

@@ -11,15 +11,17 @@ order: 10
 
 Providers are the strategy plug between an `Agent` and a model vendor. Every provider implements the same `AiProvider` interface, so the Agent itself stays vendor-agnostic. Pass an instance to `createAgent({ provider })` and the agent talks to that vendor for every turn (and for compaction, if you wire it in).
 
-`@falai/agent` ships five built-in providers. All five accept an `apiKey` and a required `model`, support `backupModels` for automatic failover on overload or 5xx, and accept a vendor-typed `config` object that flows through to the underlying SDK.
+`@falai/agent` ships five built-in providers. All five accept an `apiKey` and a required `model`, support `backupModels` for automatic failover, and take the same neutral `RequestConfig` for sampling defaults.
 
-| Provider | Class | Options | SDK |
-|----------|-------|---------|-----|
-| Google Gemini | `GeminiProvider` | `GeminiProviderOptions` | `@google/genai` |
-| OpenAI | `OpenAIProvider` | `OpenAIProviderOptions` | `openai` |
-| Anthropic Claude | `AnthropicProvider` | `AnthropicProviderOptions` | `@anthropic-ai/sdk` |
-| OpenRouter | `OpenRouterProvider` | `OpenRouterProviderOptions` | `openai` (compat) |
-| DeepSeek | `DeepSeekProvider` | `DeepSeekProviderOptions` | `openai` (compat) |
+There are no vendor SDKs behind them. Every provider is a thin binding over [`@providerkit/core`](https://www.npmjs.com/package/@providerkit/core), which speaks each vendor's REST API over `fetch` — so installing this package does not install one vendor's SDK for a consumer who uses another.
+
+| Provider | Class | Options | Wire |
+|----------|-------|---------|------|
+| Google Gemini | `GeminiProvider` | `GeminiProviderOptions` | `generateContent` (SSE) |
+| OpenAI | `OpenAIProvider` | `OpenAIProviderOptions` | Responses API |
+| Anthropic Claude | `AnthropicProvider` | `AnthropicProviderOptions` | Messages API |
+| OpenRouter | `OpenRouterProvider` | `OpenRouterProviderOptions` | chat completions |
+| DeepSeek | `DeepSeekProvider` | `DeepSeekProviderOptions` | chat completions |
 
 ## Capabilities
 
@@ -63,11 +65,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" });
@@ -86,8 +88,10 @@ interface GeminiProviderOptions {
   apiKey: string;
   model: string;
   backupModels?: string[];
-  config?: Partial<GenerateContentConfig>; // from @google/genai
+  baseUrl?: string;
+  config?: RequestConfig;                  // temperature, topP, maxTokens, stopSequences
   retryConfig?: { timeout?: number; retries?: number };
+  fetchImpl?: typeof fetch;                // scripted wire, for tests
 }
 ```
 
@@ -95,12 +99,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,9 +141,9 @@ 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. |
+| `config` | `RequestConfig` | no | — | Defaults for `temperature`, `topP`, `maxTokens`, `stopSequences`. |
 | `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
 | `retryConfig.retries` | `number` | no | `3` | Total attempts. |
 
@@ -147,7 +152,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 +171,7 @@ interface AnthropicProviderOptions {
   backupModels?: string[];
   config?: Partial<Omit<MessageCreateParamsNonStreaming, "model" | "messages">>;
   retryConfig?: { timeout?: number; retries?: number };
+  client?: Anthropic;                      // pre-configured SDK client override
 }
 ```
 
@@ -173,20 +179,21 @@ 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. |
-| `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. |
+| `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` | `RequestConfig` | no | — | Defaults for `temperature`, `topP`, `maxTokens`, `stopSequences`. `maxTokens` falls back to 4096 if neither it nor `parameters.maxOutputTokens` is set. |
+| `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",
-  config: { max_tokens: 8192 },
+  model: "claude-sonnet-5",
+  config: { maxTokens: 8192 },
 });
 ```
 
@@ -215,7 +222,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 +235,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",
 });
 ```
@@ -278,12 +285,11 @@ 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.
+Many vendors (Groq, Together, Fireworks, …) expose OpenAI-compatible chat-completions APIs. Instead of implementing `AiProvider` from scratch, subclass the exported `OpenAICompatibleProvider` base class — history and tool translation, streaming, tool-call assembly, backup-model fallback, retries and normalized `ProviderError`s all come with it. `OpenAIProvider`, `OpenRouterProvider`, and `DeepSeekProvider` are themselves thin subclasses.
 
-A minimal subclass supplies the configured client, naming, and capabilities:
+A minimal subclass supplies the endpoint, naming, and capabilities:
 
 ```typescript
-import OpenAI from "openai";
 import {
   OpenAICompatibleProvider,
   type ProviderCapabilities,
@@ -299,23 +305,20 @@ export class GroqProvider extends OpenAICompatibleProvider {
     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",
-      }),
+      id: "groq",
+      apiKey: options.apiKey,
+      baseUrl: "https://api.groq.com/openai",
       model: options.model,
+      structuredOutput: "json_schema",
       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).
+That is a complete, working provider. Vendor-specific wire behaviour is not this layer's job any more: it lives in `@providerkit/core`, which the provider classes are thin bindings over. `DeepSeekProvider` is the reference pattern for what is left here — an id, a base URL, the structured-output mode the endpoint actually supports, and its capabilities. To bind a core provider this package does not ship a class for, subclass `ProviderAdapter` directly.
 
 ## Errors
 
@@ -326,10 +329,14 @@ 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, overload and availability, timeouts, and network faults. Deterministic failures — a wrong key, an exhausted balance, an invalid request, a caller's abort — fail fast without burning the retry budget. Classification reads the response BODY before its status, because vendors file the same cause under whatever status they like.
+
+Only failures *before the first chunk* are retried: past that the stream is committed, and a retry would replay text the reader has already seen. The same rule governs the walk to a backup model. `retryConfig.timeout` is the silence deadline — the wait allowed before the first byte, and between any two after it — so a stream that opens and stalls is treated as failed while a long, healthy one is left alone.
+
+A model the endpoint will not serve also walks to the next model on the list, which is what the list is for.
 
 ### `ProviderError`
 
@@ -338,27 +345,23 @@ Terminal failures — after retries and backup models are exhausted — throw th
 ```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
-  }
-}
+type ErrorKind =
+  | 'aborted'      // the caller pressed Stop — never retried
+  | 'timeout'      // our deadline, or a 408
+  | 'network'      // never reached the provider
+  | 'overload'     // theirs and temporary — retry, and try another model
+  | 'rate'         // per-minute throttle — wait, or rotate key or model
+  | 'quota'        // balance or usage window exhausted — waiting will not fix it
+  | 'entitlement'  // the plan never included this API
+  | 'auth'         // the key is wrong, not the request
+  | 'model'        // the model id is not served here
+  | 'context'      // the prompt outgrew the window — send less
+  | 'content'      // safety filter or refusal
+  | 'invalid'      // any other 4xx — a bug in what we sent
+  | 'unknown'
 ```
 
-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

@@ -1,13 +1,13 @@
 /** @intent Minimal agent: one flow, one step, one response.
  *  @teaches createAgent, GeminiProvider, Flow, Step, respond
  *  @readAfter docs/start/02-first-agent.md */
-import { createAgent, GeminiProvider } from "../src";
+import { createAgent, GeminiProvider } from "../src/index.js";
 
 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

@@ -4,7 +4,7 @@
  * Read next: docs/guides/instructions.md
  */
 
-import { createAgent, GeminiProvider } from "../src";
+import { createAgent, GeminiProvider } from "../src/index.js";
 
 if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
 
@@ -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

@@ -1,8 +1,8 @@
 /** @intent Demonstrates step.branches — source-local forks with if, when, and Directive targets.
  *  @teaches BranchEntry, BranchMap, if-only fork, when-only fork, combined if+when, mixed targets
  *  @readAfter docs/guides/branching.md */
-import { createAgent, GeminiProvider } from "../src";
-import type { BranchMap, Directive, FlowOptions, StepOptions } from "../src";
+import { createAgent, GeminiProvider } from "../src/index.js";
+import type { BranchMap, Directive, FlowOptions, StepOptions } from "../src/index.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -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

@@ -1,13 +1,13 @@
 /** @intent Session persistence with MemoryAdapter: implicit default, explicit wiring, and sessionId for cross-turn continuity.
  *  @teaches MemoryAdapter, PersistenceConfig, sessionId, session resumption
  *  @readAfter docs/guides/persistence.md */
-import { createAgent, GeminiProvider, MemoryAdapter } from "../src";
+import { createAgent, GeminiProvider, MemoryAdapter } from "../src/index.js";
 
 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: {

package/examples/tsconfig.json

@@ -1,13 +1,15 @@
 {
     "compilerOptions": {
         "target": "ES2022",
-        "module": "ESNext",
+        "module": "node16",
         "lib": [
             "ES2022",
             "DOM"
         ],
-        "moduleResolution": "bundler",
-        "types": [],
+        "moduleResolution": "node16",
+        "types": [
+            "node"
+        ],
         "strict": true,
         "esModuleInterop": true,
         "skipLibCheck": true,
@@ -15,6 +17,7 @@
         "resolveJsonModule": true,
         "allowSyntheticDefaultImports": true,
         "noEmit": true,
+        "allowImportingTsExtensions": true,
         "paths": {
             "@falai/agent": [
                 "../src/index.ts"