@falai/agent 1.2.8 → 2.0.0

package/docs/reference/step.md

@@ -0,0 +1,339 @@
+---
+title: "Step"
+description: "A node inside a flow — collects data, calls tools, runs computational work, or speaks a verbatim line."
+type: reference
+order: 3
+---
+
+# Step
+
+> **Where this is introduced:** [Architecture](../concepts/architecture.md)
+
+A `Step` is a single node inside a `Flow`. Each step describes what
+the agent does at one point in a conversation: ask a question, collect
+schema fields, call tools, run a hook, branch to another step, or
+speak a verbatim line. Steps are the smallest unit the engine can
+suspend on between user turns.
+
+Steps are normally declared as `StepOptions` objects inside a flow's
+`steps[]` array. The `Step` class itself is rarely instantiated by
+hand — `createAgent` and `Flow.addStep` build instances from the
+options shape below. Validation runs eagerly at construction, so
+misuse surfaces as `FlowConfigurationError` before any turn runs.
+
+A step is one of three mutually exclusive shapes:
+
+- **LLM step** — the default. Has `prompt`, optionally `collect` / `tools` / `instructions`. The engine calls the LLM.
+- **Auto step** — `auto: true`. Pure computation, no LLM call. Only `onEnter`, `prepare`, and `branches` execute. Counts against `maxAutoStepsPerTurn`.
+- **Reply step** — `reply` is set. Renders a verbatim assistant message with no LLM call.
+
+Mixing fields between shapes throws at construction time.
+
+## Signature
+
+```typescript
+interface StepOptions<TContext = unknown, TData = unknown> {
+  id?: string;
+  description?: string;
+
+  // Behaviour
+  prompt?: Template<TContext, TData>;
+  reply?: Template<TContext, TData>;
+  auto?: boolean;
+
+  // Data
+  collect?: (keyof TData)[];
+  requires?: (keyof TData)[];
+
+  // Activation
+  when?: ConditionWhen;                       // AI strings — `string | string[]`
+  if?: ConditionIf<TContext, TData>;          // code predicates — function or array
+  skip?: ConditionIf<TContext, TData>;        // code predicates — OR semantics
+
+  // Surface
+  tools?: (string | Tool<TContext, TData>)[];
+  instructions?: Instruction<TContext, TData>[];
+
+  // Lifecycle (shorthand — returns PrepareResult)
+  prepare?:
+    | string                                  // tool id
+    | Tool<TContext, TData>
+    | ((ctx: TContext, data?: Partial<TData>) =>
+        void | PrepareResult | Promise<void | PrepareResult>);
+  finalize?:
+    | string
+    | Tool<TContext, TData>
+    | ((ctx: TContext, data?: Partial<TData>) =>
+        void | PrepareResult | Promise<void | PrepareResult>);
+
+  // Lifecycle (full — receives HookContext, returns PreDirective / Directive)
+  hooks?: StepLifecycleHooks<TContext, TData>;
+
+  // Routing
+  branches?: BranchMap<TContext, TData>;
+}
+
+interface StepLifecycleHooks<TContext = unknown, TData = unknown> {
+  onEnter?: (ctx: HookContext<TContext, TData>) =>
+    void | PreDirective<TContext, TData> | Promise<void | PreDirective<TContext, TData>>;
+  prepare?: (ctx: HookContext<TContext, TData>) =>
+    void | PreDirective<TContext, TData> | Promise<void | PreDirective<TContext, TData>>;
+  finalize?: (ctx: HookContext<TContext, TData>) =>
+    void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
+  onExit?: (ctx: HookContext<TContext, TData>, reason: ExitReason) =>
+    void | Promise<void>;
+}
+```
+
+## Fields
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `id` | `string` | no | derived from `description` | Stable identifier used by `goToStep`, `branches.then`, and event traces. Must be unique within the flow. |
+| `description` | `string` | no | — | One-line summary surfaced in routing and event traces. Used to derive `id` when omitted. |
+| `prompt` | `Template<TContext, TData>` | no | — | String or function `(params) => string \| Promise<string>`. Becomes the system-prompt instruction for the LLM call this step makes. Mutually exclusive with `auto: true` and `reply`. |
+| `reply` | `Template<TContext, TData>` | no | — | Verbatim assistant message. When set, the engine renders this template and emits it without calling the LLM. Cannot coexist with `prompt`, `collect`, `tools`, `finalize`, or `auto: true`. `stoppedReason: 'reply'`. |
+| `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 (AND semantics). 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. |
+| `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. |
+| `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.
+
+| 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 \| PreDirective` | 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 \| PreDirective` | `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. |
+
+`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` / `PreDirective` surface (`appendPrompt`,
+`injectTools`, `abort`, `reset`).
+
+### Resolution within a step
+
+For one step, the engine walks this sequence per turn:
+
+1. Evaluate `if` (code, AND) and `when` (AI, AND) — 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 `PreDirective`.
+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`.
+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.
+
+## Examples
+
+### Collecting fields with prerequisites and skip
+
+```typescript
+import { createAgent, GeminiProvider } from '@falai/agent';
+
+const agent = createAgent({
+  name: 'BookingBot',
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  schema: {
+    type: 'object',
+    properties: {
+      city: { type: 'string' },
+      checkIn: { type: 'string' },
+      guests: { type: 'integer' },
+    },
+  },
+  flows: [
+    {
+      title: 'Book',
+      requiredFields: ['city', 'checkIn', 'guests'],
+      steps: [
+        {
+          id: 'ask_destination',
+          prompt: 'Find out where and when the user wants to stay.',
+          collect: ['city', 'checkIn'],
+        },
+        {
+          id: 'ask_guests',
+          prompt: 'Confirm how many people are travelling.',
+          collect: ['guests'],
+          requires: ['city', 'checkIn'],
+          // Skip if the user already mentioned a party size
+          skip: ({ data }) => typeof data.guests === 'number',
+        },
+      ],
+    },
+  ],
+});
+```
+
+### Auto step with branches and a reply step
+
+```typescript
+import { createAgent, GeminiProvider } from '@falai/agent';
+
+const agent = createAgent({
+  name: 'EligibilityRouter',
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  schema: {
+    type: 'object',
+    properties: { tier: { type: 'string' } },
+  },
+  flows: [
+    {
+      title: 'Quote',
+      steps: [
+        // Pure computation — no LLM call.
+        {
+          id: 'check_tier',
+          auto: true,
+          requires: ['tier'],
+          branches: [
+            { if: ({ data }) => data.tier === 'enterprise', then: 'concierge' },
+            { when: 'the user already used their free trial', then: 'upsell' },
+            { then: 'self_serve' }, // unconditional fallback
+          ],
+        },
+        // Verbatim message — no LLM call.
+        {
+          id: 'concierge',
+          reply: 'A concierge specialist will reach out within an hour.',
+        },
+        { id: 'upsell', prompt: 'Pitch the paid plan in two short sentences.' },
+        { id: 'self_serve', prompt: 'Walk them through the self-serve form.' },
+      ],
+    },
+  ],
+});
+```
+
+### `when` + `if`, scoped tools and instructions, hook-driven redirect
+
+```typescript
+import { createAgent, GeminiProvider } from '@falai/agent';
+
+const agent = createAgent({
+  name: 'Refunds',
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  schema: {
+    type: 'object',
+    properties: {
+      orderId: { type: 'string' },
+      refundAmount: { type: 'number' },
+    },
+  },
+  flows: [
+    {
+      title: 'Refund',
+      steps: [
+        {
+          id: 'verify',
+          prompt: 'Look up the order and quote a refund amount.',
+          collect: ['orderId', 'refundAmount'],
+          // Run only when both signals agree the user is requesting a refund.
+          when: 'the user is requesting a refund',
+          if: ({ context }) =>
+            (context as { authenticated: boolean }).authenticated,
+          tools: ['lookup_order'],
+          instructions: [
+            { kind: 'must',  prompt: 'State the refund amount before confirming.' },
+            { kind: 'never', prompt: 'Promise refunds without checking eligibility.' },
+          ],
+          hooks: {
+            // Full hook — receives HookContext, returns Directive.
+            finalize: ({ data }) => {
+              if ((data.refundAmount ?? 0) > 500) {
+                return { goToStep: 'manager_review' };
+              }
+            },
+          },
+        },
+        { id: 'manager_review', prompt: 'Hand off to a manager for approval.' },
+      ],
+    },
+  ],
+});
+```
+
+### Top-level `prepare` shorthand vs `hooks.prepare`
+
+```typescript
+// Shorthand — receives (context, data?), returns PrepareResult.
+{
+  id: 'enrich',
+  auto: true,
+  prepare: (context, data) => ({
+    dataUpdate: { customerTier: lookupTier(context, data?.email) },
+  }),
+}
+
+// Full hook — receives HookContext, returns PreDirective.
+{
+  id: 'enrich',
+  auto: true,
+  hooks: {
+    prepare: ({ context, data, dispatch }) => {
+      const tier = lookupTier(context, data?.email);
+      dispatch({ dataUpdate: { customerTier: tier } });
+      if (tier === 'blocked') {
+        return { halt: true, reply: 'This account is on hold.' };
+      }
+    },
+  },
+}
+```
+
+## Errors
+
+The `Step` constructor validates the options shape eagerly. The
+following are thrown synchronously when the agent is built:
+
+- `FlowConfigurationError` — `when` contains a function (functions
+  belong on `if`).
+- `FlowConfigurationError` — `auto: true` is combined with `prompt`,
+  `collect`, `tools`, or `finalize`.
+- `FlowConfigurationError` — `reply` is combined with `prompt`,
+  `collect`, `tools`, `finalize`, or `auto: true`.
+- `FlowConfigurationError` — `branches` is empty (`[]`).
+- `FlowConfigurationError` — a non-last `branches` entry has neither
+  `when` nor `if` (later entries would be unreachable).
+- `FlowConfigurationError` — a `branches[i].then` Directive sets more
+  than one position field (`goTo`, `goToStep`, `complete`, `abort`,
+  `reset`).
+- `FlowConfigurationError` — a `branches[i].then` Directive contains
+  an empty `goTo: {}`.
+
+Runtime errors that surface from a step's hook execution include
+`DataValidationError` (invalid collected data), `ToolExecutionError`
+(a tool inside the step threw or rejected), and
+`ResponseGenerationError` (LLM call failed after retries). See
+[Errors](./errors.md) for handling patterns.
+
+## Related
+
+- [Architecture](../concepts/architecture.md) — where Step fits among the seven primitives
+- [Turn pipeline](../concepts/pipeline.md) — when each step phase fires inside a turn
+- [Flow](./flow.md) — the parent type that contains a step's `steps[]` entry
+- [Tool](./tool.md) — the shape consumed by `tools[]`
+- [Instruction](./instruction.md) — the shape consumed by `instructions[]`
+- [Branches](./branches.md) — the full `BranchEntry` / `BranchMap` contract
+- [Directive](./directive.md) — the post-LLM return type for `hooks.finalize`
+- [PreDirective](./pre-directive.md) — the pre-LLM return type for `hooks.onEnter` and `hooks.prepare`
+- [When and if](../guides/conditions.md) — picking between AI and code conditions
+- [Branching](../guides/branching.md) — adding source-local forks
+- [Flow control](../guides/flow-control.md) — redirecting from a hook

package/docs/reference/tool.md

@@ -0,0 +1,269 @@
+---
+title: "Tool"
+description: "The function-call surface the AI can invoke, with optional metadata for safety, concurrency, validation, and permissions."
+type: reference
+order: 4
+---
+
+# Tool
+
+> **Where this is introduced:** [Add tools](../start/04-add-tools.md)
+
+A `Tool` is a function the agent can invoke during a turn. v2 unifies tools into a single interface — every metadata field is optional. The handler receives a `ToolContext` (with `dispatch` for mid-handler redirection) and may return a plain value or a `ToolResult` (with an optional `directive` for declarative redirection on return).
+
+`Tool.id` is the sole identifier.
+
+## Signature
+
+```typescript
+interface Tool<TContext = any, TData = any, TResult = any> {
+  // Identity
+  id: string;
+  description?: string;
+  parameters?: unknown;
+
+  // Handler
+  handler: ToolHandler<TContext, TData, TResult>;
+
+  // Optional metadata
+  isReadOnly?(input?: Record<string, unknown>): boolean;
+  isConcurrencySafe?(input?: Record<string, unknown>): boolean;
+  isDestructive?(input?: Record<string, unknown>): boolean;
+  interruptBehavior?(): 'cancel' | 'block';
+  maxResultSizeChars?: number;
+
+  validateInput?(
+    input: Record<string, unknown>,
+    context: ToolContext<TContext, TData>,
+  ): Promise<ToolValidationResult> | ToolValidationResult;
+
+  checkPermissions?(
+    input: Record<string, unknown>,
+    context: ToolContext<TContext, TData>,
+  ): Promise<ToolPermissionResult> | ToolPermissionResult;
+}
+
+type ToolHandler<TContext, TData, TResult> = (
+  ctx: ToolContext<TContext, TData>,
+  args?: Record<string, unknown>,
+) =>
+  | Promise<TResult | ToolResult<TResult, TContext, TData>>
+  | TResult
+  | ToolResult<TResult, TContext, TData>;
+
+interface ToolContext<TContext, TData> {
+  context: TContext;
+  data: Partial<TData>;
+  history: Event[];
+  step?: StepRef;
+  metadata?: Record<string, unknown>;
+
+  updateContext(updates: Partial<TContext>): Promise<void>;
+  updateData(updates: Partial<TData>): Promise<void>;
+  getField<K extends keyof TData>(key: K): TData[K] | undefined;
+  setField<K extends keyof TData>(key: K, value: TData[K]): Promise<void>;
+  hasField<K extends keyof TData>(key: K): boolean;
+
+  /** Imperative redirection — emit a directive mid-handler. */
+  dispatch(directive: Directive<TContext, TData>): void;
+}
+
+interface ToolResult<TResultData, TContext, TData> {
+  data?: TResultData;
+  contextUpdate?: Partial<TContext>;
+  dataUpdate?: Partial<TData>;
+  success?: boolean;
+  error?: string;
+  meta?: Record<string, unknown>;
+  /** Declarative redirection — emit a directive on return. */
+  directive?: Directive<TContext, TData>;
+}
+
+interface ToolValidationResult {
+  valid: boolean;
+  error?: string;
+  correctedInput?: Record<string, unknown>;
+}
+
+interface ToolPermissionResult {
+  allowed: boolean;
+  reason?: string;
+  canOverride?: boolean;
+}
+```
+
+## Fields
+
+### `Tool`
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `id` | `string` | yes | — | Unique identifier. The AI references this name when calling the tool. There is no separate `name` field. |
+| `handler` | `ToolHandler` | yes | — | The function the AI invokes. Receives `ctx` and optional `args`. |
+| `description` | `string` | no | — | Free-form description for AI tool discovery. |
+| `parameters` | `unknown` | no | — | Argument schema (provider-specific shape; pass through to the LLM). |
+| `isReadOnly` | `(input?) => boolean` | no | — | Returns `true` when the call has no side effects. Enables result caching and concurrency. |
+| `isConcurrencySafe` | `(input?) => boolean` | no | — | Returns `true` when this call may run in parallel with other concurrent-safe calls. |
+| `isDestructive` | `(input?) => boolean` | no | — | Returns `true` for irreversible operations. Surfaces to confirmation UIs. |
+| `interruptBehavior` | `() => 'cancel' \| 'block'` | no | `'cancel'` | How the tool reacts to abort signals. `'block'` waits for natural completion. |
+| `maxResultSizeChars` | `number` | no | — | Truncation cap for the serialized result, before history compaction. |
+| `validateInput` | `(input, ctx) => ToolValidationResult` | no | — | Pre-execution input check. May return `correctedInput` to repair the call. |
+| `checkPermissions` | `(input, ctx) => ToolPermissionResult` | no | — | Pre-execution gate. When `allowed: false`, the handler is **not** invoked. |
+
+### `ToolContext`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `context` | `TContext` | Ambient app data (user, env, services). |
+| `data` | `Partial<TData>` | Everything collected so far across the conversation. |
+| `history` | `Event[]` | Native multi-turn history (read-only). |
+| `step` | `StepRef \| undefined` | Identifies the current flow/step when the tool runs inside a flow. |
+| `metadata` | `Record<string, unknown> \| undefined` | Free-form per-call metadata. |
+| `updateContext` | `(updates) => Promise<void>` | Shallow-merge into `context`. Triggers context lifecycle hooks. |
+| `updateData` | `(updates) => Promise<void>` | Shallow-merge into `data`. Triggers data lifecycle hooks. |
+| `getField` / `setField` / `hasField` | `(key) => …` | Typed accessors over `data`. |
+| `dispatch` | `(directive) => void` | Imperative directive emit. May be called multiple times; emissions are merged by Algorithm 4 alongside other tool/hook directives this turn. |
+
+### `ToolResult`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `data` | `TResultData` | The value the AI sees as the tool result. |
+| `contextUpdate` | `Partial<TContext>` | Shallow-merged into `context` after the call. |
+| `dataUpdate` | `Partial<TData>` | Shallow-merged into `data` after the call. |
+| `success` | `boolean` | When `false`, the executor treats this as a failed call and surfaces `error`. |
+| `error` | `string` | Failure message when `success === false`. |
+| `meta` | `Record<string, unknown>` | Free-form metadata (stored on the tool event). |
+| `directive` | `Directive` | Declarative redirection. Equivalent to calling `ctx.dispatch(directive)` once. |
+
+### `ToolValidationResult`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `valid` | `boolean` | `false` blocks execution and surfaces `error` to the AI. |
+| `error` | `string` | Why validation failed. |
+| `correctedInput` | `Record<string, unknown>` | When present, the executor retries with this input instead of the original. |
+
+### `ToolPermissionResult`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `allowed` | `boolean` | `false` blocks execution; the handler is never called. |
+| `reason` | `string` | Why permission was denied. |
+| `canOverride` | `boolean` | Hint to UIs: the user may grant a one-time override. |
+
+## Examples
+
+### 1. Imperative redirection with `ctx.dispatch`
+
+A tool that runs mid-flow and decides the rest of the turn is moot — for example, an eligibility check that fails and should jump straight to a denial flow.
+
+```typescript
+import type { Tool } from "@falai/agent";
+
+type Ctx = { userId: string };
+type Data = { country: string };
+
+export const checkEligibility: Tool<Ctx, Data, { ok: boolean }> = {
+  id: "check_eligibility",
+  description: "Verify the user can proceed with booking.",
+  isReadOnly: () => true,
+  async handler(ctx) {
+    const ok = await isEligible(ctx.context.userId, ctx.data.country);
+
+    if (!ok) {
+      // Imperative: stop reasoning, jump to the denial flow.
+      ctx.dispatch({
+        goTo: "denial",
+        reply: "Sorry — you're not eligible for this service.",
+      });
+      return { ok: false };
+    }
+
+    return { ok: true };
+  },
+};
+```
+
+### 2. Declarative redirection with `ToolResult.directive`
+
+The same tool, written as a value-returning handler. The directive rides back on the result and is merged identically.
+
+```typescript
+export const checkEligibility: Tool<Ctx, Data, { ok: boolean }> = {
+  id: "check_eligibility",
+  description: "Verify the user can proceed with booking.",
+  isReadOnly: () => true,
+  async handler(ctx) {
+    const ok = await isEligible(ctx.context.userId, ctx.data.country);
+
+    if (!ok) {
+      return {
+        data: { ok: false },
+        directive: {
+          goTo: "denial",
+          reply: "Sorry — you're not eligible for this service.",
+        },
+      };
+    }
+
+    return { data: { ok: true } };
+  },
+};
+```
+
+### 3. Validation, permissions, and write semantics
+
+A destructive tool that validates its input, checks permissions, and writes back into `data`.
+
+```typescript
+export const bookHotel: Tool<Ctx, Data, { id: string }> = {
+  id: "book_hotel",
+  description: "Reserve a hotel for the collected dates.",
+  isDestructive: () => true,
+  isConcurrencySafe: () => false,
+  maxResultSizeChars: 2_000,
+
+  validateInput(input) {
+    if (typeof input.nights !== "number" || input.nights < 1) {
+      return { valid: false, error: "`nights` must be a positive integer." };
+    }
+    return { valid: true };
+  },
+
+  checkPermissions(_input, ctx) {
+    if (!ctx.context.userId) {
+      return { allowed: false, reason: "Sign in required.", canOverride: false };
+    }
+    return { allowed: true };
+  },
+
+  async handler(ctx, args) {
+    const id = await api.book(ctx.context.userId, args);
+    return {
+      data: { id },
+      dataUpdate: { bookingId: id },
+      success: true,
+    };
+  },
+};
+```
+
+## Errors
+
+Misuse surfaces as typed errors from the executor:
+
+- `ToolExecutionError` — handler threw, returned `success: false`, exceeded `maxResultSizeChars` after compaction, or the tool was invoked with arguments that fail `validateInput` and cannot be corrected.
+- `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.
+
+## Related
+
+- [Add tools](../start/04-add-tools.md) — tutorial that introduces this type.
+- [Architecture](../concepts/architecture.md) — where Tool fits among the seven primitives.
+- [Directives](../concepts/directives.md) — what `dispatch` and `directive` emit.
+- [Directive](./directive.md) — the flat shape used by both forms above.
+- [Flow control](../guides/flow-control.md) — recipes for redirecting from tools and hooks.
+- [Errors](./errors.md) — `ToolExecutionError` format contract.

package/docs/start/01-install.md

@@ -0,0 +1,81 @@
+---
+title: "Install"
+description: "Install @falai/agent, set up your environment, and grab a provider key."
+type: tutorial
+order: 1
+---
+
+# Install
+
+Before you write a flow or define a schema, you need `@falai/agent` in your project and a provider key in your environment. This page handles both. By the end you will have a verified provider instance and a clean slate for the agent you build on the next page.
+
+## Prerequisites
+
+- Node.js **18+** or Bun **1.0+**
+- A package manager (Bun, npm, pnpm, or yarn)
+- An API key from at least one provider — see [Provider keys](#provider-keys) below
+
+## Install the package
+
+```bash
+bun add @falai/agent
+```
+
+Or, with another package manager:
+
+```bash
+npm install @falai/agent
+# or
+pnpm add @falai/agent
+# or
+yarn add @falai/agent
+```
+
+The package ships ESM and CJS entry points and bundles its TypeScript types — there is no `@types/*` companion to install.
+
+## Set up your environment
+
+Create a `.env` file at the root of your project. You only need a key for the provider you plan to use.
+
+```bash
+# .env
+GEMINI_API_KEY=your-gemini-key
+OPENAI_API_KEY=your-openai-key
+ANTHROPIC_API_KEY=your-anthropic-key
+OPENROUTER_API_KEY=your-openrouter-key   # optional broker
+```
+
+Load the file before your agent code runs. Bun reads `.env` automatically; with Node, pass `--env-file=.env` (Node 20+) or use your tool of choice.
+
+## Provider keys
+
+Pick one provider to start. The tutorial uses Gemini by default because it has the fastest free tier; swap to another vendor by changing one constructor in [Your first agent](./02-first-agent.md).
+
+- **Google Gemini** — [Gemini Studio](https://aistudio.google.com/apikey) (`GEMINI_API_KEY`)
+- **OpenAI** — [OpenAI Platform](https://platform.openai.com/api-keys) (`OPENAI_API_KEY`)
+- **Anthropic** — [Anthropic Console](https://console.anthropic.com/settings/keys) (`ANTHROPIC_API_KEY`)
+- **OpenRouter** *(optional broker for many vendors behind one key)* — [OpenRouter](https://openrouter.ai/keys) (`OPENROUTER_API_KEY`)
+
+Any one of these is enough to finish the tutorial. The [Providers reference](../reference/providers.md) covers options like `backupModels` and per-vendor `config`.
+
+## Verify the install
+
+Drop this into `src/check.ts` and run it. If it prints `Provider ready`, you are set.
+
+```typescript
+import { GeminiProvider } from "@falai/agent";
+
+const provider = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY!,
+  model: "models/gemini-2.5-pro",
+});
+
+console.log("Provider ready:", provider.constructor.name);
+```
+
+```bash
+bun run src/check.ts
+# Provider ready: GeminiProvider
+```
+
+**Next:** [Your first agent](./02-first-agent.md)