@falai/agent 2.0.0 → 2.1.0

package/docs/reference/providers.md

@@ -35,12 +35,12 @@ import {
 
 const provider =
   process.env.PROVIDER === "openai"
-    ? new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: "gpt-5-mini" })
+    ? new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY!, model: "gpt-5.5" })
     : process.env.PROVIDER === "anthropic"
-    ? new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY!, model: "claude-sonnet-4-5" })
+    ? new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY!, model: "claude-sonnet-4-6" })
     : process.env.PROVIDER === "openrouter"
-    ? new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY!, model: "anthropic/claude-sonnet-4.5" })
-    : new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY!, model: "models/gemini-2.5-pro" });
+    ? new OpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY!, model: "anthropic/claude-sonnet-4.6" })
+    : new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY!, model: "gemini-3.1-pro-preview" });
 
 const agent = createAgent({ provider, schema, flows });
 ```
@@ -66,7 +66,7 @@ interface GeminiProviderOptions {
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
 | `apiKey` | `string` | yes | — | Throws if empty. |
-| `model` | `string` | yes | — | Use the fully-qualified id, e.g. `"models/gemini-2.5-pro"`. |
+| `model` | `string` | yes | — | Use the model id, e.g. `"gemini-3.1-pro-preview"`. |
 | `backupModels` | `string[]` | no | `[]` | Tried in order on 429/500/503/overload errors. |
 | `config` | `Partial<GenerateContentConfig>` | no | — | Vendor-typed defaults (e.g. `temperature`, `systemInstruction`). |
 | `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
@@ -77,8 +77,8 @@ interface GeminiProviderOptions {
 ```typescript
 const gemini = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
-  model: "models/gemini-2.5-pro",
-  backupModels: ["models/gemini-2.5-flash"],
+  model: "gemini-3.1-pro-preview",
+  backupModels: ["gemini-3.1-flash-lite"],
   config: { temperature: 0.3 },
 });
 ```
@@ -106,7 +106,7 @@ interface OpenAIProviderOptions {
 |-------|------|----------|---------|-------|
 | `apiKey` | `string` | yes | — | Throws if empty. |
 | `organization` | `string` | no | — | Forwarded as `OpenAI-Organization`. |
-| `model` | `string` | yes | — | e.g. `"gpt-5"`, `"gpt-5-mini"`. |
+| `model` | `string` | yes | — | e.g. `"gpt-5.5"`, `"gpt-5.4"`. |
 | `backupModels` | `string[]` | no | `[]` | Tried in order on overload/rate-limit errors. |
 | `config` | OpenAI params | no | — | Defaults for `temperature`, `top_p`, etc. |
 | `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
@@ -117,7 +117,7 @@ interface OpenAIProviderOptions {
 ```typescript
 const openai = new OpenAIProvider({
   apiKey: process.env.OPENAI_API_KEY!,
-  model: "gpt-5-mini",
+  model: "gpt-5.5",
   organization: "org_abc",
   config: { temperature: 0.2 },
 });
@@ -144,7 +144,7 @@ interface AnthropicProviderOptions {
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
 | `apiKey` | `string` | yes | — | Throws if empty. |
-| `model` | `string` | yes | — | e.g. `"claude-sonnet-4-5"`, `"claude-opus-4-1"`. |
+| `model` | `string` | yes | — | e.g. `"claude-sonnet-4-6"`, `"claude-opus-4-7"`. |
 | `backupModels` | `string[]` | no | `[]` | Tried in order on 429/500/503/529/overload. |
 | `config` | Anthropic params | no | — | Defaults for `max_tokens`, `system`, etc. The provider sets `max_tokens=4096` if neither `config.max_tokens` nor `parameters.maxOutputTokens` is set. |
 | `retryConfig.timeout` | `number` | no | `60000` | Per-attempt timeout in ms. |
@@ -155,7 +155,7 @@ interface AnthropicProviderOptions {
 ```typescript
 const anthropic = new AnthropicProvider({
   apiKey: process.env.ANTHROPIC_API_KEY!,
-  model: "claude-sonnet-4-5",
+  model: "claude-sonnet-4-6",
   config: { max_tokens: 8192 },
 });
 ```
@@ -185,7 +185,7 @@ interface OpenRouterProviderOptions {
 | Field | Type | Required | Default | Notes |
 |-------|------|----------|---------|-------|
 | `apiKey` | `string` | yes | — | Throws if empty. |
-| `model` | `string` | yes | — | OpenRouter model id, e.g. `"anthropic/claude-sonnet-4.5"`. See [openrouter.ai/models](https://openrouter.ai/models). |
+| `model` | `string` | yes | — | OpenRouter model id, e.g. `"anthropic/claude-sonnet-4.6"`. See [openrouter.ai/models](https://openrouter.ai/models). |
 | `backupModels` | `string[]` | no | `[]` | Tried in order on overload/capacity errors. |
 | `siteUrl` | `string` | no | `""` | Sent as `HTTP-Referer` for OpenRouter rankings. |
 | `siteName` | `string` | no | `""` | Sent as `X-Title` for OpenRouter rankings. |
@@ -198,8 +198,8 @@ interface OpenRouterProviderOptions {
 ```typescript
 const openrouter = new OpenRouterProvider({
   apiKey: process.env.OPENROUTER_API_KEY!,
-  model: "anthropic/claude-sonnet-4.5",
-  backupModels: ["openai/gpt-5-mini", "google/gemini-2.5-pro"],
+  model: "anthropic/claude-sonnet-4.6",
+  backupModels: ["openai/gpt-5.5", "google/gemini-3.1-pro-preview"],
   siteName: "My App",
 });
 ```

package/docs/reference/signals.md

@@ -83,7 +83,7 @@ interface SignalContext<TContext = unknown, TData = unknown, TExtract = void> {
 }
 
 interface SignalDirective<TContext = unknown, TData = unknown>
-  extends PreDirective<TContext, TData> {
+  extends Directive<TContext, TData> {
   stopOtherSignals?: boolean;
   replyWith?: string | ((ctx: SignalContext<TContext, TData>) => string);
 }
@@ -176,7 +176,7 @@ Passed to handlers when a signal fires. Symmetric with `ToolContext`.
 
 ### `SignalDirective`
 
-Extends [`PreDirective`](./pre-directive.md), which extends [`Directive`](./directive.md). All position fields (`goTo`, `goToStep`, `complete`, `abort`, `reset`), state writes (`dataUpdate`, `contextUpdate`), `reply`, and PreDirective extras (`appendPrompt`, `injectTools`, `halt`) are inherited unchanged.
+Extends [`Directive`](./directive.md). All position fields (`goTo`, `goToStep`, `complete`, `abort`, `reset`), state writes (`dataUpdate`, `contextUpdate`), `reply`, and pre-LLM fields (`appendPrompt`, `injectTools`, `halt`) are inherited unchanged.
 
 | Added field | Type | Notes |
 |-------------|------|-------|
@@ -349,8 +349,7 @@ Soft failures handled in-band (no thrown error, turn continues):
 ## Related
 
 - [Turn pipeline](../concepts/pipeline.md) — where signal phases sit in the turn lifecycle.
-- [Directives](../concepts/directives.md) — the inheritance chain Directive → PreDirective → SignalDirective.
+- [Directives](../concepts/directives.md) — the Directive shape and SignalDirective extension.
 - [Directive](./directive.md) — base shape for all position and state fields.
-- [PreDirective](./pre-directive.md) — pre-LLM extras inherited by `SignalDirective`.
 - [createAgent](./create-agent.md) — `signals` and `signalBatchSize` options.
 - [Errors](./errors.md) — `FlowConfigurationError` format contract.

package/docs/reference/step.md

@@ -66,7 +66,7 @@ interface StepOptions<TContext = unknown, TData = unknown> {
     | ((ctx: TContext, data?: Partial<TData>) =>
         void | PrepareResult | Promise<void | PrepareResult>);
 
-  // Lifecycle (full — receives HookContext, returns PreDirective / Directive)
+  // Lifecycle (full — receives HookContext, returns Directive)
   hooks?: StepLifecycleHooks<TContext, TData>;
 
   // Routing
@@ -75,9 +75,9 @@ interface StepOptions<TContext = unknown, TData = unknown> {
 
 interface StepLifecycleHooks<TContext = unknown, TData = unknown> {
   onEnter?: (ctx: HookContext<TContext, TData>) =>
-    void | PreDirective<TContext, TData> | Promise<void | PreDirective<TContext, TData>>;
+    void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
   prepare?: (ctx: HookContext<TContext, TData>) =>
-    void | PreDirective<TContext, TData> | Promise<void | PreDirective<TContext, TData>>;
+    void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
   finalize?: (ctx: HookContext<TContext, TData>) =>
     void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
   onExit?: (ctx: HookContext<TContext, TData>, reason: ExitReason) =>
@@ -114,8 +114,8 @@ fields, with a smaller return type.
 
 | Hook | When it fires | `hooks.<name>` returns | Top-level shorthand returns | Use it for |
 |------|---------------|------------------------|------------------------------|------------|
-| `onEnter` | Before any other work the first time the step becomes current. | `void \| PreDirective` | n/a (no shorthand) | Append per-turn prompt context, inject one-turn tools, or short-circuit with `halt + reply`. |
-| `prepare` | Right before the LLM call, after `onEnter`. | `void \| PreDirective` | `void \| PrepareResult` | Mutate session data, fetch external context, halt the LLM call. |
+| `onEnter` | Before any other work the first time the step becomes current. | `void \| Directive` | n/a (no shorthand) | Append per-turn prompt context, inject one-turn tools, or short-circuit with `halt + reply`. |
+| `prepare` | Right before the LLM call, after `onEnter`. | `void \| Directive` | `void \| PrepareResult` | Mutate session data, fetch external context, halt the LLM call. |
 | `finalize` | After the LLM call and tool loop complete. | `void \| Directive` | `void \| PrepareResult` | Validate collected data, redirect with `goTo` / `goToStep`, complete the flow. |
 | `onExit` | When the step is left (next step entered, flow completed, aborted). | `void` | n/a | Emit telemetry. Cannot influence flow control. |
 
@@ -123,7 +123,7 @@ fields, with a smaller return type.
 common Directive fields (`dataUpdate`, `contextUpdate`, `goTo`,
 `goToStep`, `complete`, `halt`, `reply`). Use `hooks.<name>` when you
 need the full `HookContext` (with `session`, `history`, `dispatch`)
-or the full `Directive` / `PreDirective` surface (`appendPrompt`,
+or the full `Directive` surface (`appendPrompt`,
 `injectTools`, `abort`, `reset`).
 
 ### Resolution within a step
@@ -133,7 +133,7 @@ For one step, the engine walks this sequence per turn:
 1. Evaluate `if` (code, AND) and `when` (AI, AND) — fails skip the step entirely.
 2. Evaluate `skip` (code, OR) — true means bypass and fall through.
 3. Check `requires` — refuse entry if any required field is missing.
-4. Run `onEnter`, then `prepare` / `hooks.prepare`. May emit a `PreDirective`.
+4. Run `onEnter`, then `prepare` / `hooks.prepare`. May emit a `Directive` (pre-LLM fields honored).
 5. **LLM step**: call the LLM with the step's prompt, tools, and instructions; tool loop runs until completion. **Auto step**: skip the LLM call. **Reply step**: render `reply` as the verbatim assistant message.
 6. Run `finalize` / `hooks.finalize`. May emit a `Directive`.
 7. Evaluate `branches`. The first entry whose `if`/`when` passes wins; its `then` resolves to a step id, a flow id, or a full `Directive`. If no entry matches, fall through.
@@ -282,7 +282,7 @@ const agent = createAgent({
   }),
 }
 
-// Full hook — receives HookContext, returns PreDirective.
+// Full hook — receives HookContext, returns Directive.
 {
   id: 'enrich',
   auto: true,
@@ -326,14 +326,13 @@ Runtime errors that surface from a step's hook execution include
 
 ## Related
 
-- [Architecture](../concepts/architecture.md) — where Step fits among the seven primitives
+- [Architecture](../concepts/architecture.md) — where Step fits among the six primitives
 - [Turn pipeline](../concepts/pipeline.md) — when each step phase fires inside a turn
 - [Flow](./flow.md) — the parent type that contains a step's `steps[]` entry
 - [Tool](./tool.md) — the shape consumed by `tools[]`
 - [Instruction](./instruction.md) — the shape consumed by `instructions[]`
 - [Branches](./branches.md) — the full `BranchEntry` / `BranchMap` contract
 - [Directive](./directive.md) — the post-LLM return type for `hooks.finalize`
-- [PreDirective](./pre-directive.md) — the pre-LLM return type for `hooks.onEnter` and `hooks.prepare`
 - [When and if](../guides/conditions.md) — picking between AI and code conditions
 - [Branching](../guides/branching.md) — adding source-local forks
 - [Flow control](../guides/flow-control.md) — redirecting from a hook

package/docs/reference/tool.md

@@ -262,7 +262,7 @@ Permission denials (`checkPermissions` returning `allowed: false`) are surfaced
 ## Related
 
 - [Add tools](../start/04-add-tools.md) — tutorial that introduces this type.
-- [Architecture](../concepts/architecture.md) — where Tool fits among the seven primitives.
+- [Architecture](../concepts/architecture.md) — where Tool fits among the six primitives.
 - [Directives](../concepts/directives.md) — what `dispatch` and `directive` emit.
 - [Directive](./directive.md) — the flat shape used by both forms above.
 - [Flow control](../guides/flow-control.md) — recipes for redirecting from tools and hooks.

package/docs/start/01-install.md

@@ -67,7 +67,7 @@ import { GeminiProvider } from "@falai/agent";
 
 const provider = new GeminiProvider({
   apiKey: process.env.GEMINI_API_KEY!,
-  model: "models/gemini-2.5-pro",
+  model: "gemini-3.1-pro-preview",
 });
 
 console.log("Provider ready:", provider.constructor.name);

package/docs/start/02-first-agent.md

@@ -36,7 +36,7 @@ const response = await agent.respond("Hi, I'm Alice");
 console.log(response.message);
 ```
 
-That is the whole program. No persistence config, no tools, no branches, no signals. Three primitives appear by name (`Agent`, `Flow`, `Step`) and four more sit one decision away (`Tool`, `Instruction`, `Directive`, `PreDirective`). The next sections walk through every line.
+That is the whole program. No persistence config, no tools, no branches, no signals. Three primitives appear by name (`Agent`, `Flow`, `Step`) and three more sit one decision away (`Tool`, `Instruction`, `Directive`). The next sections walk through every line.
 
 ## Walk it line by line
 
@@ -139,7 +139,6 @@ Three primitives appear by name in the code above: [`Agent`](../concepts/archite
 - [`Tool`](../concepts/architecture.md#tool) — a typed function the AI can call. May redirect the conversation by emitting a directive. Added on page [04](./04-add-tools.md).
 - [`Instruction`](../concepts/architecture.md#instruction) — a `must` / `never` / `should` behavioral statement at agent, flow, or step scope.
 - [`Directive`](../concepts/architecture.md#directive) — a flat object any tool, hook, or branch returns to write state, change position, or speak verbatim.
-- [`PreDirective`](../concepts/architecture.md#predirective) — a `Directive` plus per-turn shaping (`appendPrompt`, `injectTools`, `halt`) returned from `onEnter` and `prepare` hooks.
 
 Read [Architecture](../concepts/architecture.md) end to end when you want the full mental model — what each primitive owns, how they reference each other, and why the set is exactly seven.
 
@@ -185,7 +184,7 @@ A few common failure modes and where to look:
 - **`Missing API key`** or a 401 from Gemini — `GEMINI_API_KEY` is unset or your `.env` did not load. Bun loads `.env` automatically; Node needs `--env-file=.env`.
 - **`FlowConfigurationError: collect references unknown key 'foo'`** — the schema does not declare `foo` as a property. Add it to `schema.properties` or fix the `collect` array.
 - **`FlowConfigurationError: duplicate flow id` / `duplicate step id`** — two flows or two steps share the same auto-derived id. Set explicit `id` values to disambiguate.
-- **The LLM call hangs** — check the `model` (Gemini's free tier expects `"models/gemini-2.5-pro"` or `"models/gemini-2.5-flash"`) and your network. Provider errors surface as `ResponseGenerationError`.
+- **The LLM call hangs** — check the `model` (Gemini's free tier expects `"gemini-3.1-pro-preview"` or `"gemini-3.1-flash-lite"`) and your network. Provider errors surface as `ResponseGenerationError`.
 
 The full set of typed errors and the `[<ErrorClass>] <what>: <why>. <how to fix>.` format contract live in the [Errors reference](../reference/errors.md).
 

package/examples/01-quickstart.ts

@@ -7,7 +7,7 @@ if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
 
 const agent = createAgent({
     name: "Greeter",
-    provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY, model: "models/gemini-2.5-flash" }),
+    provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY, model: "gemini-3.1-flash-lite" }),
     schema: { type: "object", properties: { name: { type: "string" } } },
     flows: [{
         title: "Greet",

package/examples/02-data-extraction.ts

@@ -40,7 +40,7 @@ const agent = createAgent<Record<string, never>, BookingData>({
     name: "Booking Agent",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "models/gemini-2.5-flash",
+        model: "gemini-3.1-flash-lite",
     }),
     schema,
     flows: [

package/examples/03-tools.ts

@@ -99,7 +99,7 @@ const agent = createAgent<AppContext, AppData>({
     name: "BookingAgent",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "models/gemini-2.5-flash",
+        model: "gemini-3.1-flash-lite",
     }),
     schema: {
         type: "object",

package/examples/04-instructions.ts

@@ -22,7 +22,7 @@ const agent = createAgent<unknown, SupportData>({
     name: "SupportBot",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY,
-        model: "models/gemini-2.5-flash",
+        model: "gemini-3.1-flash-lite",
     }),
     schema: {
         type: "object",

package/examples/05-branching.ts

@@ -13,7 +13,7 @@ interface Data { intent: string; query: string; answer: string }
 
 const provider = new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
-    model: "models/gemini-2.5-flash",
+    model: "gemini-3.1-flash-lite",
 });
 
 // ─── Steps with branches ─────────────────────────────────────────────────────

package/examples/06-flow-control.ts

@@ -19,7 +19,7 @@ const agent = createAgent<{}, AppData>({
     name: "FlowControlDemo",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "models/gemini-2.5-flash",
+        model: "gemini-3.1-flash-lite",
     }),
     schema: {
         type: "object",

package/examples/07-streaming.ts

@@ -18,7 +18,7 @@ const agent = createAgent<{}, AppData>({
     name: "StreamingDemo",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "models/gemini-2.5-flash",
+        model: "gemini-3.1-flash-lite",
     }),
     schema: {
         type: "object",

package/examples/08-persistence.ts

@@ -7,7 +7,7 @@ if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
 
 const provider = new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY,
-    model: "models/gemini-2.5-flash",
+    model: "gemini-3.1-flash-lite",
 });
 
 const schema = {

package/examples/09-signals.ts

@@ -100,7 +100,7 @@ const agent = createAgent<AppContext, AppData>({
     name: "SupportAgent",
     provider: new GeminiProvider({
         apiKey: process.env.GEMINI_API_KEY!,
-        model: "models/gemini-2.5-flash",
+        model: "gemini-3.1-flash-lite",
     }),
     context: { supportTier: "free" },
     schema: {

package/examples/tsconfig.json

@@ -7,9 +7,7 @@
             "DOM"
         ],
         "moduleResolution": "bundler",
-        "types": [
-            "@types/bun"
-        ],
+        "types": [],
         "strict": true,
         "esModuleInterop": true,
         "skipLibCheck": true,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@falai/agent",
-  "version": "2.0.0",
-  "description": "Standalone, strongly-typed AI Agent framework with route DSL and AI provider strategy",
+  "version": "2.1.0",
+  "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",
   "module": "./dist/index.js",
@@ -36,7 +36,7 @@
   "bugs": {
     "url": "https://github.com/falai-dev/agent/issues"
   },
-  "homepage": "https://github.com/falai-dev/agent#readme",
+  "homepage": "https://falai.dev",
   "scripts": {
     "build": "npm run build:esm && npm run build:cjs && npm run fix:cjs",
     "build:esm": "tsc",
@@ -65,11 +65,15 @@
     "typescript",
     "conversational",
     "gemini",
+    "openai",
+    "anthropic",
     "llm",
     "chatbot",
     "framework",
-    "routes",
-    "dsl"
+    "flows",
+    "schema",
+    "directives",
+    "signals"
   ],
   "author": "Gustavo Salomé <gusnips>",
   "license": "MIT",

package/src/core/Agent.ts

@@ -1225,7 +1225,7 @@ export class Agent<TContext = any, TData = any> {
       }
     }
 
-    // Strip PreDirective-only fields before storing
+    // Strip pre-LLM-only fields before storing
     const stripped = this.stripPreDirectiveFields(directive);
 
     // Set pendingDirective on the session without applying it
@@ -1439,7 +1439,7 @@ export class Agent<TContext = any, TData = any> {
   }
 
   /**
-   * Strip PreDirective-only fields (appendPrompt, injectTools, halt) from a directive.
+   * Strip pre-LLM-only fields (appendPrompt, injectTools, halt) from a directive.
    * These fields are transient (one-turn lifetime) and must not be persisted.
    * @private
    */
@@ -1452,8 +1452,8 @@ export class Agent<TContext = any, TData = any> {
     const { appendPrompt, injectTools, halt, ...rest } = raw;
 
     if (appendPrompt || injectTools || halt !== undefined) {
-      logger.debug(
-        `[Agent] Stripped PreDirective-only fields before storing pendingDirective: ` +
+      logger.warn(
+        `[Agent] Ignoring pre-LLM-only fields on pendingDirective (these only take effect in onEnter/prepare hooks): ` +
         `${[appendPrompt && 'appendPrompt', injectTools && 'injectTools', halt !== undefined && 'halt'].filter(Boolean).join(', ')}`
       );
     }

package/src/core/AutoChainExecutor.ts

@@ -25,7 +25,7 @@ import type { StoppedReason } from "../types/flow";
 
 /**
  * The directive-like object that `prepare` may return on auto-steps.
- * This is a structural subset of the full PreDirective that v2 will formalize.
+ * This is a structural subset of Directive (pre-LLM fields).
  */
 export interface AutoStepPrepareResult {
     dataUpdate?: Record<string, unknown>;
@@ -292,7 +292,7 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
 
     /**
      * Run onEnter and prepare hooks for an auto-step, collecting any
-     * PreDirective-like return values.
+     * Directive return values (pre-LLM fields honored).
      */
     private async runStepHooks(
         step: Step<TContext, TData>,
@@ -310,7 +310,7 @@ export class AutoChainExecutor<TContext = unknown, TData = unknown> {
             }
         }
 
-        // prepare hook — for auto-steps, prepare may return a PreDirective-like object
+        // prepare hook — for auto-steps, prepare may return a Directive with pre-LLM fields
         if (step.prepare) {
             if (typeof step.prepare === 'function') {
                 const prepareResult = await (step.prepare as (

package/src/core/PromptComposer.ts

@@ -419,7 +419,7 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
    * Build the final prompt string.
    *
    * @param options.transientAppendage - Per-turn sentences from merged
-   *   PreDirective.appendPrompt arrays (outer-to-inner: agent.onEnter →
+   *   Directive.appendPrompt arrays (outer-to-inner: agent.onEnter →
    *   flow.onEnter → step.onEnter → step.prepare). Appended after all
    *   other sections. Fresh every turn, never cached, never persisted.
    *   **Validates: Requirements 2.2, 2.8, 2.11, 27.1, 27.2, 27.4**
@@ -434,7 +434,7 @@ export class PromptComposer<TContext = unknown, TData = unknown> {
       sections = this.parts.filter(Boolean);
     }
 
-    // Append transient per-turn sentences (from PreDirective.appendPrompt).
+    // Append transient per-turn sentences (from Directive.appendPrompt).
     // These are never cached — they are a fresh slot built per turn.
     if (options?.transientAppendage && options.transientAppendage.length > 0) {
       const appendageBlock = options.transientAppendage.join("\n");

package/src/core/ResponseEngine.ts

@@ -33,7 +33,7 @@ export interface BuildResponsePromptParams<
   // NEW: Agent-level schema for data validation
   agentSchema?: StructuredSchema;
   /**
-   * Per-turn transient appendage from merged PreDirective.appendPrompt arrays.
+   * Per-turn transient appendage from merged Directive.appendPrompt arrays.
    * Appended to the system prompt after all other sections.
    * Fresh every turn, never cached, never persisted.
    */

package/src/core/ResponseModal.ts

@@ -18,7 +18,7 @@ import type {
     ScopedInstructions,
     AppliedInstruction,
     PrepareResult,
-    PreDirective,
+    Directive,
 } from "../types";
 import type { SignalFiring } from "../types/signals";
 import type { Agent } from "./Agent";
@@ -140,7 +140,7 @@ interface ResponseContext<TContext = unknown, TData = unknown> {
     /** Signal firings accumulated across both phases (pre + post) for the response surface. */
     signalFirings?: SignalFiring<TContext, TData>[];
     /** Pre-phase merged directive from signals (non-position fields like appendPrompt, injectTools). */
-    signalPreDirective?: PreDirective<TContext, TData>;
+    signalPreDirective?: Directive<TContext, TData>;
     /** Whether the pre-signal phase emitted a halt directive. */
     signalHalted?: boolean;
     /** Reply from a halt directive. */
@@ -477,7 +477,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 session: SessionState<TData>;
                 isFlowComplete: boolean;
                 signalFirings?: SignalFiring<TContext, TData>[];
-                signalPreDirective?: PreDirective<TContext, TData>;
+                signalPreDirective?: Directive<TContext, TData>;
                 signalHalted?: boolean;
                 signalHaltReply?: string;
             };
@@ -533,7 +533,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         /** Signal firings from the pre-phase (threaded through for response surface). */
         signalFirings?: SignalFiring<TContext, TData>[];
         /** Non-position signal directive for pre-LLM augmentation (appendPrompt, injectTools, etc). */
-        signalPreDirective?: PreDirective<TContext, TData>;
+        signalPreDirective?: Directive<TContext, TData>;
         /** Pre-signal phase halted the turn. */
         signalHalted?: boolean;
         /** Reply text from the halt directive. */
@@ -752,7 +752,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         signalResult: {
             firings: SignalFiring<TContext, TData>[];
             updatedSession: SessionState<TData>;
-            mergedDirective: PreDirective<TContext, TData> | undefined;
+            mergedDirective: Directive<TContext, TData> | undefined;
         },
         _params: { session: SessionState<TData>; history: Event[]; context: TContext },
     ): {
@@ -762,7 +762,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         session: SessionState<TData>;
         isFlowComplete: boolean;
         signalFirings?: SignalFiring<TContext, TData>[];
-        signalPreDirective?: PreDirective<TContext, TData>;
+        signalPreDirective?: Directive<TContext, TData>;
         signalHalted?: boolean;
         signalHaltReply?: string;
     } {
@@ -1381,15 +1381,15 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         historyEvents: Event[];
         signal?: AbortSignal;
         /**
-         * Per-turn transient appendage from merged PreDirective.appendPrompt.
+         * Per-turn transient appendage from merged directive.appendPrompt.
          * Fresh every turn, never cached, never persisted.
          */
         transientAppendage?: string[];
         /**
-         * Merged PreDirective from the directive bus's pre-LLM phase drain.
+         * Merged directive from the directive bus's pre-LLM phase drain.
          * When `halt: true`, the LLM call is skipped entirely.
          */
-        mergedPreDirective?: PreDirective<TContext, TData>;
+        mergedPreDirective?: Directive<TContext, TData>;
     }): Promise<{
         message: string;
         toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
@@ -1503,7 +1503,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         // ── STEP.REPLY SHORT-CIRCUIT (Requirement 25.1–25.7, 17.9) ──────────────
         // A step with `reply` set emits a verbatim template response without LLM.
         // onEnter and prepare have already fired normally at this point.
-        // If prepare returned a PreDirective with `reply`, that overrides
+        // If prepare returned a Directive with `reply`, that overrides
         // the step-declared reply (last-emission-wins per Algorithm 4).
         if (nextStep.reply != null) {
             // Determine the effective reply: prepare-emitted reply wins over step-declared
@@ -1515,7 +1515,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             return { message: effectiveReply, session, stoppedReason: 'reply' };
         }
 
-        // Transient appendage: per-turn slot from PreDirective.appendPrompt.
+        // Transient appendage: per-turn slot from Directive.appendPrompt.
         // Fresh each turn, never cached, never persisted.
         // Wrapped in try/finally to ensure cleanup even on abnormal termination.
         let turnTransientAppendage: string[] | undefined = transientAppendage;
@@ -1592,7 +1592,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             return { message, toolCalls, session, appliedInstructions };
         } finally {
             // Drain the transient appendage at end of turn.
-            // This ensures PreDirective.appendPrompt does not leak to subsequent
+            // This ensures Directive.appendPrompt does not leak to subsequent
             // turns even when the turn terminates abnormally (error, abort, reject).
             turnTransientAppendage = undefined;
         }
@@ -1799,15 +1799,15 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         historyEvents: Event[];
         signal?: AbortSignal;
         /**
-         * Per-turn transient appendage from merged PreDirective.appendPrompt.
+         * Per-turn transient appendage from merged directive.appendPrompt.
          * Fresh every turn, never cached, never persisted.
          */
         transientAppendage?: string[];
         /**
-         * Merged PreDirective from the directive bus's pre-LLM phase drain.
+         * Merged directive from the directive bus's pre-LLM phase drain.
          * When `halt: true`, the LLM call is skipped entirely.
          */
-        mergedPreDirective?: PreDirective<TContext, TData>;
+        mergedPreDirective?: Directive<TContext, TData>;
     }): AsyncGenerator<AgentResponseStreamChunk<TData>> {
         const { selectedFlow, selectedStep, responseDirectives, history, context, historyEvents, signal, transientAppendage, mergedPreDirective } = params;
         let session = params.session;
@@ -1918,7 +1918,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         // ── STEP.REPLY SHORT-CIRCUIT (Requirement 25.1–25.7, 17.9) ──────────────
         // A step with `reply` set emits a verbatim template response without LLM.
         // onEnter and prepare have already fired normally. If prepare returned
-        // a PreDirective with `reply`, that overrides the step-declared reply.
+        // a Directive with `reply`, that overrides the step-declared reply.
         if (nextStep.reply != null) {
             const effectiveReply = mergedPreDirective?.reply ?? await render(
                 nextStep.reply,
@@ -1937,7 +1937,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             return;
         }
 
-        // Transient appendage: per-turn slot from PreDirective.appendPrompt.
+        // Transient appendage: per-turn slot from Directive.appendPrompt.
         // Fresh each turn, never cached, never persisted.
         // Wrapped in try/finally to ensure cleanup even on abnormal termination.
         let turnTransientAppendage: string[] | undefined = transientAppendage;
@@ -2092,7 +2092,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             }
         } finally {
             // Drain the transient appendage at end of turn.
-            // This ensures PreDirective.appendPrompt does not leak to subsequent
+            // This ensures Directive.appendPrompt does not leak to subsequent
             // turns even when the turn terminates abnormally (error, abort, reject).
             turnTransientAppendage = undefined;
         }

package/src/core/ResponsePipeline.ts

@@ -9,7 +9,6 @@ import type {
   AgentStructuredResponse,
   Tool,
   Directive,
-  PreDirective,
 } from "../types";
 import type { SignalFiring } from "../types/signals";
 import type { SignalProcessor } from "./SignalProcessor";
@@ -162,7 +161,7 @@ export class ResponsePipeline<TContext = unknown, TData = unknown> {
   ): Promise<{
     firings: SignalFiring<TContext, TData>[];
     updatedSession: SessionState<TData>;
-    mergedDirective: PreDirective<TContext, TData> | undefined;
+    mergedDirective: Directive<TContext, TData> | undefined;
   }> {
     if (!this.signalProcessor) {
       return { firings: [], updatedSession: session, mergedDirective: undefined };