@falai/agent 2.0.0 → 2.1.0

package/src/core/SignalProcessor.ts

@@ -15,7 +15,7 @@ import type { AiProvider } from "../types/ai";
 import type { Event } from "../types/history";
 import { MessageRole as MessageRoleEnum } from "../types/history";
 import type { SessionState } from "../types/session";
-import type { PreDirective, Directive } from "../types/flow";
+import type { Directive } from "../types/flow";
 import type {
     Signal,
     SignalContext,
@@ -295,14 +295,14 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
 
     /**
      * Pre-signal phase. Delegates to `runPhase('pre', ...)`.
-     * Return type narrows `mergedDirective` to `PreDirective | undefined`.
+     * Return type narrows `mergedDirective` to `Directive | undefined`.
      */
     async runPreSignalPhase(params: {
         session: SessionState<TData>;
         history: Event[];
         context: TContext;
     }): Promise<{
-        mergedDirective?: PreDirective<TContext, TData>;
+        mergedDirective?: Directive<TContext, TData>;
         firings: SignalFiring<TContext, TData>[];
         updatedSession: SessionState<TData>;
     }> {
@@ -335,7 +335,7 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
         phase: 'pre' | 'post',
         params: { session: SessionState<TData>; history: Event[]; context: TContext },
     ): Promise<{
-        mergedDirective?: PreDirective<TContext, TData>;
+        mergedDirective?: Directive<TContext, TData>;
         firings: SignalFiring<TContext, TData>[];
         updatedSession: SessionState<TData>;
     }> {
@@ -584,7 +584,7 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
         }
 
         // ── STEP 9: merge directives ─────────────────────────────────────────
-        let mergedDirective: PreDirective<TContext, TData> | undefined;
+        let mergedDirective: Directive<TContext, TData> | undefined;
 
         if (bus.length > 0) {
             mergedDirective = this.mergeDirectives(bus);
@@ -633,8 +633,8 @@ export class SignalProcessor<TContext = unknown, TData = unknown> {
      */
     private mergeDirectives(
         directives: SignalDirective<TContext, TData>[],
-    ): PreDirective<TContext, TData> {
-        const merged: PreDirective<TContext, TData> = {};
+    ): Directive<TContext, TData> {
+        const merged: Directive<TContext, TData> = {};
 
         for (const d of directives) {
             // Position fields — last-write-wins

package/src/core/Step.ts

@@ -1,5 +1,5 @@
 /**
- * Step in the route DSL
+ * Step in a conversational flow
  */
 
 import type {

package/src/core/ToolManager.ts

@@ -62,7 +62,7 @@ export class ToolManager<TContext = unknown, TData = unknown> {
   private toolRegistry: Map<string, Tool<TContext, TData>>;
 
   /**
-   * Per-turn transient tool layer populated from PreDirective.injectTools.
+   * Per-turn transient tool layer populated from Directive.injectTools.
    * Resolution order: transient → step → flow → agent.
    * Drained at end of turn via try/finally guard.
    *

package/src/core/flow-namespace.ts

@@ -25,7 +25,12 @@ const POSITION_PRECEDENCE: Record<PositionField, number> = {
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-function getSetPositionFields(d: Directive): PositionField[] {
+/** Structural type for anything that has position fields (read-only access). */
+type HasPositionFields = {
+    readonly [K in PositionField]?: unknown;
+};
+
+function getSetPositionFields(d: HasPositionFields): PositionField[] {
     return POSITION_FIELDS.filter((f) => d[f] !== undefined && d[f] !== null);
 }
 
@@ -44,7 +49,7 @@ function beatsCurrent(
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 /**
- * Type guard: is `x` a Directive (or any subtype like PreDirective)?
+ * Type guard: is `x` a Directive (or any subtype like SignalDirective)?
  *
  * A value is considered a Directive if it is a non-null object. The Directive
  * interface has all-optional fields, so any plain object qualifies structurally.
@@ -65,31 +70,31 @@ function isDirective(x: unknown): x is Directive {
  *   ties broken by emission order (b wins over a — last wins).
  * - reply: last-wins (b.reply overrides a.reply if set).
  * - dataUpdate / contextUpdate: shallow-merge (b overrides a on key collision).
- * - appendPrompt / injectTools (PreDirective fields): concatenate then dedupe.
+ * - appendPrompt / injectTools (pre-LLM fields): concatenate then dedupe.
  * - halt: logical-OR.
  */
-function merge<T extends Directive>(a: T, b: T): T {
+function merge<TContext, TData>(a: Directive<TContext, TData>, b: Directive<TContext, TData>): Directive<TContext, TData> {
     const result = {} as Record<string, unknown>;
 
     // ── Position field: winner-takes-all by precedence, b wins ties ──
-    const aPos = getSetPositionFields(a as Directive);
-    const bPos = getSetPositionFields(b as Directive);
+    const aPos = getSetPositionFields(a);
+    const bPos = getSetPositionFields(b);
 
     // Pick the highest-priority position field across both directives.
     // b's fields are evaluated after a's, so b wins on same precedence (last-wins).
     let winnerField: PositionField | null = null;
-    let winnerSource: Directive | null = null;
+    let winnerSource: Directive<TContext, TData> | null = null;
 
     for (const field of aPos) {
         if (beatsCurrent(field, winnerField)) {
             winnerField = field;
-            winnerSource = a as Directive;
+            winnerSource = a;
         }
     }
     for (const field of bPos) {
         if (beatsCurrent(field, winnerField)) {
             winnerField = field;
-            winnerSource = b as Directive;
+            winnerSource = b;
         }
     }
 
@@ -98,54 +103,30 @@ function merge<T extends Directive>(a: T, b: T): T {
     }
 
     // ── reply: last-wins ──
-    if ((b as Directive).reply !== undefined) {
-        result.reply = (b as Directive).reply;
-    } else if ((a as Directive).reply !== undefined) {
-        result.reply = (a as Directive).reply;
+    if (b.reply !== undefined) {
+        result.reply = b.reply;
+    } else if (a.reply !== undefined) {
+        result.reply = a.reply;
     }
 
     // ── dataUpdate: shallow merge ──
-    const aData = (a as Record<string, unknown>).dataUpdate as
-        | Record<string, unknown>
-        | undefined;
-    const bData = (b as Record<string, unknown>).dataUpdate as
-        | Record<string, unknown>
-        | undefined;
-    if (aData || bData) {
-        result.dataUpdate = { ...aData, ...bData };
+    if (a.dataUpdate || b.dataUpdate) {
+        result.dataUpdate = { ...a.dataUpdate, ...b.dataUpdate };
     }
 
     // ── contextUpdate: shallow merge ──
-    const aCtx = (a as Record<string, unknown>).contextUpdate as
-        | Record<string, unknown>
-        | undefined;
-    const bCtx = (b as Record<string, unknown>).contextUpdate as
-        | Record<string, unknown>
-        | undefined;
-    if (aCtx || bCtx) {
-        result.contextUpdate = { ...aCtx, ...bCtx };
+    if (a.contextUpdate || b.contextUpdate) {
+        result.contextUpdate = { ...a.contextUpdate, ...b.contextUpdate };
     }
 
-    // ── appendPrompt (PreDirective): concatenate ──
-    const aPrompt = (a as Record<string, unknown>).appendPrompt as
-        | string[]
-        | undefined;
-    const bPrompt = (b as Record<string, unknown>).appendPrompt as
-        | string[]
-        | undefined;
-    if (aPrompt || bPrompt) {
-        result.appendPrompt = [...(aPrompt ?? []), ...(bPrompt ?? [])];
+    // ── appendPrompt (pre-LLM): concatenate ──
+    if (a.appendPrompt || b.appendPrompt) {
+        result.appendPrompt = [...(a.appendPrompt ?? []), ...(b.appendPrompt ?? [])];
     }
 
-    // ── injectTools (PreDirective): concatenate then dedupe by id (last wins) ──
-    const aTools = (a as Record<string, unknown>).injectTools as
-        | Array<{ id: string;[k: string]: unknown }>
-        | undefined;
-    const bTools = (b as Record<string, unknown>).injectTools as
-        | Array<{ id: string;[k: string]: unknown }>
-        | undefined;
-    if (aTools || bTools) {
-        const combined = [...(aTools ?? []), ...(bTools ?? [])];
+    // ── injectTools (pre-LLM): concatenate then dedupe by id (last wins) ──
+    if (a.injectTools || b.injectTools) {
+        const combined = [...(a.injectTools ?? []), ...(b.injectTools ?? [])];
         // Dedupe by id — last definition wins
         const seen = new Map<string, (typeof combined)[number]>();
         for (const tool of combined) {
@@ -154,14 +135,12 @@ function merge<T extends Directive>(a: T, b: T): T {
         result.injectTools = Array.from(seen.values());
     }
 
-    // ── halt (PreDirective): logical OR ──
-    const aHalt = (a as Record<string, unknown>).halt as boolean | undefined;
-    const bHalt = (b as Record<string, unknown>).halt as boolean | undefined;
-    if (aHalt || bHalt) {
+    // ── halt (pre-LLM): logical OR ──
+    if (a.halt || b.halt) {
         result.halt = true;
     }
 
-    return result as T;
+    return result as Directive<TContext, TData>;
 }
 
 /**
@@ -170,7 +149,7 @@ function merge<T extends Directive>(a: T, b: T): T {
  * - `goTo` set as empty object `{}` (no flow target).
  * - `reply` co-existing with `abort` (abort ends the conversation; a reply is nonsensical).
  */
-function validate(d: Directive): void {
+function validate<TContext, TData>(d: Directive<TContext, TData>): void {
     // ── Multiple position fields ──
     const setFields = getSetPositionFields(d);
     if (setFields.length > 1) {

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
- * @falai/agent - Standalone AI Agent framework
+ * @falai/agent — Conversational state engine for TypeScript
  *
- * A strongly-typed, modular agent framework with flow DSL and AI provider strategy
+ * The AI understands. The code is in control.
  */
 
 // Core
@@ -173,7 +173,6 @@ export type {
   StoppedReason,
   PrepareResult,
   Directive,
-  PreDirective,
   BranchEntry,
   BranchMap,
   BranchPredicate,

package/src/providers/AnthropicProvider.ts

@@ -30,7 +30,7 @@ const DEFAULT_RETRY_CONFIG = {
 export interface AnthropicProviderOptions {
   /** Anthropic API key */
   apiKey: string;
-  /** Model to use (required) - e.g., "claude-sonnet-4-5", "claude-opus-4-1" */
+  /** Model to use (required) - e.g., "claude-sonnet-4-6", "claude-opus-4-7" */
   model: string;
   /** Backup models to try if primary fails (default: []) */
   backupModels?: string[];
@@ -138,7 +138,7 @@ export class AnthropicProvider implements AiProvider {
     }
 
     if (!model) {
-      throw new Error("Model is required. Example: 'claude-sonnet-4-5'");
+      throw new Error("Model is required. Example: 'claude-sonnet-4-6'");
     }
 
     this.client = new Anthropic({

package/src/providers/GeminiProvider.ts

@@ -36,7 +36,7 @@ const DEFAULT_RETRY_CONFIG = {
 export interface GeminiProviderOptions {
   /** Gemini API key */
   apiKey: string;
-  /** Model to use (required) - e.g., "models/gemini-2.5-pro" */
+  /** Model to use (required) - e.g., "gemini-3.1-pro-preview" */
   model: string;
   /** Backup models to try if primary fails (default: []) */
   backupModels?: string[];
@@ -140,7 +140,7 @@ export class GeminiProvider implements AiProvider {
     }
 
     if (!model) {
-      throw new Error("Model is required. Example: 'models/gemini-2.5-pro'");
+      throw new Error("Model is required. Example: 'gemini-3.1-pro-preview'");
     }
 
     this.genAI = new GoogleGenAI({ apiKey });

package/src/providers/OpenAIProvider.ts

@@ -31,7 +31,7 @@ export interface OpenAIProviderOptions {
   apiKey: string;
   /** Organization ID (optional) */
   organization?: string;
-  /** Model to use (required) - e.g., "gpt-5", "gpt-5-mini" */
+  /** Model to use (required) - e.g., "gpt-5.5", "gpt-5.4" */
   model: string;
   /** Backup models to try if primary fails (default: []) */
   backupModels?: string[];
@@ -144,7 +144,7 @@ export class OpenAIProvider implements AiProvider {
     }
 
     if (!model) {
-      throw new Error("Model is required. Example: 'gpt-5' or 'gpt-5-mini'");
+      throw new Error("Model is required. Example: 'gpt-5.5' or 'gpt-5.4'");
     }
 
     // Dynamic import to avoid bundling issues

package/src/types/agent.ts

@@ -146,7 +146,7 @@ export interface AgentOptions<TContext = unknown, TData = unknown> {
   contextProvider?: ContextProvider<TContext>;
   /** Lifecycle hooks for context management */
   hooks?: ContextLifecycleHooks<TContext, TData>;
-  /** AI provider strategy for generating responses */
+  /** AI provider for generating responses */
   provider: AiProvider;
   /** Initial terms for domain glossary */
   terms?: Term<TContext, TData>[];

package/src/types/ai.ts

@@ -1,5 +1,5 @@
 /**
- * AI provider strategy types
+ * AI provider types
  */
 
 import type { HistoryItem } from "./history";

package/src/types/flow.ts

@@ -79,54 +79,61 @@ export interface PrepareResult {
 // ─── Branch types ────────────────────────────────────────────────────────────
 
 /**
- * A programmatic transition directive. Encodes where to go and what state
- * writes to apply. Used as the `then` target of a `BranchEntry` when the
- * destination is more complex than a simple step/flow id string.
+ * A programmatic transition directive. The single shape any tool, hook, branch,
+ * or signal handler returns to write state, redirect the conversation, or speak
+ * verbatim.
  *
  * At most one position field (`goTo`, `goToStep`, `complete`, `abort`, `reset`)
  * may be set per Directive. Non-position fields (`reply`, `contextUpdate`,
  * `dataUpdate`) may accompany any position field.
+ *
+ * Pre-LLM augmentation fields (`appendPrompt`, `injectTools`, `halt`) are
+ * one-turn-lifetime: they only take effect in pre-LLM hooks (`onEnter`,
+ * `prepare`). When emitted from post-LLM hooks (`finalize`, `onComplete`) or
+ * persisted to `session.pendingDirective`, these fields are ignored and a WARN
+ * log is emitted. They are never serialized across turns.
  */
 export interface Directive<TContext = unknown, TData = unknown> {
+  // ── Position fields (mutually exclusive: at most one) ────────────
   /** Jump to a flow (string) or a flow with options (object). */
   goTo?: string | { flow?: string; step?: string; data?: Partial<TData>; reason?: string; carry?: 'preserve' | 'reset'; };
   /** Jump to a specific step, optionally in another flow. */
   goToStep?: string | { step: string; flow?: string; data?: Partial<TData>; reason?: string; };
   /** Mark the current flow as complete. */
-  complete?: true | { next?: Directive<TContext, TData>; reason?: string; };
+  complete?: true | { next?: Directive<unknown, unknown>; reason?: string; };
   /** Abort the current flow. */
   abort?: string | { reason: string; clearSession?: boolean; };
   /** Reset the current flow (or jump to a step within it). */
   reset?: true | { step?: string; clearData?: boolean; reason?: string; };
+
+  // ── Verbatim utterance ───────────────────────────────────────────
   /** Verbatim reply text to send to the user. */
   reply?: string;
+
+  // ── State writes ─────────────────────────────────────────────────
   /** Partial context update applied before the next turn. */
   contextUpdate?: Partial<TContext>;
   /** Partial data update applied before the next turn. */
   dataUpdate?: Partial<TData>;
-}
 
-/**
- * PreDirective — what `prepare` hooks and `onEnter` hooks return.
- * Adds prompt/tool shaping that only makes sense BEFORE the LLM call this turn.
- * Extends Directive — anything a Directive can do, a PreDirective can do too.
- *
- * NOT persistable: contains live Tool references and a halt flag that
- * has no meaning across turns. This type is transient (one-turn lifetime).
- */
-export interface PreDirective<TContext = unknown, TData = unknown>
-  extends Directive<TContext, TData> {
+  // ── Pre-LLM augmentation (one-turn lifetime) ─────────────────────
   /**
    * Sentences to append to the system prompt for THIS turn only.
    * Wired through PromptComposer's per-turn appendage slot.
+   *
+   * Only meaningful in pre-LLM hooks (`onEnter`, `prepare`). Ignored with
+   * a WARN log when emitted from post-LLM hooks or persisted.
    */
   appendPrompt?: string[];
 
   /**
    * Tools available for THIS turn only. Stacked on top of agent/flow/step
    * tool scopes via ToolManager's transient layer.
+   *
+   * Only meaningful in pre-LLM hooks (`onEnter`, `prepare`). Ignored with
+   * a WARN log when emitted from post-LLM hooks or persisted.
    */
-  injectTools?: Array<Tool<TContext, TData>>;
+  injectTools?: Tool[];
 
   /**
    * If true, skip the LLM call entirely this turn.
@@ -135,10 +142,15 @@ export interface PreDirective<TContext = unknown, TData = unknown>
    * assistant output (`stoppedReason: 'reply'`). When `halt` is true
    * without `reply`, the turn produces an empty assistant message
    * (`stoppedReason: 'halt'`).
+   *
+   * Only meaningful in pre-LLM hooks (`onEnter`, `prepare`). Ignored with
+   * a WARN log when emitted from post-LLM hooks or persisted.
    */
   halt?: boolean;
 }
 
+
+
 /**
  * Context passed to a `BranchPredicate` function.
  *
@@ -241,7 +253,7 @@ export interface StepRef {
 /**
  * Flow lifecycle hooks for managing flow-specific data and behavior.
  *
- * Pre-LLM hooks (`onEnter`) return `void | PreDirective`.
+ * Pre-LLM hooks (`onEnter`) return `void | Directive`.
  * Post-LLM hooks (`onComplete`) return `void | Directive`.
  * Informational hooks (`onExit`) return `void`.
  * Data hooks (`onDataUpdate`, `onContextUpdate`) retain their v1 signatures.
@@ -249,11 +261,12 @@ export interface StepRef {
 export interface FlowLifecycleHooks<TContext = unknown, TData = unknown> {
   /**
    * Called when the flow is first entered.
-   * May return a PreDirective to augment the prompt, inject tools, or halt.
+   * May return a Directive to augment the prompt, inject tools, halt, or redirect.
+   * Pre-LLM fields (`appendPrompt`, `injectTools`, `halt`) are honored here.
    */
   onEnter?: (
     ctx: HookContext<TContext, TData>
-  ) => void | PreDirective<TContext, TData> | Promise<void | PreDirective<TContext, TData>>;
+  ) => void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
 
   /**
    * Called when the flow is exited. Informational only — cannot influence flow control.
@@ -401,18 +414,19 @@ export interface FlowOptions<TContext = unknown, TData = unknown> {
 /**
  * Step lifecycle hooks for managing step-specific behavior.
  *
- * Pre-LLM hooks (`onEnter`, `prepare`) return `void | PreDirective`.
+ * Pre-LLM hooks (`onEnter`, `prepare`) return `void | Directive`.
  * Post-LLM hooks (`finalize`) return `void | Directive`.
  * Informational hooks (`onExit`) return `void`.
  */
 export interface StepLifecycleHooks<TContext = unknown, TData = unknown> {
   /**
-   * Called on step entry. May return a PreDirective to augment the prompt,
-   * inject tools, or halt.
+   * Called on step entry. May return a Directive to augment the prompt,
+   * inject tools, halt, or redirect.
+   * Pre-LLM fields (`appendPrompt`, `injectTools`, `halt`) are honored here.
    */
   onEnter?: (
     ctx: HookContext<TContext, TData>
-  ) => void | PreDirective<TContext, TData> | Promise<void | PreDirective<TContext, TData>>;
+  ) => void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
 
   /**
    * Called when the step is exited. Informational only — cannot influence flow control.
@@ -424,12 +438,13 @@ export interface StepLifecycleHooks<TContext = unknown, TData = unknown> {
   ) => void | Promise<void>;
 
   /**
-   * Called pre-LLM. May return a PreDirective to augment the prompt,
+   * Called pre-LLM. May return a Directive to augment the prompt,
    * inject tools, or halt the LLM call.
+   * Pre-LLM fields (`appendPrompt`, `injectTools`, `halt`) are honored here.
    */
   prepare?: (
     ctx: HookContext<TContext, TData>
-  ) => void | PreDirective<TContext, TData> | Promise<void | PreDirective<TContext, TData>>;
+  ) => void | Directive<TContext, TData> | Promise<void | Directive<TContext, TData>>;
 
   /**
    * Called post-LLM. May return a Directive to redirect flow, write state,
@@ -524,7 +539,7 @@ export interface StepOptions<TContext = unknown, TData = unknown> {
    * at construction time.
    *
    * `onEnter` and `prepare` hooks fire normally before the reply is rendered.
-   * If `prepare` returns a `PreDirective` with its own `reply` field, the
+   * If `prepare` returns a Directive with its own `reply` field, the
    * hook-emitted reply wins (last-emission-wins per Algorithm 4).
    *
    * After emission, `onExit` fires and `branches` are resolved for next step.

package/src/types/index.ts

@@ -52,7 +52,6 @@ export type {
   FlowLifecycleHooks,
   StepLifecycleHooks,
   Directive,
-  PreDirective,
   BranchEntry,
   BranchMap,
   BranchPredicate,

package/src/types/signals.ts

@@ -8,7 +8,7 @@
  */
 
 import type { SessionState } from "./session";
-import type { PreDirective } from "./flow";
+import type { Directive } from "./flow";
 import type { Event } from "./history";
 
 // ──────────────────────────────────────────────────────────────────────────────
@@ -100,19 +100,18 @@ export type SignalPredicate<TContext = unknown, TData = unknown> = (
 
 /**
  * SignalDirective — what signal handlers return.
- * Extends `PreDirective` (which extends `Directive`). Adds signal-specific
- * fields: `stopOtherSignals` and `replyWith`.
+ * Extends `Directive`. Adds signal-specific fields: `stopOtherSignals` and `replyWith`.
  *
  * All position-control (`goTo`, `goToStep`, `complete`, `abort`, `reset`),
  * state writes (`dataUpdate`, `contextUpdate`), prompt augmentation
  * (`appendPrompt`, `injectTools`), `reply`, and `halt` are inherited unchanged.
  *
  * Post-phase drop rules: when returned in the post-phase, `appendPrompt`,
- * `injectTools`, and `halt` are dropped with a debug warning — they have
+ * `injectTools`, and `halt` are dropped with a WARN log — they have
  * no meaning after the LLM call has already completed.
  */
 export interface SignalDirective<TContext = unknown, TData = unknown>
-    extends PreDirective<TContext, TData> {
+    extends Directive<TContext, TData> {
     /**
      * Stop processing remaining signals for this phase after this handler.
      * Does not affect the other phase.

package/src/utils/session.ts

@@ -262,7 +262,7 @@ export function sessionStepToData<TData = Record<string, unknown>>(
   currentStep?: string;
   collectedData: CollectedStateData<TData>;
 } {
-  // Strip PreDirective fields before persisting pendingDirective
+  // Strip pre-LLM-only fields before persisting pendingDirective
   let pendingDirective: SessionState<TData>["pendingDirective"] | undefined;
   if (session.pendingDirective) {
     pendingDirective = stripPreDirectiveFields(session.pendingDirective);
@@ -354,7 +354,7 @@ export function sessionDataToStep<TData = Record<string, unknown>>(
 
 
 /**
- * Strip PreDirective-only fields from a directive before persistence.
+ * Strip pre-LLM-only fields from a directive before persistence.
  *
  * `appendPrompt`, `injectTools`, and `halt` are transient (one-turn lifetime)
  * and must not be serialized. This is a belt-and-suspenders safety net —
@@ -380,8 +380,8 @@ function stripPreDirectiveFields<TData>(
   ].filter(Boolean);
 
   if (droppedFields.length > 0) {
-    logger.debug(
-      `[createPersistedState] Stripped PreDirective-only fields before persistence: ${droppedFields.join(", ")}`
+    logger.warn(
+      `[createPersistedState] Ignoring pre-LLM-only fields before persistence (these have no effect outside pre-LLM hooks): ${droppedFields.join(", ")}`
     );
   }
 
@@ -393,7 +393,7 @@ function stripPreDirectiveFields<TData>(
  *
  * This is the shared helper that every persistence adapter should call before
  * writing session state. It ensures:
- * - `pendingDirective` has PreDirective-only fields (`appendPrompt`,
+ * - `pendingDirective` has pre-LLM-only fields (`appendPrompt`,
  *   `injectTools`, `halt`) stripped (these are one-turn-lifetime and not
  *   serializable across turns).
  * - `pendingDirective` is omitted from the result when `undefined` (adapters