@falai/agent 1.2.8 → 2.0.0

package/docs/reference/branches.md

@@ -0,0 +1,241 @@
+---
+title: "Branches"
+description: "Explicit source-local forks declared on a step, evaluated in order with code-first short-circuit."
+type: reference
+order: 8
+---
+
+# Branches
+
+> **Where this is introduced:** [Branching](../guides/branching.md)
+
+A **branch** is an explicit, source-local fork: from this step, here are the possible next steps and how each one is chosen. `step.branches` is an array of `BranchEntry` evaluated in declaration order — the first entry whose conditions pass wins, and its `then` resolves to a step id, a flow id, or a full `Directive`.
+
+Branches sit between code and AI. Use `if` (a function predicate) to skip LLM evaluation when the choice is purely a function of `data` and `context`. Use `when` (an AI-evaluated string) for choices that need intent classification. Combine both when both must agree — `if` runs first, free; `when` is only evaluated if `if` passes, saving tokens.
+
+Branches resolve **after** the step's post-LLM phase (tool execution, `finalize`) and **before** linear successor selection. They coexist with the implicit-fork pattern (multiple successor steps each carrying their own `step.when`); when `branches` is absent or no entry matches, resolution falls through to that path unchanged.
+
+## Signature
+
+```typescript
+interface BranchEntry<TContext = unknown, TData = unknown> {
+  /** AI-evaluated condition. String or array of strings (AND semantics). */
+  when?: string | string[];
+
+  /** Code predicate. Function or array of functions (AND semantics). */
+  if?:
+    | BranchPredicate<TContext, TData>
+    | BranchPredicate<TContext, TData>[];
+
+  /**
+   * Where to go when this entry matches.
+   * - String matching a step id in the current flow → enter that step.
+   * - String matching a flow id/title → treated as { goTo: <string> }.
+   * - Directive object → applied directly.
+   */
+  then: string | Directive<TContext, TData>;
+
+  /** Optional label for event traces and flow visualization. */
+  label?: string;
+}
+
+type BranchMap<TContext = unknown, TData = unknown> =
+  Array<BranchEntry<TContext, TData>>;
+
+type BranchPredicate<TContext = unknown, TData = unknown> = (
+  ctx: BranchPredicateContext<TContext, TData>,
+) => boolean | Promise<boolean>;
+
+interface BranchPredicateContext<TContext = unknown, TData = unknown> {
+  /** Collected data (partial — null-check fields not in `requires`). */
+  data: Partial<TData>;
+  /** Agent-level context. */
+  context: TContext;
+  /** Full session state. */
+  session: SessionState<TData>;
+  /** Conversation history as events. */
+  history: Event[];
+}
+```
+
+## Fields
+
+### `BranchEntry`
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `when` | `string \| string[]` | no | — | AI-evaluated condition. Reuses the same machinery as `step.when`. Only evaluated if `if` passes (or is absent). Costs LLM tokens. |
+| `if` | `BranchPredicate \| BranchPredicate[]` | no | — | Code predicate. Free to evaluate. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if all `if` predicates pass. |
+| `then` | `string \| Directive` | yes | — | Target. See [Resolution of `then`](#resolution-of-then) below. |
+| `label` | `string` | no | — | Optional label surfaced in event traces and flow visualization. |
+
+An entry with neither `when` nor `if` is an unconditional fallback and is only legal as the **last** entry in the array.
+
+### `BranchMap`
+
+A `BranchMap` is just `Array<BranchEntry>`. Entries are evaluated top-to-bottom; the first match wins. There is no separate object-syntax form — keeping the shape an array means declaration order and source position are the same thing.
+
+### `BranchPredicateContext`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `data` | `Partial<TData>` | Collected data so far. Predicates must null-check any field not declared in the source step's `requires`. Fields covered by `requires` are guaranteed present when the predicate runs. |
+| `context` | `TContext` | Agent-level context (user, env, services). |
+| `session` | `SessionState<TData>` | Full session state — current flow, current step, history. |
+| `history` | `Event[]` | Conversation history as events (read-only). |
+
+## Resolution
+
+### Order
+
+For each entry in declaration order:
+
+1. If the entry has neither `when` nor `if`, it matches unconditionally (only legal as the last entry).
+2. If `if` is set, evaluate every predicate. If any returns falsy, skip the entry — `when` is **not** evaluated.
+3. If `when` is set, evaluate the AI condition. If it returns falsy, skip the entry.
+4. Otherwise the entry matches; return its `then`.
+
+If no entry matches, branches return `undefined` and resolution falls through to linear `nextStep` / AI step selection. This is the same fall-through used when `branches` is omitted entirely.
+
+The code-first ordering is deliberate: `if` is free, `when` costs tokens. Running `if` first short-circuits the AI call when the predicate already disqualifies the entry.
+
+### Resolution of `then`
+
+`then` accepts three forms, resolved in this order:
+
+1. **String matching a step id in the current flow** → enter that step directly.
+2. **String matching a flow id or title** → treated as `applyDirective({ goTo: then })`.
+3. **`Directive` object** → applied via `applyDirective(then)`.
+
+When a string matches both a local step id and a flow id (rare), the local step wins — step ids are scoped to the current flow.
+
+A bare string **never** resolves to a step in another flow, even if that step id is globally unique. To target a step in a different flow, use the `Directive` form: `then: { goToStep: { step: 'foo', flow: 'OtherFlow' } }`. This keeps the string lookup unambiguous and makes cross-flow intent explicit at the call site.
+
+## Examples
+
+### 1. Code-only fork (zero LLM cost)
+
+A routing step that picks a path based purely on collected data. Combined with `auto: true`, the entire decision happens without an LLM call.
+
+```typescript
+flow({
+  id: "plan_routing",
+  steps: [
+    {
+      id: "route_by_plan",
+      auto: true,
+      branches: [
+        { if: ({ data }) => data.plan === "enterprise", then: "enterprise_path", label: "enterprise" },
+        { if: ({ data }) => data.plan === "pro",        then: "pro_path",        label: "pro" },
+        { then: "free_path" }, // unconditional fallback (last entry)
+      ],
+    },
+    { id: "enterprise_path", prompt: "A specialist will reach out." },
+    { id: "pro_path",        prompt: "Set up your pro account." },
+    { id: "free_path",       prompt: "Welcome to the free tier." },
+  ],
+});
+```
+
+### 2. Mixed targets (step id, flow id, full Directive)
+
+One branch step covering local navigation, cross-flow handoff, cross-flow step targeting, and completion in a single source-local list.
+
+```typescript
+flow({
+  id: "router",
+  steps: [
+    {
+      id: "classify",
+      prompt: "How can I help?",
+      branches: [
+        // Step id in the current flow.
+        { if: ({ data }) => data.tier === "enterprise", then: "enterprise_path" },
+
+        // Flow id — sugar for { goTo: "CancellationFlow" }.
+        { when: "user wants to cancel", then: "CancellationFlow" },
+
+        // Full Directive — cross-flow with data carry.
+        {
+          when: "user is asking about a refund",
+          then: { goTo: { flow: "Refund", data: { source: "classify" } } },
+        },
+
+        // Cross-flow step reference (Directive required for cross-flow steps).
+        {
+          if: ({ data }) => data.escalate === true,
+          then: { goToStep: { step: "priority_intake", flow: "Escalation" } },
+        },
+
+        // Directive with a non-position field (state write + completion).
+        { if: ({ data }) => data.shouldComplete === true, then: { complete: true } },
+
+        // Unconditional fallback.
+        { then: "default_path" },
+      ],
+    },
+    { id: "enterprise_path", prompt: "..." },
+    { id: "default_path",    prompt: "..." },
+  ],
+});
+```
+
+### 3. Combined `if` + `when` (token-saving short-circuit)
+
+When both fields are set on the same entry, `if` runs first. `when` is only evaluated if `if` passes — so the LLM call only happens when the predicate hasn't already disqualified the branch.
+
+```typescript
+flow({
+  id: "pricing",
+  steps: [
+    {
+      id: "pricing_routing",
+      branches: [
+        {
+          // Free predicate runs first; AI condition only fires when it passes.
+          if: ({ data, context }) =>
+            data.country === "US" && context.featureFlags.enableUsPricing,
+          when: "user is asking about pricing",
+          then: "us_pricing",
+        },
+        {
+          when: "user is asking about pricing",
+          then: "global_pricing",
+        },
+        { then: "general_help" }, // fallback
+      ],
+    },
+    { id: "us_pricing",     prompt: "Here is US pricing." },
+    { id: "global_pricing", prompt: "Here is global pricing." },
+    { id: "general_help",   prompt: "I can help with that." },
+  ],
+});
+```
+
+## Errors
+
+Misuse of `branches` surfaces as `FlowConfigurationError` at flow construction or at first evaluation:
+
+- **Empty array.** `branches: []` is rejected — it signals a missing target.
+- **Unreachable fallback.** A non-last entry with neither `when` nor `if` is rejected (later entries would never run).
+- **Unknown step id.** A `then` string that matches neither a step in the current flow nor any flow id throws when first evaluated.
+- **Malformed Directive.** A `then` Directive with multiple position fields set, or an empty `goTo: {}`, fails the same `flow.validate(directive)` rules that apply to all directives.
+
+A `BranchPredicate` that throws or rejects is caught by the resolver, logged at `ERROR`, and treated as a falsy result for that entry — resolution proceeds to the next entry. Branch predicate errors never corrupt the session; the worst case degrades to fall-through (linear / AI step selection).
+
+## Coexistence with implicit forks
+
+The implicit-fork pattern (multiple successor steps each carrying their own `step.when`) is unchanged in v2. Both forms are first-class:
+
+- **Implicit** — fork by listing multiple steps with their own `when`. Reads as a linear flow that occasionally skips. Use when the fork is incidental.
+- **Explicit (`branches`)** — fork declared at the source step, all paths visible in one list. Reads as "this step is a routing point with N options." Use when the fork is the point.
+
+When both are present on the same step, branches take precedence: if a branch entry matches, the linear chain is bypassed. If branches return `undefined`, the linear chain runs.
+
+## Related
+
+- [Branching](../guides/branching.md) — the guide that introduces this primitive end-to-end.
+- [Step](./step.md) — where the `branches` field lives.
+- [Directive](./directive.md) — the flat shape `then` accepts as its third form.
+- [Conditions](../guides/conditions.md) — the `when` (AI) vs `if` (code) split shared with `Step` and `Flow`.
+- [Turn pipeline](../concepts/pipeline.md) — where branch resolution sits in the per-turn sequence.

package/docs/reference/create-agent.md

@@ -0,0 +1,186 @@
+---
+title: "createAgent"
+description: "Factory function that constructs an Agent from a single options object."
+type: reference
+order: 1
+---
+
+# createAgent
+
+> **Where this is introduced:** [Your first agent](../start/02-first-agent.md)
+
+`createAgent` is the level-1 entry point for constructing an `Agent`. It is
+syntactic sugar over `new Agent(options)` and accepts the same `AgentOptions`
+shape. Generic inference flows from `schema` through every `flows[].steps[].collect`
+reference, so the type of `session.data` and tool handler arguments is derived
+once and propagates everywhere.
+
+## Signature
+
+```typescript
+function createAgent<TContext = unknown, TData = unknown>(
+  options: AgentOptions<TContext, TData>
+): Agent<TContext, TData>;
+
+interface AgentOptions<TContext = unknown, TData = unknown> {
+  name: string;
+  goal?: string;
+  persona?: Template<TContext>;
+  debug?: boolean;
+  context?: TContext;
+  contextProvider?: ContextProvider<TContext>;
+  hooks?: ContextLifecycleHooks<TContext, TData>;
+  provider: AiProvider;
+  schema?: StructuredSchema;
+  initialData?: Partial<TData>;
+  terms?: Term<TContext, TData>[];
+  instructions?: Instruction<TContext, TData>[];
+  tools?: Tool<TContext, TData, unknown>[];
+  flows?: FlowOptions<TContext, TData>[];
+  signals?: Signal<TContext, TData, unknown>[];
+  signalBatchSize?: number;
+  persistence?: PersistenceConfig<TData>;
+  knowledgeBase?: Record<string, unknown>;
+  flowSwitchMargin?: number;
+  maxAutoStepsPerTurn?: number;
+  maxDirectiveChain?: number;
+  compaction?: AgentCompactionConfig;
+  promptCache?: PromptCacheConfig;
+  routerMode?: 'ai';
+  sessionId?: string;
+  session?: SessionState;
+}
+```
+
+## Fields
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `name` | `string` | yes | — | Display name surfaced in logs and prompt sections. |
+| `goal` | `string` | no | — | One-line objective rendered into the system prompt. |
+| `persona` | `Template<TContext>` | no | — | Who the agent is and how it communicates — role, tone, and self-concept. Rendered into the system prompt. |
+| `provider` | `AiProvider` | yes | — | Strategy instance: `GeminiProvider`, `OpenAIProvider`, `AnthropicProvider`, or `OpenRouterProvider`. |
+| `schema` | `StructuredSchema` | no | — | Single source of truth for `TData`. Every `collect` key in every step must reference a property defined here. |
+| `initialData` | `Partial<TData>` | no | — | Pre-populates `session.data` when the agent is constructed. |
+| `flows` | `FlowOptions<TContext, TData>[]` | no | `[]` | Conversation flows. May also be added later via `agent.createFlow(...)`. |
+| `tools` | `Tool<TContext, TData, unknown>[]` | no | `[]` | Agent-scoped tools. Each tool's `Tool.id` must be unique. |
+| `instructions` | `Instruction<TContext, TData>[]` | no | `[]` | Behavioral statements discriminated by `kind: 'must' \| 'never' \| 'should'`. Scoped at agent, flow, or step level. |
+| `terms` | `Term<TContext, TData>[]` | no | `[]` | Domain glossary entries inlined into the prompt. |
+| `signals` | `Signal<TContext, TData, unknown>[]` | no | `[]` | Typed event detectors that run before/after the LLM turn. |
+| `signalBatchSize` | `number` | no | `10` | Maximum signals per batched classifier call. Throws `FlowConfigurationError` if not a positive integer. |
+| `context` | `TContext` | no | — | Static ambient data (user info, env, etc.) available to every hook and tool. |
+| `contextProvider` | `ContextProvider<TContext>` | no | — | Async context loader. Use instead of `context` when ambient data must be fetched per turn. |
+| `hooks` | `ContextLifecycleHooks<TContext, TData>` | no | — | `beforeRespond`, `onContextUpdate`, `onDataUpdate` — fire around every turn. |
+| `persistence` | `PersistenceConfig<TData>` | no | in-memory | Session storage. Omit for `MemoryAdapter`. |
+| `knowledgeBase` | `Record<string, unknown>` | no | — | Arbitrary JSON inlined into the prompt as background knowledge. |
+| `flowSwitchMargin` | `number` | no | `15` | Margin (0–100) the best alternative flow must exceed the current flow's score by before switching. Higher values make the agent stickier. |
+| `maxAutoStepsPerTurn` | `number` | no | `10` | Cap on consecutive `auto: true` steps per turn. Throws `FlowConfigurationError` when exceeded. |
+| `maxDirectiveChain` | `number` | no | `10` | Cap on chained directives per turn (e.g., `goTo` → `onEnter` emits `goTo` → …). Throws `FlowConfigurationError` when exceeded. |
+| `compaction` | `AgentCompactionConfig` | no | — | History compaction config: `maxTokens`, `compactionThreshold`, `preserveRecentCount`, `maxToolResultChars`. |
+| `promptCache` | `PromptCacheConfig` | no | `{ enabled: true }` | Controls prompt-section memoization across turns. |
+| `debug` | `boolean` | no | `false` | Enables `loglevel` debug output. |
+| `routerMode` | `'ai'` | no | `'ai'` | Reserved for future router strategies. Any non-`'ai'` value throws `NotImplementedError` at construction. |
+| `sessionId` | `string` | no | — | Auto-loads the session with this id from the configured adapter. |
+| `session` | `SessionState` | no | — | Pre-built session passed in for convenience methods. |
+
+## Examples
+
+### Minimal agent
+
+```typescript
+import { createAgent, GeminiProvider } from '@falai/agent';
+
+const agent = createAgent({
+  name: 'Greeter',
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  schema: {
+    type: 'object',
+    properties: { name: { type: 'string' } },
+  },
+  flows: [
+    {
+      title: 'Greet',
+      steps: [
+        { id: 'ask_name', prompt: 'Ask for the user\'s name.', collect: ['name'] },
+        { id: 'greet', prompt: 'Greet them by name.', requires: ['name'] },
+      ],
+    },
+  ],
+});
+
+const response = await agent.respond('Hi, I\'m Ada.');
+console.log(response.message);
+```
+
+### Tools, instructions, and persistence
+
+```typescript
+import { createAgent, GeminiProvider, MemoryAdapter } from '@falai/agent';
+
+const agent = createAgent({
+  name: 'BookingBot',
+  persona: 'Concise concierge. Always confirms dates before booking.',
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  schema: {
+    type: 'object',
+    properties: {
+      city: { type: 'string' },
+      checkIn: { type: 'string' },
+    },
+  },
+  instructions: [
+    { kind: 'must', prompt: 'Validate dates are in the future.' },
+    { kind: 'never', prompt: 'Promise rates you have not looked up.' },
+  ],
+  tools: [
+    {
+      id: 'book_hotel',
+      description: 'Book a hotel for the collected city and date.',
+      parameters: {
+        type: 'object',
+        properties: {
+          city: { type: 'string' },
+          checkIn: { type: 'string' },
+        },
+        required: ['city', 'checkIn'],
+      },
+      handler: async (ctx, args) => {
+        const ref = await reserve(args.city, args.checkIn);
+        return { content: `Booked ${ref}.` };
+      },
+    },
+  ],
+  flows: [
+    {
+      title: 'Book',
+      requiredFields: ['city', 'checkIn'],
+      steps: [
+        { id: 'ask', prompt: 'Collect city and check-in date.', collect: ['city', 'checkIn'] },
+        { id: 'confirm', prompt: 'Confirm and call book_hotel.', requires: ['city', 'checkIn'] },
+      ],
+    },
+  ],
+  persistence: { adapter: new MemoryAdapter() },
+});
+```
+
+## Errors
+
+`createAgent` runs the same construction-time validation as `new Agent(...)`.
+The following typed errors may be thrown:
+
+- `FlowConfigurationError` — duplicate flow ids or titles, duplicate signal ids, duplicate tool ids, invalid `signalBatchSize`, invalid signal `extract` schema, a step's `collect` references a key not defined in `schema`, a flow's `requiredFields`/`optionalFields` references an unknown schema key, or an unresolvable branch `then` target.
+- `NotImplementedError` — `routerMode` set to anything other than `'ai'`.
+
+Validation errors during a turn (not construction) — `DataValidationError`,
+`ToolExecutionError`, `ResponseGenerationError` — surface from
+`agent.respond(...)` and are documented on [Errors](./errors.md).
+
+## Related
+
+- [Architecture](../concepts/architecture.md) — the seven primitives and how they fit together
+- [Your first agent](../start/02-first-agent.md) — the tutorial that introduces `createAgent`
+- [Flow](./flow.md) — the `flows[]` entry shape
+- [Tool](./tool.md) — the `tools[]` entry shape
+- [Instruction](./instruction.md) — the `instructions[]` entry shape
+- [Errors](./errors.md) — typed error classes thrown at construction and at runtime

package/docs/reference/directive.md

@@ -0,0 +1,243 @@
+---
+title: "Directive"
+description: "Flat shape returned by tools and hooks to write state, redirect the conversation, or speak verbatim."
+type: reference
+order: 6
+---
+
+# Directive
+
+> **Where this is introduced:** [Directives](../concepts/directives.md)
+
+A `Directive<TContext, TData>` is the single shape any tool, hook, or branch returns when it wants to write state, change position, or speak verbatim. It is a **flat object literal** — not a discriminated union, not a class, not a builder. Every field is optional. Every directive is plain JSON-serializable data (PreDirective adds non-serializable extensions; see [PreDirective](./pre-directive.md)).
+
+A directive carries up to four orthogonal payloads:
+
+- **One position field** — `goTo`, `goToStep`, `complete`, `abort`, or `reset`. Where to send the conversation. Mutually exclusive: at most one per directive.
+- **State writes** — `dataUpdate` and/or `contextUpdate`. Shallow-merged into `session.data` and `session.context` before the next phase runs.
+- **A verbatim reply** — `reply`. The literal assistant utterance, bypassing the LLM.
+- **Per-position observability** — `reason` strings inside the object forms of position fields, surfaced in event traces and the directive chain log.
+
+Multiple directives emitted during the same turn are collected onto the per-turn bus and merged by Algorithm 4 (see [Merge rules](#merge-rules) below).
+
+## Signature
+
+```typescript
+interface Directive<TContext = unknown, TData = unknown> {
+  // ── Position fields (mutually exclusive: at most one) ────────────
+  goTo?:
+    | string
+    | {
+        flow?: string;
+        step?: string;
+        data?: Partial<TData>;
+        reason?: string;
+        carry?: "preserve" | "reset";
+      };
+
+  goToStep?:
+    | string
+    | { step: string; flow?: string; data?: Partial<TData>; reason?: string };
+
+  complete?:
+    | true
+    | { next?: Directive<TContext, TData>; reason?: string };
+
+  abort?:
+    | string
+    | { reason: string; clearSession?: boolean };
+
+  reset?:
+    | true
+    | { step?: string; clearData?: boolean; reason?: string };
+
+  // ── Verbatim utterance ───────────────────────────────────────────
+  reply?: string;
+
+  // ── State writes (shallow-merged, both phases) ───────────────────
+  contextUpdate?: Partial<TContext>;
+  dataUpdate?: Partial<TData>;
+}
+```
+
+## Fields
+
+### Position fields
+
+Exactly **zero or one** position field may be set per directive. Setting two or more is a runtime configuration error (see [Errors](#errors)). When zero are set, the directive is purely a state write or a verbatim reply.
+
+| Field | Shorthand | Object form | Notes |
+|-------|-----------|-------------|-------|
+| `goTo` | `string` (flow id / title) | `{ flow?, step?, data?, reason?, carry? }` | Jump to another flow. The string form is sugar for `{ flow: <string> }`. `carry: 'reset'` clears the destination flow's `requiredFields`/`optionalFields` on entry; `carry: 'preserve'` (default) preserves them. `data` is shallow-merged into `session.data` before entry. |
+| `goToStep` | `string` (step id in the current flow) | `{ step, flow?, data?, reason? }` | Jump to a step. The bare string form targets the current flow only — for cross-flow steps, use the object form with `flow`. |
+| `complete` | `true` | `{ next?, reason? }` | Mark the current flow complete. `next` is a chained `Directive` applied immediately after completion (e.g. transition to a follow-up flow). Equivalent to satisfying all `requiredFields`. |
+| `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.
+
+### State writes
+
+| Field | Type | Phase | Notes |
+|-------|------|-------|-------|
+| `dataUpdate` | `Partial<TData>` | both | Shallow-merged into `session.data`. Triggers `flow.hooks.onDataUpdate` and `Agent` data hooks. Across multiple emitters this turn, key collisions resolve last-write-wins. |
+| `contextUpdate` | `Partial<TContext>` | both | Shallow-merged into `session.context`. Triggers `flow.hooks.onContextUpdate` and `Agent` context hooks. Last-write-wins on key collision. |
+
+Shallow-merge means each top-level key is replaced wholesale. To update a nested object, read it from `data`/`context`, merge in code, and write back the full sub-object. Deep merge is intentionally not provided — it would silently disagree with TypeScript's `Partial<>` shape.
+
+### `reply`
+
+`reply: string` is the verbatim assistant utterance. When set, the LLM call is skipped this turn and the string is emitted as the assistant message exactly as written. Templating is not applied — `reply` is the rendered output.
+
+`reply` co-validates with two fields:
+
+- **`abort`** — co-existence is rejected at validation. Aborted conversations cannot deliver a reply.
+- **`halt`** (PreDirective only) — when both are set, `reply` becomes the assistant output and the turn ends with `stoppedReason: 'reply'`. When `halt` is set without `reply`, the turn ends with `stoppedReason: 'halt'` and an empty assistant message.
+
+Across multiple emitters this turn, `reply` is **last-wins** — the most recent emission overrides earlier ones, with a `DEBUG` log when more than one emitter set it.
+
+## Merge rules
+
+Directives emitted during one turn — by tools (return value or `ctx.dispatch`), prepare/finalize hooks, onEnter/onComplete hooks, and signal handlers — are collected onto a per-phase bus and merged into a single applied directive. The bus runs in two phases (pre-LLM and post-LLM); merge rules are identical for both.
+
+| Field group | Merge rule |
+|-------------|-----------|
+| Position fields (`goTo`, `goToStep`, `complete`, `abort`, `reset`) | **Winner-takes-all by precedence:** `abort > complete > goTo / goToStep > reset`. Among entries of the same precedence, last emission wins. A `DEBUG` log records all losers. |
+| `reply` | **Last-wins.** Most recent non-empty `reply` overrides earlier ones. `DEBUG` log when more than one was set. |
+| `dataUpdate`, `contextUpdate` | **Shallow-merged across all emitters.** Last-write-wins on key collision. Always applied — never overridden by position fields. |
+| `appendPrompt` (PreDirective) | **Concatenated** in emission order. |
+| `injectTools` (PreDirective) | **Concatenated, then deduped by `Tool.id`** (last definition wins). |
+| `halt` (PreDirective) | **Logical-OR.** Any emitter setting `halt: true` halts the turn. |
+
+The full algorithm is implemented by `flow.merge(a, b)`. See [`flow` namespace](#flow-namespace) below.
+
+> Branches **do not** participate in this bus. When a branch's `then` resolves to a `Directive`, it is applied via `applyDirective` directly, bypassing merge. The bus winner (if any) wins over branch evaluation: if the post-LLM bus produced a position field, branches don't run on that turn. See [Branches](./branches.md).
+
+## `flow` namespace
+
+The `flow` namespace exports three runtime helpers for working with directives. There are no constructor builders — directives are plain object literals.
+
+```typescript
+import { flow } from "@falai/agent";
+
+flow.isDirective(x);     // type guard
+flow.merge(a, b);        // Algorithm 4 merge of two directives
+flow.validate(d);        // throws FlowConfigurationError on invalid shape
+```
+
+| Helper | Signature | Notes |
+|--------|-----------|-------|
+| `flow.isDirective` | `(x: unknown) => x is Directive` | Structural type guard. Returns `true` for any non-null, non-array object. Filters out primitives, null/undefined, arrays, and functions. |
+| `flow.merge` | `<T extends Directive>(a: T, b: T) => T` | Merges by Algorithm 4. Position field uses precedence (b wins on tie). `reply` is last-wins. State writes shallow-merge. PreDirective fields concatenate / dedupe / OR per the table above. |
+| `flow.validate` | `(d: Directive) => void` | Throws `FlowConfigurationError` for: multiple position fields set; `goTo` set as an empty object `{}`; `reply` co-existing with `abort`. |
+
+## Examples
+
+### 1. Simple `goTo`
+
+A finalize hook redirects to a follow-up flow when a flag flips on the response.
+
+```typescript
+import type { Directive } from "@falai/agent";
+
+const step = {
+  id: "summary",
+  prompt: "Summarize the request.",
+  hooks: {
+    finalize: ({ data }): Directive | void => {
+      if (data.escalate) {
+        return { goTo: "Escalation", reason: "summary marked escalate=true" };
+      }
+    },
+  },
+};
+```
+
+### 2. `complete` with `dataUpdate`
+
+A booking tool finalizes its work and writes back the booking id while marking the flow done in one declarative result.
+
+```typescript
+import type { Tool, Directive } from "@falai/agent";
+
+export const bookHotel: Tool = {
+  id: "book_hotel",
+  description: "Reserve the collected dates.",
+  async handler(ctx) {
+    const id = await api.book(ctx.data);
+    const directive: Directive = {
+      complete: { reason: "reservation confirmed" },
+      dataUpdate: { bookingId: id, bookedAt: new Date().toISOString() },
+    };
+    return { data: { id }, directive };
+  },
+};
+```
+
+### 3. `abort`
+
+A permission tool halts the conversation when the caller cannot proceed. Note that `reply` cannot accompany `abort`; the abort reason itself is what's recorded.
+
+```typescript
+import type { Tool, Directive } from "@falai/agent";
+
+export const verifyAccess: Tool = {
+  id: "verify_access",
+  isReadOnly: () => true,
+  async handler(ctx) {
+    const allowed = await acl.check(ctx.context.userId);
+    if (!allowed) {
+      const directive: Directive = {
+        abort: { reason: "caller is not on the allow-list", clearSession: true },
+      };
+      return { data: { allowed: false }, directive };
+    }
+    return { data: { allowed: true } };
+  },
+};
+```
+
+### 4. `reply` only — speak verbatim, write nothing
+
+A finalize hook emits a confirmation utterance without changing position or writing state. The LLM call this turn is skipped; the literal string is the assistant message.
+
+```typescript
+import type { Directive } from "@falai/agent";
+
+const step = {
+  id: "confirm_handoff",
+  hooks: {
+    finalize: ({ data }): Directive | void => {
+      if (data.handoffReady) {
+        return { reply: "Connecting you with a specialist now." };
+      }
+    },
+  },
+};
+```
+
+## Errors
+
+`flow.validate(directive)` and the per-turn merge stage throw `FlowConfigurationError` for the following invariants. See [Errors](./errors.md) for the format contract.
+
+| Cause | Message shape |
+|-------|---------------|
+| Multiple position fields set on one directive | `[FlowConfigurationError] Invalid directive: multiple position fields set (...). A directive may have at most one position field. Remove the extras.` |
+| `goTo` set as an empty object `{}` | `[FlowConfigurationError] Invalid directive: goTo is set as an empty object. goTo requires a flow id or title. Provide { flow: "<id>" } or use the string shorthand.` |
+| `reply` co-existing with `abort` | `[FlowConfigurationError] Invalid directive: reply cannot co-exist with abort. An aborted conversation cannot deliver a reply. Remove one of the fields.` |
+
+Two related runtime behaviors are notable but **not** thrown errors:
+
+- Returning a `PreDirective` (with `appendPrompt` / `injectTools` / `halt`) from a post-LLM hook (`finalize`, `onComplete`) drops those three fields with a `DEBUG` log; the remaining `Directive` portion is honored.
+- A `goTo` / `goToStep` referencing an unknown flow or step throws `FlowConfigurationError` at apply time, not at validation time — the validator does not have the agent's flow registry.
+
+## Related
+
+- [Directives](../concepts/directives.md) — the mental model and inheritance chain `Directive → PreDirective → SignalDirective`.
+- [Turn pipeline](../concepts/pipeline.md) — when the bus runs, and where merge sits in the per-turn sequence.
+- [Flow control](../guides/flow-control.md) — recipes for redirecting, completing, aborting, or replying from tools and hooks.
+- [PreDirective](./pre-directive.md) — pre-LLM extension adding `appendPrompt`, `injectTools`, `halt`.
+- [Signals](./signals.md) — `SignalDirective` extends `PreDirective` for signal handlers.
+- [Tool](./tool.md) — `ctx.dispatch(directive)` and `ToolResult.directive`.
+- [Branches](./branches.md) — `then: Directive` as a branch target (note: branches bypass the bus).
+- [Errors](./errors.md) — `FlowConfigurationError` format contract.