@falai/agent 2.0.1 → 2.1.0

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/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.
 

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.1",
-  "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 };

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,