@falai/agent 2.0.1 → 2.1.0

package/docs/migration/route-to-flow.md

@@ -1,561 +0,0 @@
----
-title: "Route → Flow rename"
-description: "Rename the Route domain noun to Flow across symbols, config, persistence, and generated IDs, with per-adapter data migration steps."
-type: migration
-order: 2
-sidebar: false
----
-
-# Migration Guide: Route → Flow Rename
-
-**Version:** Minor breaking bump (ships before v2 overhaul)
-**CHANGELOG:** See the [breaking-change entry in CHANGELOG.md](../../CHANGELOG.md)
-
-## Summary
-
-The `Route` domain noun has been renamed to `Flow` across the entire `@falai/agent` package. This is a clean break with no compatibility shims, no dual-naming layer, and no runtime fallback for legacy field names. Every public symbol, configuration option, persisted column/field, adapter method, constant, error class, and utility function that referenced "Route" as a noun now uses "Flow". The verb form `route()` and the gerund "routing" (as used in prose and the `routing.ts` module) are preserved — routing-as-an-action remains the correct verb for selecting a flow.
-
----
-
-## Symbol Rename Table
-
-| Old | New | Layer | Action |
-|-----|-----|-------|--------|
-| `Route` (class) | `Flow` | Core | Update imports and instantiation |
-| `RouteOptions` | `FlowOptions` | Type | Update type annotations |
-| `RouteRef` | `FlowRef` | Type | Update type annotations |
-| `RouteTransitionConfig` | `FlowTransitionConfig` | Type | Update type annotations |
-| `RouteCompletionHandler` | `FlowCompletionHandler` | Type | Update type annotations |
-| `RouteLifecycleHooks` | `FlowLifecycleHooks` | Type | Update type annotations |
-| `RoutingEngine` | `FlowRouter` | Core | Update imports and references |
-| `RoutingEngineOptions` | `FlowRouterOptions` | Type | Update type annotations |
-| `RoutingDecisionOutput` | `FlowRoutingDecisionOutput` | Type | Update type annotations |
-| `RouteConfigurationError` | `FlowConfigurationError` | Error | Update catch blocks |
-| `END_ROUTE` | Removed | Constant | Implicit terminus — remove all references |
-| `END_ROUTE_ID` | Removed | Constant | Implicit terminus — remove all references |
-| `generateRouteId` | `generateFlowId` | Utility | Update calls |
-| `enterRoute` | `enterFlow` | Utility | Update calls |
-| `StepRef.routeId` | `StepRef.flowId` | Type | Update field access |
-
-### Preserved (verb-form carve-outs)
-
-These are **not** renamed:
-
-- `route()` method on `FlowRouter` (verb form)
-- `RoutingDecision` type (describes the act of routing)
-- `RoutingSchemaOptions` type
-- `buildRoutingPrompt` method
-- `getCandidateStepsWithConditions` method (returns Steps)
-- `src/types/routing.ts` file path
-- All "routing" prose in documentation
-
----
-
-## Configuration Rename Table
-
-| Old | New | Location |
-|-----|-----|----------|
-| `AgentOptions.routes` | `AgentOptions.flows` | Agent constructor |
-| `AgentOptions.routeSwitchMargin` | `AgentOptions.flowSwitchMargin` | Agent constructor |
-| `agent.routeSwitchMargin` | `agent.flowSwitchMargin` | Getter/setter |
-| `agent.createRoute(...)` | `agent.createFlow(...)` | Method call |
-| `agent.getRoutes()` | `agent.getFlows()` | Method call |
-| `agent.nextStepRoute(...)` | `agent.nextStepFlow(...)` | Method call |
-| `agent.getRoutingEngine()` | `agent.getFlowRouter()` | Method call |
-| `agent.routes` | `agent.flows` | Getter |
-| `Guideline.scope: 'route'` | `Guideline.scope: 'flow'` | Guideline config |
-| `Guideline.route` | `Guideline.flow` | Guideline config |
-| `RoutingDecision.routes` | `RoutingDecision.flows` | Field access |
-
----
-
-## Session State Rename Table
-
-| Old | New | Notes |
-|-----|-----|-------|
-| `SessionState.currentRoute` | `SessionState.currentFlow` | Runtime shape |
-| `SessionState.routeHistory` | `SessionState.flowHistory` | Runtime shape |
-| `flowHistory[].routeId` | `flowHistory[].flowId` | History item shape |
-| `PendingTransition.targetRouteId` | `PendingTransition.targetFlowId` | Transition config |
-| `PendingTransition.reason: "route_complete"` | `PendingTransition.reason: "flow_complete"` | String literal |
-| `SessionData.currentRoute` | `SessionData.currentFlow` | Persistence shape |
-| `CollectedStateData.routeHistory` | `CollectedStateData.flowHistory` | Persistence shape |
-| `CollectedStateData.currentRouteTitle` | `CollectedStateData.currentFlowTitle` | Persistence shape |
-| `MessageData.route` | `MessageData.flow` | Persistence shape |
-| `SaveMessageOptions.route` | `SaveMessageOptions.flow` | Persistence shape |
-
-### StoppedReason Literals
-
-| Old | New |
-|-----|-----|
-| `'end_route'` | Removed — use `'last_step'` or `'completed'` |
-| `'route_complete'` | `'last_step'` (no successor) or `'completed'` (explicit directive) |
-
----
-
-## Adapter Method Rename Table
-
-| Adapter | Old Method | New Method |
-|---------|-----------|------------|
-| `MemoryAdapter` | `updateRouteStep()` | `updateFlowStep()` |
-| `PrismaAdapter` | `updateRouteStep()` | `updateFlowStep()` |
-| `RedisAdapter` | `updateRouteStep()` | `updateFlowStep()` |
-| `MongoAdapter` | `updateRouteStep()` | `updateFlowStep()` |
-| `PostgreSQLAdapter` | `updateRouteStep()` | `updateFlowStep()` |
-| `SQLiteAdapter` | `updateRouteStep()` | `updateFlowStep()` |
-| `OpenSearchAdapter` | `updateRouteStep()` | `updateFlowStep()` |
-| `PersistenceManager` | `updateRouteStep()` | `updateFlowStep()` |
-| `SessionRepository` (interface) | `updateRouteStep()` | `updateFlowStep()` |
-
-If you implement a custom adapter, rename your `updateRouteStep` method to `updateFlowStep`.
-
----
-
-## Per-Adapter Data Migration
-
-The framework no longer reads or writes the legacy field/column names. You must migrate your persisted data before deploying the new version.
-
-### PostgreSQL
-
-```sql
--- Sessions table
-ALTER TABLE sessions RENAME COLUMN current_route TO current_flow;
-
--- Messages table
-ALTER TABLE messages RENAME COLUMN route TO flow;
-```
-
-### SQLite
-
-SQLite 3.25+ supports `ALTER TABLE ... RENAME COLUMN`:
-
-```sql
--- Sessions table
-ALTER TABLE sessions RENAME COLUMN current_route TO current_flow;
-
--- Messages table
-ALTER TABLE messages RENAME COLUMN route TO flow;
-```
-
-For SQLite versions older than 3.25, use the copy-and-rename pattern:
-
-```sql
--- 1. Create new table with correct column names
-CREATE TABLE sessions_new (
-  id TEXT PRIMARY KEY,
-  user_id TEXT,
-  agent_name TEXT,
-  status TEXT DEFAULT 'active',
-  current_flow TEXT,
-  current_step TEXT,
-  collected_data TEXT,
-  message_count INTEGER DEFAULT 0,
-  last_message_at TEXT,
-  completed_at TEXT,
-  created_at TEXT NOT NULL,
-  updated_at TEXT NOT NULL
-);
-
--- 2. Copy data
-INSERT INTO sessions_new SELECT
-  id, user_id, agent_name, status,
-  current_route AS current_flow,
-  current_step, collected_data, message_count,
-  last_message_at, completed_at, created_at, updated_at
-FROM sessions;
-
--- 3. Drop old table and rename
-DROP TABLE sessions;
-ALTER TABLE sessions_new RENAME TO sessions;
-
--- Repeat for messages table (route → flow column)
-```
-
-### Prisma
-
-Update your Prisma schema model fields:
-
-```diff
-model Session {
-  id            String   @id
-  userId        String?
-  agentName     String?
-  status        String   @default("active")
-- currentRoute  String?  @map("current_route")
-+ currentFlow   String?  @map("current_flow")
-  currentStep   String?  @map("current_step")
-  collectedData Json?    @map("collected_data")
-  // ...
-}
-
-model Message {
-  id        String   @id
-  sessionId String   @map("session_id")
-  // ...
-- route     String?
-+ flow      String?
-  step      String?
-  // ...
-}
-```
-
-Then generate and apply the migration:
-
-```bash
-npx prisma migrate dev --name route-to-flow-rename
-```
-
-If you use a custom `fieldMappings` config in `PrismaAdapter`, update the key from `currentRoute` to `currentFlow`:
-
-```typescript
-// Before
-fieldMappings: { currentRoute: 'currentRoute', ... }
-
-// After
-fieldMappings: { currentFlow: 'currentFlow', ... }
-```
-
-### MongoDB
-
-```javascript
-// Rename session fields
-db.sessions.updateMany({}, {
-  $rename: {
-    "currentRoute": "currentFlow"
-  }
-});
-
-// Rename collected state fields (if stored at top level)
-db.sessions.updateMany({}, {
-  $rename: {
-    "collectedData.routeHistory": "collectedData.flowHistory",
-    "collectedData.currentRouteTitle": "collectedData.currentFlowTitle"
-  }
-});
-
-// Rename message fields
-db.messages.updateMany({}, {
-  $rename: {
-    "route": "flow"
-  }
-});
-```
-
-### Redis
-
-Redis stores sessions as serialized JSON. Use a Lua script to rewrite the payload in-place:
-
-```lua
--- redis-migrate-route-to-flow.lua
--- Run with: redis-cli --eval redis-migrate-route-to-flow.lua
-
-local cursor = "0"
-repeat
-  local result = redis.call("SCAN", cursor, "MATCH", "session:*", "COUNT", 100)
-  cursor = result[1]
-  local keys = result[2]
-  for _, key in ipairs(keys) do
-    local val = redis.call("GET", key)
-    if val then
-      -- Replace field names in JSON payload
-      val = val:gsub('"currentRoute"', '"currentFlow"')
-      val = val:gsub('"routeHistory"', '"flowHistory"')
-      val = val:gsub('"currentRouteTitle"', '"currentFlowTitle"')
-      redis.call("SET", key, val)
-    end
-  end
-until cursor == "0"
-
--- If using hash layout instead of JSON:
--- Rename hash fields per session key
-local cursor2 = "0"
-repeat
-  local result = redis.call("SCAN", cursor2, "MATCH", "session:*", "COUNT", 100)
-  cursor2 = result[1]
-  local keys = result[2]
-  for _, key in ipairs(keys) do
-    local typ = redis.call("TYPE", key)["ok"]
-    if typ == "hash" then
-      local oldVal = redis.call("HGET", key, "currentRoute")
-      if oldVal then
-        redis.call("HSET", key, "currentFlow", oldVal)
-        redis.call("HDEL", key, "currentRoute")
-      end
-    end
-  end
-until cursor2 == "0"
-```
-
-For message keys, apply the same pattern replacing `"route"` with `"flow"` in the JSON payload or hash field.
-
-### OpenSearch
-
-Use the `_reindex` API with a painless script to rename fields:
-
-```json
-POST _reindex
-{
-  "source": {
-    "index": "sessions"
-  },
-  "dest": {
-    "index": "sessions_v2"
-  },
-  "script": {
-    "source": """
-      // Rename currentRoute → currentFlow
-      if (ctx._source.containsKey('currentRoute')) {
-        ctx._source.currentFlow = ctx._source.remove('currentRoute');
-      }
-      // Rename routeHistory → flowHistory in collectedData
-      if (ctx._source.containsKey('collectedData') && ctx._source.collectedData.containsKey('routeHistory')) {
-        ctx._source.collectedData.flowHistory = ctx._source.collectedData.remove('routeHistory');
-      }
-      if (ctx._source.containsKey('collectedData') && ctx._source.collectedData.containsKey('currentRouteTitle')) {
-        ctx._source.collectedData.currentFlowTitle = ctx._source.collectedData.remove('currentRouteTitle');
-      }
-    """,
-    "lang": "painless"
-  }
-}
-```
-
-Then swap the alias:
-
-```json
-POST _aliases
-{
-  "actions": [
-    { "remove": { "index": "sessions", "alias": "sessions_active" } },
-    { "add": { "index": "sessions_v2", "alias": "sessions_active" } }
-  ]
-}
-```
-
-For the messages index, apply the same reindex pattern renaming the `route` field to `flow`:
-
-```json
-POST _reindex
-{
-  "source": {
-    "index": "messages"
-  },
-  "dest": {
-    "index": "messages_v2"
-  },
-  "script": {
-    "source": """
-      if (ctx._source.containsKey('route')) {
-        ctx._source.flow = ctx._source.remove('route');
-      }
-    """,
-    "lang": "painless"
-  }
-}
-```
-
----
-
-## ID Prefix Migration
-
-The `generateFlowId()` function now produces IDs with the prefix `flow_` instead of `route_`. Existing sessions stored under the legacy `route_*` prefix will not be recognized by the framework's flow-matching logic unless migrated.
-
-**Run this migration during a maintenance window.** In-flight sessions will lose their step pointer if the rename is not atomic with the adapter restart.
-
-### PostgreSQL / SQLite
-
-```sql
-UPDATE sessions
-SET current_flow = REPLACE(current_flow, 'route_', 'flow_')
-WHERE current_flow LIKE 'route\_%' ESCAPE '\';
-```
-
-If your `collected_data` JSON contains `flowHistory` entries with old IDs (stored as `routeId` before the field rename), update those as well:
-
-```sql
--- PostgreSQL (JSONB)
-UPDATE sessions
-SET collected_data = REPLACE(collected_data::text, '"route_', '"flow_')::jsonb
-WHERE collected_data::text LIKE '%"route_%';
-```
-
-### MongoDB
-
-```javascript
-db.sessions.updateMany(
-  { currentFlow: { $regex: "^route_" } },
-  [{
-    $set: {
-      currentFlow: {
-        $replaceOne: {
-          input: "$currentFlow",
-          find: "route_",
-          replacement: "flow_"
-        }
-      }
-    }
-  }]
-);
-
-// Also update flowHistory entries
-db.sessions.updateMany(
-  { "collectedData.flowHistory.flowId": { $regex: "^route_" } },
-  [{
-    $set: {
-      "collectedData.flowHistory": {
-        $map: {
-          input: "$collectedData.flowHistory",
-          as: "entry",
-          in: {
-            $mergeObjects: [
-              "$$entry",
-              {
-                flowId: {
-                  $replaceOne: {
-                    input: "$$entry.flowId",
-                    find: "route_",
-                    replacement: "flow_"
-                  }
-                }
-              }
-            ]
-          }
-        }
-      }
-    }
-  }]
-);
-```
-
-### Redis
-
-Extend the Lua script above to also replace ID prefixes in the JSON payload:
-
-```lua
--- Add to the existing migration script
-val = val:gsub('"route_', '"flow_')
-```
-
-### OpenSearch
-
-Include the prefix replacement in the reindex painless script:
-
-```json
-POST _reindex
-{
-  "source": { "index": "sessions_v2" },
-  "dest": { "index": "sessions_v3" },
-  "script": {
-    "source": """
-      if (ctx._source.containsKey('currentFlow') && ctx._source.currentFlow != null && ctx._source.currentFlow.startsWith('route_')) {
-        ctx._source.currentFlow = 'flow_' + ctx._source.currentFlow.substring(6);
-      }
-    """,
-    "lang": "painless"
-  }
-}
-```
-
----
-
-## Code-Side Migration Recipe
-
-For downstream TypeScript consumers, here's a sed/codemod summary covering the most common public-API touchpoints:
-
-```bash
-# Symbol renames (imports and references)
-sed -i '' 's/\bRoute\b/Flow/g; s/\bRouteOptions\b/FlowOptions/g; s/\bRouteRef\b/FlowRef/g' src/**/*.ts
-sed -i '' 's/\bRouteTransitionConfig\b/FlowTransitionConfig/g' src/**/*.ts
-sed -i '' 's/\bRouteCompletionHandler\b/FlowCompletionHandler/g' src/**/*.ts
-sed -i '' 's/\bRouteLifecycleHooks\b/FlowLifecycleHooks/g' src/**/*.ts
-sed -i '' 's/\bRouteConfigurationError\b/FlowConfigurationError/g' src/**/*.ts
-sed -i '' 's/\bRoutingEngine\b/FlowRouter/g' src/**/*.ts
-
-# Constants (END_ROUTE removed — delete all references)
-# END_ROUTE/END_FLOW are no longer needed. Remove imports and usages.
-# The last step in a flow is the implicit terminus.
-sed -i '' '/END_ROUTE/d; /END_FLOW/d' src/**/*.ts
-
-# Methods and fields
-sed -i '' 's/\.createRoute(/\.createFlow(/g' src/**/*.ts
-sed -i '' 's/\.getRoutes(/\.getFlows(/g' src/**/*.ts
-sed -i '' 's/\.nextStepRoute(/\.nextStepFlow(/g' src/**/*.ts
-sed -i '' 's/\.getRoutingEngine(/\.getFlowRouter(/g' src/**/*.ts
-sed -i '' 's/\brouteSwitchMargin\b/flowSwitchMargin/g' src/**/*.ts
-sed -i '' 's/\bgenerateRouteId\b/generateFlowId/g' src/**/*.ts
-sed -i '' 's/\benterRoute\b/enterFlow/g' src/**/*.ts
-
-# Session state fields
-sed -i '' 's/\.currentRoute/\.currentFlow/g' src/**/*.ts
-sed -i '' 's/\.routeHistory/\.flowHistory/g' src/**/*.ts
-sed -i '' 's/\btargetRouteId\b/targetFlowId/g' src/**/*.ts
-
-# String literals
-sed -i '' "s/'end_route'/'last_step'/g" src/**/*.ts
-sed -i '' "s/'route_complete'/'completed'/g" src/**/*.ts
-
-# Configuration
-sed -i '' 's/routes:/flows:/g' src/**/*.ts  # Be careful — review matches manually
-
-# Import paths (if importing from @falai/agent internals)
-sed -i '' 's/core\/Route/core\/Flow/g' src/**/*.ts
-sed -i '' 's/core\/RoutingEngine/core\/FlowRouter/g' src/**/*.ts
-sed -i '' 's/types\/route/types\/flow/g' src/**/*.ts
-```
-
-**Important:** These sed commands are aggressive. Run them, then use `tsc --noEmit` to catch any false positives (e.g., `routes` in an HTTP router context). Review the diff before committing.
-
-For a safer approach, use a TypeScript-aware codemod tool like [jscodeshift](https://github.com/facebook/jscodeshift) or rely on your IDE's "Find and Replace with Regex" with word-boundary matching.
-
----
-
-## Verification
-
-After migrating your code, run this ripgrep command to confirm no legacy references remain:
-
-```bash
-rg -n '\b(Route|RouteOptions|RouteRef|RouteConfigurationError|RoutingEngine|END_ROUTE|currentRoute|routeHistory|createRoute|generateRouteId|enterRoute|nextStepRoute|getRoutes|routeSwitchMargin)\b' \
-  --glob '**/*.ts' \
-  --glob '**/*.tsx' \
-  --glob '!node_modules/**' \
-  --glob '!dist/**'
-```
-
-Expected output: **zero matches**.
-
-If you have historical migration notes or changelog entries that reference the old names, exclude them:
-
-```bash
-rg -n '\b(Route|RouteOptions|RouteRef|RouteConfigurationError|RoutingEngine|END_ROUTE|currentRoute|routeHistory|createRoute|generateRouteId|enterRoute|nextStepRoute|getRoutes|routeSwitchMargin)\b' \
-  --glob '**/*.ts' \
-  --glob '**/*.tsx' \
-  --glob '!node_modules/**' \
-  --glob '!dist/**' \
-  --glob '!**/CHANGELOG*' \
-  --glob '!**/migration/**'
-```
-
-Then run your type checker to confirm everything compiles:
-
-```bash
-npx tsc --noEmit
-```
-
----
-
-## FAQ
-
-**Q: Is there a compatibility shim or deprecation period?**
-No. This is a clean break. The old names are removed entirely.
-
-**Q: Do I need to migrate my database before deploying?**
-Yes. The framework no longer reads or writes the legacy column/field names. Deploy the data migration first, then deploy the new code.
-
-**Q: What about the `route()` method I see on `FlowRouter`?**
-That's the verb form — it means "to route a message to a flow." It is intentionally preserved.
-
-**Q: My tests assert on `'end_route'` or `'route_complete'` — what do I do?**
-`'end_route'` has been removed entirely (implicit terminus replaces it). Update to `'last_step'`. `'route_complete'` becomes `'last_step'` (no successor) or `'completed'` (explicit directive). TypeScript will flag these as type errors if you miss any.
-
-**Q: I have custom IDs that don't use the `route_` prefix — do I need to migrate them?**
-Only IDs generated by `generateRouteId()` (now `generateFlowId()`) use the prefix. If you set custom IDs on your flows, they are unaffected by the prefix change.

package/docs/reference/pre-directive.md

@@ -1,131 +0,0 @@
----
-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[]`