@falai/agent 2.0.0 → 2.1.0

package/docs/migration/v1-to-v2.md

@@ -96,7 +96,7 @@ db.sessions.updateMany({}, { $unset: { pendingTransition: "" } });
 
 ### Redis
 
-Extend your migration Lua script (see the [route-to-flow migration](./route-to-flow.md) for the pattern):
+Extend your migration Lua script (see the [Route → Flow rename](#3-route--flow-rename) Redis section for the pattern):
 
 ```lua
 local cursor = "0"
@@ -208,7 +208,7 @@ type StoppedReason =
   | 'aborted'           // { abort: '...' } directive
   | 'goto'              // goTo/goToStep directive short-circuited
   | 'reset'             // { reset: true } directive
-  | 'halt'              // PreDirective halt: true
+  | 'halt'              // Directive halt: true (pre-LLM only)
   | 'reply'             // Step.reply or directive reply (LLM skipped)
   | 'max_auto_steps'    // auto-step chain cap hit
   | 'prepare_error'     // unchanged
@@ -221,9 +221,512 @@ type StoppedReason =
 
 ## 3. Route → Flow Rename
 
-The `Route` domain noun was renamed to `Flow` in a minor breaking bump that ships before v2. v2 assumes `Flow` naming everywhere — `Route` / `createRoute` / `session.currentRoute` and the corresponding persistence columns no longer exist.
+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
 
-If you haven't run that migration yet, start there: see **[Route → Flow rename](./route-to-flow.md)** for the full rename table, schema changes per adapter, and Redis/OpenSearch backfill scripts. Once that lands, return here for the rest of the v2 changes.
+| 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)
+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.
+
+### Route → Flow Verification
+
+After migrating, confirm no legacy route 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**.
+
+### 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.
 
 
 ---
@@ -495,7 +998,7 @@ const agent = createAgent({
   name: "BookingBot",
   provider: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
-    model: "models/gemini-2.5-flash",
+    model: "gemini-3.1-flash-lite",
   }),
   schema: {
     type: "object",
@@ -905,5 +1408,4 @@ If both commands return clean (no matches; exit code 0), your migration is compl
 
 ## Cross-References
 
-- [Route → Flow rename](./route-to-flow.md) — the rename pass that ships before v2
 - [CHANGELOG](../../CHANGELOG.md) — full v2.0 release notes

package/docs/reference/adapters.md

@@ -474,7 +474,7 @@ Adapter errors propagate from the underlying driver — the agent does not wrap
 ## Related
 
 - [Persistence](../guides/persistence.md) — recipe for swapping memory for a real adapter
-- [Architecture](../concepts/architecture.md) — where the adapter sits among the seven primitives
+- [Architecture](../concepts/architecture.md) — where the adapter sits among the six primitives
 - [createAgent](./create-agent.md) — the `persistence` and `sessionId` fields
 - [Directive](./directive.md) — what `pendingDirective` stores
 - [Signals](./signals.md) — what the `signals` column stores

package/docs/reference/directive.md

@@ -9,7 +9,7 @@ order: 6
 
 > **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<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. Pre-LLM-only fields (`appendPrompt`, `injectTools`, `halt`) are one-turn-lifetime and ignored with a WARN log when emitted from post-LLM hooks or persisted.
 
 A directive carries up to four orthogonal payloads:
 
@@ -92,7 +92,7 @@ Shallow-merge means each top-level key is replaced wholesale. To update a nested
 `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.
+- **`halt`** — 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.
 
@@ -105,9 +105,9 @@ Directives emitted during one turn — by tools (return value or `ctx.dispatch`)
 | 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. |
+| `appendPrompt` | **Concatenated** in emission order. |
+| `injectTools` | **Concatenated, then deduped by `Tool.id`** (last definition wins). |
+| `halt` | **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.
 
@@ -128,7 +128,7 @@ 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.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. Pre-LLM 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
@@ -228,16 +228,15 @@ const step = {
 
 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.
+- Returning a directive with `appendPrompt` / `injectTools` / `halt` from a post-LLM hook (`finalize`, `onComplete`) drops those three fields with a `WARN` 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`.
+- [Directives](../concepts/directives.md) — the mental model for `Directive` and `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.
+- [Signals](./signals.md) — `SignalDirective` extends `Directive` 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.

package/docs/reference/flow.md

@@ -9,7 +9,7 @@ order: 2
 
 > **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.
+A `Flow` is one of the six 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
 
@@ -95,7 +95,7 @@ class Flow<TContext = unknown, TData = unknown> {
 
 | 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).|
+| `onEnter`         | `void \| Directive`                    | pre-LLM  | Fires when the flow is entered. May augment the prompt, inject tools, or `halt`. Pre-LLM fields honored here.|
 | `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`.                                             |
@@ -229,7 +229,7 @@ All `FlowConfigurationError` messages follow the format `[FlowConfigurationError
 
 ## Related
 
-- [Architecture](../concepts/architecture.md) — where Flow fits among the seven primitives
+- [Architecture](../concepts/architecture.md) — where Flow fits among the six 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

package/docs/reference/instruction.md

@@ -171,7 +171,7 @@ for (const a of response.appliedInstructions ?? []) {
 ## Related
 
 - [Instructions](../guides/instructions.md) — recipe for shaping behavior with `must` / `never` / `should`
-- [Architecture](../concepts/architecture.md) — where Instruction fits among the seven primitives
+- [Architecture](../concepts/architecture.md) — where Instruction fits among the six primitives
 - [createAgent](./create-agent.md) — `AgentOptions.instructions`
 - [Flow](./flow.md) — `FlowOptions.instructions`
 - [Step](./step.md) — `StepOptions.instructions`