@falai/agent 1.2.7 → 2.0.0

package/docs/reference/errors.md

@@ -0,0 +1,122 @@
+---
+title: "Errors"
+description: "Typed error classes the framework throws, and the message format contract every thrown error follows."
+type: reference
+order: 12
+---
+
+# Errors
+
+> **Where this is introduced:** [Errors](../guides/error-handling.md)
+
+`@falai/agent` throws typed `Error` subclasses for every failure mode the framework owns. Catch them by class to discriminate construction errors from runtime errors, and by `error.name` when classes that are not exported (e.g. `DataValidationError`, `ResponseGenerationError`) need to be matched.
+
+Every thrown message follows the same format contract:
+
+```text
+[<ErrorClass>] <what>: <why>. <how to fix>.
+```
+
+The bracketed prefix matches the class name. The "what / why / how to fix" triplet is mandatory — the framework never throws a bare message.
+
+## Signature
+
+```typescript
+// Exported from "@falai/agent"
+class FlowConfigurationError extends Error { /* name = "FlowConfigurationError" */ }
+class ToolCreationError       extends Error { toolId: string; cause?: Error }
+class ToolExecutionError      extends Error {
+  toolId: string;
+  executionContext?: Record<string, unknown>;
+  cause?: Error;
+}
+class NotImplementedError     extends Error { /* name = "NotImplementedError" */ }
+
+// Internal — match by `error.name` (not exported from the package barrel)
+class DataValidationError     extends Error { errors: ValidationError[] }
+class ResponseGenerationError extends Error {
+  details?: {
+    originalError?: unknown;
+    params?: Record<string, unknown>;
+    phase?: string;
+    context?: Record<string, unknown>;
+  };
+}
+```
+
+## Fields
+
+| Class | Thrown when | Notable fields | Recover by |
+|-------|-------------|----------------|------------|
+| `FlowConfigurationError` | Construction- or run-time misconfiguration: duplicate ids, unknown `collect` keys, malformed `Directive`, auto-step cycles, branch targets that do not resolve, function on `when`. | `message` | Fix the offending agent/flow/step/branch/directive at the source. Not a runtime-recoverable error. |
+| `ToolCreationError` | A `Tool` fails registration (invalid schema, duplicate id, builder threw). | `toolId`, `cause` | Repair the tool definition. Not user-facing. |
+| `ToolExecutionError` | A handler throws, all retries fail, or `validateInput` cannot correct invalid args. | `toolId`, `executionContext`, `cause` | Surface a user-friendly message; optionally `agent.dispatch({ goTo: '<recovery-flow>' })`. |
+| `DataValidationError` | `agent.respond(...)` collects values that violate the declared `schema`. | `errors: ValidationError[]` | Re-prompt for the offending fields, then retry. |
+| `ResponseGenerationError` | The provider call fails or the response cannot be parsed. | `details.phase`, `details.originalError` | Retry with backoff, fall back to a different provider, or surface a soft failure to the user. |
+| `NotImplementedError` | A reserved option is set to a value this version does not support (e.g. `routerMode: 'embedding'` in v2.0). | `message` | Use a supported value. |
+
+## Examples
+
+### 1. Narrowing by class and `name`
+
+```typescript
+import {
+  FlowConfigurationError,
+  ToolExecutionError,
+  NotImplementedError,
+} from "@falai/agent";
+
+try {
+  const response = await agent.respond(message);
+  return response.message;
+} catch (err) {
+  if (err instanceof FlowConfigurationError) throw err;          // bug — bubble up
+  if (err instanceof NotImplementedError) throw err;             // config bug
+  if (err instanceof ToolExecutionError) {
+    log.warn({ toolId: err.toolId, cause: err.cause }, err.message);
+    return "Sorry, that action failed. Try again in a moment.";
+  }
+  // Not exported — match by name.
+  if (err instanceof Error && err.name === "DataValidationError") {
+    return "I need you to clarify a few details — let's try that again.";
+  }
+  if (err instanceof Error && err.name === "ResponseGenerationError") {
+    return "I'm having trouble reaching the model. Please retry.";
+  }
+  throw err;
+}
+```
+
+### 2. The format contract in practice
+
+Every thrown message is parseable. The leading `[<ErrorClass>]` token mirrors the class name, the colon separates `<what>` from `<why>`, and the trailing sentence is `<how to fix>`.
+
+```text
+[FlowConfigurationError] Invalid directive: multiple position fields set (goTo, complete). A directive may have at most one position field. Remove the extras.
+
+[ToolExecutionError] Tool "book_hotel" execution failed: all 3 attempts exhausted. Check the tool handler for errors or increase maxRetries. Last error: ECONNRESET.
+
+[DataValidationError] Data validation failed: fields [checkIn must be a date] did not pass schema validation. Fix the offending values to match the declared schema.
+
+[NotImplementedError] routerMode "embedding" is not implemented: only "ai" is supported in v2.0. Set routerMode to "ai" or omit the option.
+```
+
+## Errors
+
+The format contract itself has zero runtime enforcement — it is a contract on framework code, not on user code. If you write a custom `Tool` or hook that throws, follow the same shape so downstream `try/catch` blocks parse uniformly:
+
+```typescript
+throw new ToolExecutionError(
+  `[ToolExecutionError] Tool "${tool.id}" booking failed: provider returned 503. Retry the call or fall back to manual booking.`,
+  tool.id,
+);
+```
+
+Tool input validation, permission denials, and missing-tool warnings are reported as `ToolResult { success: false, error }` rather than thrown — this keeps the AI's reasoning loop intact while preserving the same `[<ErrorClass>] <what>: <why>. <how to fix>.` shape in the `error` string.
+
+## Related
+
+- [Errors](../guides/error-handling.md) — recipe-shaped guide that introduces this surface.
+- [createAgent](./create-agent.md) — construction-time errors thrown from `new Agent(...)`.
+- [Tool](./tool.md) — handler return shape and the `ToolExecutionError` triggers.
+- [Directive](./directive.md) — the validation rules that surface as `FlowConfigurationError`.

package/docs/reference/flow.md

@@ -0,0 +1,238 @@
+---
+title: Flow
+description: A goal-shaped sequence of steps with shared schema, conditions, and completion semantics.
+type: reference
+order: 2
+---
+
+# Flow
+
+> **Where this is introduced:** [Architecture](../concepts/architecture.md)
+
+A `Flow` is one of the seven primitives in `@falai/agent`. It models a single conversational goal — booking a hotel, escalating a complaint, onboarding a teammate — as an ordered set of steps that share the agent's typed `TData` schema. Flows declare what data they need (`requiredFields`), what extra data they can use (`optionalFields`), when they should activate (`when` for AI strings, `if` for code), and what happens when they finish (`onComplete` or `hooks.onComplete`). The router selects exactly one flow per turn; once the active flow's required fields are satisfied, the engine fires its completion path.
+
+## Signature
+
+```typescript
+interface FlowOptions<TContext = unknown, TData = unknown> {
+  id?: string;
+  title: string;
+  description?: string;
+
+  when?: ConditionWhen;                                // string | string[]
+  if?: ConditionIf<TContext, TData>;                   // predicate | predicate[]
+
+  instructions?: Instruction<TContext, TData>[];
+  tools?: (string | Tool<TContext, TData>)[];
+
+  routingExtrasSchema?: StructuredSchema;
+  responseOutputSchema?: StructuredSchema;
+
+  requiredFields?: (keyof TData)[];
+  optionalFields?: (keyof TData)[];
+  initialData?: Partial<TData>;
+
+  steps?: StepOptions<TContext, TData>[];
+
+  onComplete?: string;                                 // top-level: string sugar only
+  reentrant?: boolean;                                 // default false
+
+  hooks?: FlowLifecycleHooks<TContext, TData>;
+}
+
+class Flow<TContext = unknown, TData = unknown> {
+  readonly id: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly when?: ConditionWhen;
+  readonly if?: ConditionIf<TContext, TData>;
+  readonly initialStep: Step<TContext, TData>;
+  readonly requiredFields?: (keyof TData)[];
+  readonly optionalFields?: (keyof TData)[];
+  readonly initialData?: Partial<TData>;
+  readonly onComplete?: string;
+  readonly reentrant: boolean;
+  readonly hooks?: FlowLifecycleHooks<TContext, TData>;
+
+  constructor(options: FlowOptions<TContext, TData>, parentAgent?: Agent<TContext, TData>);
+
+  addStep(options: StepOptions<TContext, TData>): Step<TContext, TData>;
+  getSteps(): Step<TContext, TData>[];
+  getStep(stepId: string): Step<TContext, TData> | undefined;
+  getInstructions(): Instruction<TContext, TData>[];
+  getTools(): Tool<TContext, TData>[];
+
+  isComplete(data: Partial<TData>): boolean;
+  getMissingRequiredFields(data: Partial<TData>): (keyof TData)[];
+  getCompletionProgress(data: Partial<TData>): number;
+}
+```
+
+## Fields
+
+### `FlowOptions`
+
+| Field                 | Type                                              | Required | Default | Notes                                                                                                                                              |
+| --------------------- | ------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                  | `string`                                          | no       | derived from `title` | Stable identifier. Auto-generated deterministically from the title when omitted.                                                                                 |
+| `title`               | `string`                                          | yes      | —       | Human-readable name. Shown to the router and used as the default flow id.                                                                          |
+| `description`         | `string`                                          | no       | —       | One-line summary surfaced to the router prompt.                                                                                                    |
+| `when`                | `string \| string[]`                              | no       | —       | AI-evaluated activation condition(s). Strings only — functions belong on `if`. Multiple strings combine with AND semantics.                        |
+| `if`                  | `(ctx) => boolean \| Promise<boolean>` or array   | no       | —       | Code-evaluated activation condition(s). Free to evaluate. When both are set, `if` runs first; `when` only evaluates if `if` passes.                |
+| `instructions`        | `Instruction<TContext, TData>[]`                  | no       | `[]`    | Flow-scoped instructions. Apply only while this flow is active. See [Instruction](./instruction.md).                                               |
+| `tools`               | `(string \| Tool)[]`                              | no       | `[]`    | Tool ids (resolved via the agent's tool registry) or inline `Tool` objects. Available only while this flow is active.                              |
+| `routingExtrasSchema` | `StructuredSchema`                                | no       | —       | Optional extra fields the router may extract during routing.                                                                                       |
+| `responseOutputSchema`| `StructuredSchema`                                | no       | —       | Optional structured response shape for this flow's assistant messages.                                                                             |
+| `requiredFields`      | `(keyof TData)[]`                                 | no       | —       | Fields that must be present in `session.data` for the flow to complete. Drives `isComplete` and progress calculation.                              |
+| `optionalFields`      | `(keyof TData)[]`                                 | no       | —       | Fields the flow uses but doesn't require. Tracked for re-entry resets and progress visibility only.                                                |
+| `initialData`         | `Partial<TData>`                                  | no       | —       | Pre-populated values applied when the flow is entered. Merged into `session.data`.                                                                 |
+| `steps`               | `StepOptions<TContext, TData>[]`                  | no       | —       | Sequential steps. The first becomes the initial step; the rest are chained as linear successors. The last step is the implicit terminus.           |
+| `onComplete`          | `string`                                          | no       | —       | **String only.** Sugar for `hooks.onComplete = () => ({ goTo: '<id>' })`. For dynamic completion logic, use `hooks.onComplete`.                    |
+| `reentrant`           | `boolean`                                         | no       | `false` | If `true`, the router may select this flow again after it has completed in the current session. On re-entry, declared `requiredFields` and `optionalFields` are cleared. |
+| `hooks`               | `FlowLifecycleHooks<TContext, TData>`             | no       | —       | Lifecycle hooks: `onEnter`, `onExit`, `onComplete`, `onDataUpdate`, `onContextUpdate`. See below.                                                   |
+
+### `FlowLifecycleHooks`
+
+| Hook              | Returns                                | Phase    | Notes                                                                                                                  |
+| ----------------- | -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `onEnter`         | `void \| PreDirective`                 | pre-LLM  | Fires when the flow is entered. May augment the prompt, inject tools, or `halt`. See [PreDirective](./pre-directive.md).|
+| `onExit`          | `void`                                 | post     | Informational. Receives an `ExitReason`; cannot influence flow control.                                                |
+| `onComplete`      | `void \| Directive`                    | post-LLM | Handler form of completion. Mutually exclusive with top-level `onComplete: string` — setting both throws.              |
+| `onDataUpdate`    | `Partial<TData>`                       | post     | Mutate or enrich the data update before it is committed to `session.data`.                                             |
+| `onContextUpdate` | `void`                                 | post     | Informational reaction to context updates while this flow is active.                                                   |
+
+### `Flow` instance methods
+
+| Method                                       | Returns                          | Notes                                                                                              |
+| -------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `addStep(options)`                           | `Step<TContext, TData>`          | Imperatively append a step as the successor of the current last step. Same validations as `steps[]`. |
+| `getSteps()`                                 | `Step<TContext, TData>[]`        | All steps reachable from the initial step via BFS traversal.                                       |
+| `getStep(stepId)`                            | `Step \| undefined`              | Look up a step by id.                                                                              |
+| `getInstructions()`                          | `Instruction[]`                  | Flow-scoped instructions (a copy).                                                                 |
+| `getTools()`                                 | `Tool[]`                         | Flow-scoped tools (a copy).                                                                        |
+| `isComplete(data)`                           | `boolean`                        | `true` when all `requiredFields` are populated. Optional-only flows complete on terminus, not data. |
+| `getMissingRequiredFields(data)`             | `(keyof TData)[]`                | Fields from `requiredFields` not yet present in `data`.                                            |
+| `getCompletionProgress(data)`                | `number` (0–1)                   | Fraction of `requiredFields` satisfied. `0` when only `optionalFields` are declared.               |
+
+### Completion semantics
+
+A flow finishes in one of three ways:
+
+1. **All `requiredFields` are satisfied.** The engine marks the flow complete, fires `hooks.onComplete` (or the desugared `onComplete: string` transition), and applies the returned `Directive`.
+2. **The last step in `steps[]` runs and `requiredFields` is empty.** The terminus rule applies — the flow is implicitly complete, and the same completion path runs.
+3. **A `Directive` with `complete: true` is returned** from a tool, hook, or branch while the flow is active. Completion fires immediately regardless of field state.
+
+`requiredFields` is the contract for "this flow is done." `optionalFields` is descriptive metadata — it never gates completion, but it's tracked for two reasons:
+
+- **Re-entry resets.** When `reentrant: true` and the router re-selects this flow after it has completed, every field listed in `requiredFields` and `optionalFields` is cleared so the flow starts fresh.
+- **Progress visibility.** `getCompletionProgress` ignores optional fields by design — progress reflects what the flow is *blocked on*, not what it has *touched*.
+
+### `reentrant` behavior
+
+By default (`reentrant: false`), once a flow completes the router excludes it from candidate selection for the rest of the session. Set `reentrant: true` to support patterns like "book another?", "file another ticket?", or "search again". On re-entry:
+
+- All `requiredFields` and `optionalFields` are cleared from `session.data`.
+- Other fields in `session.data` are preserved.
+- The flow restarts from its initial step.
+
+`onComplete` always wins over `reentrant`. If `onComplete` (or `hooks.onComplete`) returns a target, the session transitions there. `reentrant` is consulted only when the completion handler is absent or returns `undefined`.
+
+### Top-level `onComplete` vs `hooks.onComplete`
+
+The top-level `onComplete` is **string-only** sugar. Internally, the constructor desugars `onComplete: 'targetFlow'` into `hooks.onComplete = () => ({ goTo: 'targetFlow' })`. Use the handler form when you need conditional transitions, data writes, or any logic beyond a static target id.
+
+| Use this           | When                                                                                |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| `onComplete: 'id'` | You always want to chain into the same next flow when this one finishes.            |
+| `hooks.onComplete` | The next flow depends on collected data, or you want to write state on completion.  |
+
+> Setting **both** the top-level `onComplete` and `hooks.onComplete` on the same flow throws `FlowConfigurationError` at construction time. Pick one.
+
+## Examples
+
+### Basic linear flow
+
+```typescript
+import { createAgent, Flow, GeminiProvider } from "@falai/agent";
+
+interface BookingData {
+  destination: string;
+  checkIn: string;
+  guests: number;
+}
+
+const bookHotel = new Flow<unknown, BookingData>({
+  title: "Book Hotel",
+  description: "Collect destination, check-in date, and party size, then book.",
+  when: "the user wants to book a hotel",
+  requiredFields: ["destination", "checkIn", "guests"],
+  steps: [
+    { description: "Greet and ask destination", collect: ["destination"] },
+    { description: "Ask check-in date",         collect: ["checkIn"] },
+    { description: "Ask guest count",           collect: ["guests"] },
+  ],
+});
+
+const agent = createAgent<unknown, BookingData>({
+  schema: { /* ... */ },
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  flows: [bookHotel],
+});
+```
+
+### Completion handler with state writes and chained transition
+
+```typescript
+import { Flow } from "@falai/agent";
+
+const bookHotel = new Flow<AppContext, BookingData>({
+  title: "Book Hotel",
+  requiredFields: ["destination", "checkIn", "guests"],
+  reentrant: true,                                          // allow "book another?" loops
+  steps: [/* ... */],
+  hooks: {
+    onComplete: ({ data }) => ({
+      dataUpdate: { lastBookedAt: new Date().toISOString() },
+      goTo: data.guests > 4 ? "Group Coordination" : "Confirmation",
+      reason: "booking finalized",
+    }),
+  },
+});
+```
+
+### Imperative `addStep` after construction
+
+```typescript
+const supportFlow = new Flow({
+  title: "Support",
+  steps: [{ description: "Capture issue summary", collect: ["issue"] }],
+});
+
+// Later — extend the flow programmatically.
+supportFlow.addStep({
+  description: "Triage severity",
+  collect: ["severity"],
+});
+```
+
+> Calling `addStep` after the agent has handled a turn emits a debug-level warning that the flow graph is being mutated mid-session. The new step is still registered and connected as the successor of the current last step.
+
+## Errors
+
+| Error                       | When it's thrown                                                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `FlowConfigurationError`    | Both top-level `onComplete` and `hooks.onComplete` are set on the same flow.                                        |
+| `FlowConfigurationError`    | A function appears in `when` (functions belong on `if`).                                                            |
+| `FlowConfigurationError`    | A step inside `steps[]` violates auto-step or reply-step shape rules (raised from the underlying `Step` constructor). |
+
+All `FlowConfigurationError` messages follow the format `[FlowConfigurationError] <what>: <why>. <how to fix>.` See [Errors](./errors.md).
+
+## Related
+
+- [Architecture](../concepts/architecture.md) — where Flow fits among the seven primitives
+- [Turn pipeline](../concepts/pipeline.md) — when flows are selected, entered, and completed
+- [Step](./step.md) — the inner DSL primitive flows are composed of
+- [Directive](./directive.md) — what `hooks.onComplete` returns
+- [Instruction](./instruction.md) — flow-scoped behavioral nudges
+- [Branching](../guides/branching.md) — explicit forks inside a flow
+- [Flow control](../guides/flow-control.md) — completion, dispatch, and verbatim replies

package/docs/reference/instruction.md

@@ -0,0 +1,177 @@
+---
+title: "Instruction"
+description: "Unified behavioral primitive that shapes how the agent responds, with a kind discriminator (must / never / should) and agent / flow / step scoping."
+type: reference
+order: 5
+---
+
+# Instruction
+
+> **Where this is introduced:** [Instructions](../guides/instructions.md)
+
+An `Instruction` is a single statement of behavior the agent should follow. v2 collapses three v1 types into one — every instruction now carries a `kind` discriminator (`'must'`, `'never'`, or `'should'`) and a `prompt` that is rendered into the system prompt with a scope caption. The same shape works at agent, flow, and step scope; only its position in the configuration changes.
+
+The set of instructions actually rendered into a given turn's prompt is reported back on the response as `appliedInstructions` — observability is deterministic, derived from rendering, not self-reported by the model.
+
+## Signature
+
+```typescript
+interface Instruction<TContext = unknown, TData = unknown> {
+  id?: string;
+  kind?: 'must' | 'never' | 'should';        // default: 'should'
+  when?: ConditionWhen;                       // AI-evaluated string(s), AND semantics
+  if?: ConditionIf<TContext, TData>;          // code-evaluated function(s), AND semantics
+  prompt: Template<TContext, TData>;
+  enabled?: boolean;                          // default: true
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+interface ScopedInstructions<TContext = unknown, TData = unknown> {
+  global: Instruction<TContext, TData>[];
+  flow?: { flowTitle: string; items: Instruction<TContext, TData>[] };
+  step?: { stepId: string; items: Instruction<TContext, TData>[] };
+}
+
+interface AppliedInstruction {
+  id: string;
+  scope: 'global' | 'flow' | 'step';
+  scopeRef?: string;                          // flowTitle for flow, stepId for step
+}
+```
+
+## Fields
+
+### `Instruction`
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `prompt` | `Template<TContext, TData>` | yes | — | Behavioral text rendered into the prompt under the `## Instructions` section. |
+| `kind` | `'must' \| 'never' \| 'should'` | no | `'should'` | Severity. `'must'` = absolute do, `'never'` = absolute don't, `'should'` = conditional nudge. |
+| `when` | `ConditionWhen` | no | — | AI-evaluated activation string (or array, AND semantics). Functions are not allowed here; use `if`. |
+| `if` | `ConditionIf<TContext, TData>` | no | — | Code-evaluated activation function (or array). Free to evaluate. When both `when` and `if` are set, `if` runs first; `when` is only evaluated if `if` passes. |
+| `id` | `string` | no | auto | Stable identifier used in `AppliedInstruction.id`. Auto-generated when omitted. |
+| `enabled` | `boolean` | no | `true` | Set `false` to skip the instruction without removing it from configuration. |
+| `tags` | `string[]` | no | — | Free-form tags for filtering and grouping. |
+| `metadata` | `Record<string, unknown>` | no | — | Free-form per-instruction metadata. |
+
+### `AppliedInstruction`
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | `string` | The `Instruction.id` that fired. |
+| `scope` | `'global' \| 'flow' \| 'step'` | Where the instruction was declared. |
+| `scopeRef` | `string \| undefined` | `flowTitle` for `flow`, `stepId` for `step`, `undefined` for `global`. |
+
+## Scoping
+
+The same `Instruction` shape attaches at three positions:
+
+- **Agent (global):** `AgentOptions.instructions` — always considered, on every turn, for every flow.
+- **Flow:** `FlowOptions.instructions` — considered when the active flow matches.
+- **Step:** `StepOptions.instructions` — considered when the active step matches.
+
+At prompt-build time the composer renders each active instruction as a single bullet:
+
+```
+- [<kind>] [<scope-caption>] <prompt>
+```
+
+Scope captions are fixed by where the instruction was declared:
+
+| Scope | Caption |
+|-------|---------|
+| Agent | `[Always]` |
+| Flow | `[In: <FlowTitle>]` |
+| Step | `[Step: <stepId>]` |
+
+Example block in the rendered prompt:
+
+```
+## Instructions
+
+- [must] [Always] Always greet by name
+- [never] [Always] Promise delivery dates you cannot guarantee
+- [should] [In: Booking] Confirm dates before calling book_hotel
+- [should] [Step: payment] If the card is declined, never retry without confirmation
+```
+
+## Examples
+
+### 1. Agent-level absolutes plus a step-level nudge
+
+```typescript
+import { createAgent, GeminiProvider } from '@falai/agent';
+
+const agent = createAgent({
+  name: 'BookingBot',
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
+  instructions: [
+    { kind: 'must', prompt: 'Validate dates are in the future before booking.' },
+    { kind: 'never', prompt: 'Promise rates you have not looked up.' },
+  ],
+  flows: [
+    {
+      title: 'Booking',
+      instructions: [
+        { kind: 'should', prompt: 'Offer to compare two options before committing.' },
+      ],
+      steps: [
+        {
+          id: 'payment',
+          prompt: 'Take payment.',
+          instructions: [
+            { kind: 'must', prompt: 'If the card is declined, never retry without confirmation.' },
+          ],
+        },
+      ],
+    },
+  ],
+});
+```
+
+### 2. Conditional activation with `when` and `if`
+
+```typescript
+import type { Instruction } from '@falai/agent';
+
+type Ctx = { tier: 'free' | 'pro' };
+type Data = { hasQuoted: boolean };
+
+const concise: Instruction<Ctx, Data> = {
+  kind: 'should',
+  when: 'User asks a simple yes/no question',
+  prompt: 'Answer in one sentence.',
+};
+
+const proOnly: Instruction<Ctx, Data> = {
+  kind: 'must',
+  if: (ctx) => ctx.context.tier === 'pro',
+  prompt: 'Offer to export the conversation as PDF.',
+};
+```
+
+### 3. Reading `appliedInstructions` from a response
+
+```typescript
+const response = await agent.respond('Hi, I want to book a room.');
+
+for (const a of response.appliedInstructions ?? []) {
+  console.log(`${a.scope}${a.scopeRef ? `:${a.scopeRef}` : ''} → ${a.id}`);
+}
+// global → ins_validate_dates
+// flow:Booking → ins_offer_two_options
+```
+
+## Errors
+
+- `FlowConfigurationError` — duplicate `id` across instructions in the same scope, or `kind` set to a value other than `'must' | 'never' | 'should'`.
+- `DataValidationError` — a `Template` `prompt` references a `data` field not declared in the agent `schema`.
+
+## Related
+
+- [Instructions](../guides/instructions.md) — recipe for shaping behavior with `must` / `never` / `should`
+- [Architecture](../concepts/architecture.md) — where Instruction fits among the seven primitives
+- [createAgent](./create-agent.md) — `AgentOptions.instructions`
+- [Flow](./flow.md) — `FlowOptions.instructions`
+- [Step](./step.md) — `StepOptions.instructions`

package/docs/reference/pre-directive.md

@@ -0,0 +1,131 @@
+---
+title: "PreDirective"
+description: "Directive variant returned by pre-LLM hooks; adds prompt and tool shaping for the current turn."
+type: reference
+order: 7
+---
+
+# PreDirective
+
+> **Where this is introduced:** [Directives](../concepts/directives.md)
+
+`PreDirective<TContext, TData>` is the variant of [`Directive`](./directive.md)
+that pre-LLM hooks return. It inherits every Directive field — position writes
+(`goTo`, `goToStep`, `complete`, `abort`, `reset`), the verbatim `reply`, and
+state writes (`dataUpdate`, `contextUpdate`) — and adds three fields that only
+make sense before this turn's LLM call: `appendPrompt`, `injectTools`, and
+`halt`.
+
+Lifetime is one turn. PreDirective fields are stripped before
+`session.pendingDirective` is written, so they cannot persist across turns and
+cannot be assigned to `pendingDirective` directly.
+
+PreDirective is the return type of:
+
+- `flow.hooks.onEnter`
+- `step.hooks.onEnter`
+- `step.hooks.prepare`
+- the merged pre-LLM phase of the directive bus
+- a [`Signal`](./signals.md) firing in the pre-phase (via `SignalDirective`,
+  which extends PreDirective)
+
+Post-LLM hooks (`step.hooks.finalize`, `flow.hooks.onComplete`) return plain
+`Directive` — the three PreDirective-only fields have no effect post-LLM and
+are dropped with a debug log if present.
+
+## Signature
+
+```typescript
+interface PreDirective<TContext = unknown, TData = unknown>
+  extends Directive<TContext, TData> {
+  appendPrompt?: string[];
+  injectTools?: Array<Tool<TContext, TData>>;
+  halt?: boolean;
+}
+```
+
+## Fields
+
+| Field | Type | Required | Default | Notes |
+|-------|------|----------|---------|-------|
+| `appendPrompt` | `string[]` | no | — | Sentences appended to the system prompt for THIS turn only via `PromptComposer`'s transient appendage slot. Merged across hooks by array-concat (Algorithm 4). Never cached, never persisted. |
+| `injectTools` | `Tool<TContext, TData>[]` | no | — | Tools added to the available tool list for THIS turn only via `ToolManager`'s transient layer. Merged across hooks by concat-then-dedupe by `Tool.id` (last definition wins). Tool references are not serializable, so this field never persists. |
+| `halt` | `boolean` | no | `false` | When `true`, skip the LLM call entirely this turn. Merged by logical-OR. Co-validates with `reply`: if both are set the `reply` is emitted and the turn ends with `stoppedReason: 'reply'`; if `halt` is set without `reply` the turn ends with `stoppedReason: 'halt'` and an empty assistant message. |
+| *…all `Directive` fields* | — | — | — | See [Directive](./directive.md) for `goTo`, `goToStep`, `complete`, `abort`, `reset`, `reply`, `dataUpdate`, `contextUpdate`. Mutually-exclusive position rules apply identically. |
+
+## Examples
+
+### Append a sentence to the prompt for this turn
+
+```typescript
+import type { PreDirective } from '@falai/agent';
+
+const flow = {
+  title: 'Booking',
+  hooks: {
+    onEnter: (ctx): PreDirective => {
+      if (ctx.context.user.tier === 'vip') {
+        return {
+          appendPrompt: ['This caller is a VIP — confirm preferences before suggesting options.'],
+        };
+      }
+    },
+  },
+  steps: [/* ... */],
+};
+```
+
+### Inject a one-shot tool, then halt the LLM call
+
+```typescript
+import type { PreDirective, Tool } from '@falai/agent';
+
+const lookupAccount: Tool = {
+  id: 'lookup_account',
+  description: 'Fetch the caller\'s account record.',
+  parameters: { type: 'object', properties: {} },
+  handler: async (ctx) => ({ content: JSON.stringify(await fetchAccount(ctx.context.user.id)) }),
+};
+
+const step = {
+  id: 'verify',
+  prompt: 'Verify the caller before proceeding.',
+  hooks: {
+    prepare: async (ctx): Promise<PreDirective> => {
+      if (!ctx.data.verified) {
+        // Make the tool available for THIS turn only and let the model call it.
+        return { injectTools: [lookupAccount] };
+      }
+      // Already verified — skip the LLM, emit a deterministic reply.
+      return { halt: true, reply: 'Verified. How can I help?' };
+    },
+  },
+};
+```
+
+## Errors
+
+`PreDirective` shares Directive's construction-time validation. The following
+typed errors may be thrown by `flow.validate(...)` or by the directive bus
+when an invalid PreDirective is emitted:
+
+- `FlowConfigurationError` — multiple position fields set (`goTo`, `goToStep`, `complete`, `abort`, `reset`); `reply` co-existing with `abort`; `goTo` set as an empty object.
+
+PreDirective-only fields surface no extra construction errors. Two runtime
+behaviors are notable rather than thrown:
+
+- Assigning a PreDirective with `appendPrompt`, `injectTools`, or `halt` to
+  `session.pendingDirective` causes those fields to be stripped before the
+  write (with a debug log). The remaining Directive fields persist normally.
+- Returning a PreDirective from a post-LLM hook (`finalize`, `onComplete`)
+  causes the three PreDirective-only fields to be dropped with a debug log;
+  the Directive fields are honored.
+
+## Related
+
+- [Directives](../concepts/directives.md) — the mental model for the Directive → PreDirective → SignalDirective inheritance chain
+- [Directive](./directive.md) — the parent interface and field semantics for position writes, `reply`, and state writes
+- [Step](./step.md) — `hooks.onEnter` and `hooks.prepare` return `PreDirective`
+- [Flow](./flow.md) — `hooks.onEnter` returns `PreDirective`
+- [Signals](./signals.md) — `SignalDirective` extends `PreDirective` for pre-phase signal firings
+- [Tool](./tool.md) — the type of values in `injectTools[]`