@falai/agent 1.2.8 → 2.0.0

package/dist/core/Agent.js

@@ -1,12 +1,15 @@
 /**
  * Core Agent implementation
  */
-import { CompositionMode } from "../types";
-import { mergeCollected, logger, LoggerLevel, render, createTemplateContext, createConditionEvaluator, } from "../utils";
-import { Route } from "./Route";
+import { NotImplementedError } from "../types/errors";
+import { SignalProcessor } from "./SignalProcessor";
+import { SignalEvaluator } from "./SignalEvaluator";
+import { mergeCollected, enterFlow, enterStep, completeCurrentFlow, logger, LoggerLevel, generateSignalId, } from "../utils";
+import { Flow } from "./Flow";
+import { FlowConfigurationError as StepFlowConfigurationError } from "./Step";
 import { PersistenceManager } from "./PersistenceManager";
 import { SessionManager } from "./SessionManager";
-import { RoutingEngine } from "./RoutingEngine";
+import { FlowRouter } from "./FlowRouter";
 import { PromptSectionCache } from "./PromptSectionCache";
 import { ResponseModal } from "./ResponseModal";
 import { ToolManager } from "./ToolManager";
@@ -22,14 +25,14 @@ class DataValidationError extends Error {
     }
 }
 /**
- * Error thrown when route configuration is invalid
+ * Error thrown when flow configuration is invalid
  */
-class RouteConfigurationError extends Error {
-    constructor(routeTitle, invalidFields, message) {
-        super(message || `Route configuration error in '${routeTitle}'`);
-        this.routeTitle = routeTitle;
+class FlowConfigurationError extends Error {
+    constructor(flowTitle, invalidFields, message) {
+        super(message || `Flow configuration error in '${flowTitle}'`);
+        this.flowTitle = flowTitle;
         this.invalidFields = invalidFields;
-        this.name = "RouteConfigurationError";
+        this.name = "FlowConfigurationError";
     }
 }
 /**
@@ -40,13 +43,75 @@ export class Agent {
     constructor(options) {
         this.options = options;
         this._terms = [];
-        this._guidelines = [];
+        this._instructions = [];
         this._tools = [];
-        this._routes = [];
-        this._rules = [];
-        this._prohibitions = [];
+        this._flows = [];
         this._knowledgeBase = {};
         this._collectedData = {};
+        this.maxAutoStepsPerTurn = options.maxAutoStepsPerTurn ?? 10;
+        this.maxDirectiveChain = options.maxDirectiveChain ?? 10;
+        // Validate routerMode reservation — only 'ai' is supported in v2.0
+        if (options.routerMode !== undefined && options.routerMode !== 'ai') {
+            throw new NotImplementedError(`[NotImplementedError] routerMode "${String(options.routerMode)}" is not implemented: only "ai" is supported in v2.0. ` +
+                `Set routerMode to "ai" or omit the option.`);
+        }
+        // ─── Signal construction-time validation (Requirements 1.4, 1.5, 1.6, 1.9, 2.3) ───
+        const rawSignals = options.signals ?? [];
+        // Auto-generate stable ids for entries without `id`
+        for (let i = 0; i < rawSignals.length; i++) {
+            if (!rawSignals[i].id) {
+                rawSignals[i] = {
+                    ...rawSignals[i],
+                    id: generateSignalId(rawSignals[i].title, rawSignals[i].description, i),
+                };
+            }
+        }
+        // Validate unique ids (Requirement 1.4)
+        const idCounts = new Map();
+        for (const signal of rawSignals) {
+            const id = signal.id;
+            idCounts.set(id, (idCounts.get(id) ?? 0) + 1);
+        }
+        const duplicateIds = [...idCounts.entries()]
+            .filter(([, count]) => count > 1)
+            .map(([id]) => id);
+        if (duplicateIds.length > 0) {
+            throw new StepFlowConfigurationError(`[FlowConfigurationError] Duplicate signal ids: ${duplicateIds.join(', ')}. ` +
+                `Each signal must have a unique id.`);
+        }
+        // Validate signalBatchSize (positive integer when set)
+        if (options.signalBatchSize !== undefined) {
+            if (!Number.isInteger(options.signalBatchSize) ||
+                options.signalBatchSize <= 0) {
+                throw new StepFlowConfigurationError(`[FlowConfigurationError] signalBatchSize must be a positive integer, got: ${options.signalBatchSize}.`);
+            }
+        }
+        // Validate each signal's configuration
+        for (const signal of rawSignals) {
+            // Requirement 1.5: cooldown without cooldownMs → debug warning, treat as 'always'
+            if (signal.behavior === 'cooldown' && signal.cooldownMs == null) {
+                logger.debug(`[Agent] Signal "${signal.id}" has behavior 'cooldown' but no cooldownMs. Treating as 'always'.`);
+                signal.behavior = 'always';
+            }
+            // Requirement 1.9: validate extract schema is a JSON Schema object
+            if (signal.extract !== undefined) {
+                if (signal.extract === null ||
+                    typeof signal.extract !== 'object' ||
+                    Array.isArray(signal.extract)) {
+                    throw new StepFlowConfigurationError(`[FlowConfigurationError] Signal "${signal.id}" has an invalid extract schema. ` +
+                        `Expected a JSON Schema object, got: ${typeof signal.extract}.`);
+                }
+            }
+        }
+        this._signals = rawSignals;
+        // Requirement 2.3: Only instantiate SignalProcessor when signals are present
+        if (rawSignals.length > 0) {
+            const evaluator = new SignalEvaluator(options.provider);
+            this.signalProcessor = new SignalProcessor(rawSignals, options.provider, evaluator, { batchSize: options.signalBatchSize ?? 10 });
+        }
+        else {
+            this.signalProcessor = undefined;
+        }
         // Set log level based on debug option
         if (options.debug) {
             logger.setLevel(LoggerLevel.DEBUG);
@@ -78,10 +143,10 @@ export class Agent {
         this._currentSession = options.session;
         // Initialize prompt section cache
         this._promptSectionCache = new PromptSectionCache(options.promptCache);
-        // Initialize routing engine
-        this._routingEngine = new RoutingEngine({
-            routeSwitchMargin: options.routeSwitchMargin,
-            onRouteSwitch: () => this.invalidateRouteSections(),
+        // Initialize flow router
+        this._routingEngine = new FlowRouter({
+            flowSwitchMargin: options.flowSwitchMargin,
+            onFlowSwitch: () => this.invalidateFlowSections(),
             promptSectionCache: this._promptSectionCache,
         });
         // Initialize ResponseModal for handling all response generation
@@ -119,28 +184,25 @@ export class Agent {
                 this.createTerm(term);
             });
         }
-        if (options.guidelines) {
-            options.guidelines.forEach((guideline) => {
-                this.createGuideline(guideline);
+        // Initialize instructions (new unified form)
+        if (options.instructions) {
+            options.instructions.forEach((instruction) => {
+                this.createInstruction(instruction);
             });
         }
         if (options.tools) {
             options.tools.forEach((tool) => {
-                this.createTool(tool);
+                this.addTool(tool);
             });
         }
-        // Initialize agent-level rules and prohibitions
-        if (options.rules) {
-            this._rules = [...options.rules];
-        }
-        if (options.prohibitions) {
-            this._prohibitions = [...options.prohibitions];
-        }
-        if (options.routes) {
-            options.routes.forEach((routeOptions) => {
-                this.createRoute(routeOptions);
+        if (options.flows) {
+            options.flows.forEach((flowOptions) => {
+                this.createFlow(flowOptions);
             });
         }
+        // Validate deferred branch `then` string references against the flow registry.
+        // This catches strings that don't match a local step id AND don't match any flow id/title.
+        this.validateBranchReferences();
         // Initialize knowledge base
         if (options.knowledgeBase) {
             this._knowledgeBase = { ...options.knowledgeBase };
@@ -196,6 +258,66 @@ export class Agent {
         }
         logger.debug("[Agent] Schema validation passed");
     }
+    /**
+     * Walk every flow's steps and resolve deferred string `then` values in branches
+     * against the agent's flow registry. Strings that match neither a local step id
+     * nor any flow id/title throw FlowConfigurationError.
+     * @private
+     */
+    validateBranchReferences() {
+        for (const flow of this._flows) {
+            this.validateFlowBranchReferences(flow);
+        }
+    }
+    /**
+     * Validate branch `then` string references for a single flow against the agent's
+     * flow registry. Throws FlowConfigurationError for unresolved references.
+     * @private
+     */
+    validateFlowBranchReferences(flow) {
+        const steps = flow.getAllSteps();
+        const localStepIds = new Set(steps.map(s => s.id));
+        for (const step of steps) {
+            if (!step.branches)
+                continue;
+            for (const entry of step.branches) {
+                if (typeof entry.then !== 'string')
+                    continue;
+                // Already matches a local step id — no deferred resolution needed
+                if (localStepIds.has(entry.then))
+                    continue;
+                // Check against the agent's flow registry (id or title)
+                const matchesFlow = this._flows.some(f => f.id === entry.then || f.title === entry.then);
+                if (!matchesFlow) {
+                    throw new StepFlowConfigurationError(`[FlowConfigurationError] Unresolved branch target: "${entry.then}" in ${flow.id}.${step.id} does not match any step in the flow or any flow in the agent. ` +
+                        `Fix the branch "then" value to reference a valid step id or flow id/title.`);
+                }
+            }
+        }
+    }
+    /**
+     * Validate that every step's `collect` fields in a flow reference valid keys
+     * from the agent-level schema. Throws FlowConfigurationError at construction
+     * time if any collect field is not a valid schema key.
+     *
+     * This enforces Requirement 14.5: generic inference is preserved AND every
+     * `collect` field reference is a valid key of the inferred TData.
+     * @private
+     */
+    validateFlowCollectFields(flow) {
+        const schemaKeys = Object.keys(this._schema.properties);
+        const schemaKeySet = new Set(schemaKeys);
+        const steps = flow.getAllSteps();
+        for (const step of steps) {
+            if (!step.collect || step.collect.length === 0)
+                continue;
+            const invalidFields = step.collect.filter(field => !schemaKeySet.has(String(field)));
+            if (invalidFields.length > 0) {
+                throw new StepFlowConfigurationError(`[FlowConfigurationError] Step "${step.id}" in flow "${flow.title}" references invalid collect fields: ${invalidFields.map(f => String(f)).join(', ')}. ` +
+                    `Must be valid keys from agent schema. Available fields: ${schemaKeys.join(', ')}.`);
+            }
+        }
+    }
     /**
      * Validate data against the agent-level schema
      */
@@ -266,7 +388,7 @@ export class Agent {
         const validation = this.validateData(updates);
         if (!validation.valid) {
             const errorMessages = validation.errors.map(e => e.message).join(', ');
-            throw new DataValidationError(validation.errors, `Data validation failed: ${errorMessages}`);
+            throw new DataValidationError(validation.errors, `[DataValidationError] Data validation failed: fields [${errorMessages}] did not pass schema validation. Fix the offending values to match the declared schema.`);
         }
         // Log warnings if any
         if (validation.warnings.length > 0) {
@@ -311,16 +433,16 @@ export class Agent {
         this.options.name = value;
     }
     /**
-     * Get agent description
+     * Get agent persona
      */
-    get description() {
-        return this.options.description;
+    get persona() {
+        return this.options.persona;
     }
     /**
-     * Set agent description
+     * Set agent persona
      */
-    set description(value) {
-        this.options.description = value;
+    set persona(value) {
+        this.options.persona = value;
     }
     /**
      * Get agent goal
@@ -334,30 +456,6 @@ export class Agent {
     set goal(value) {
         this.options.goal = value;
     }
-    /**
-     * Get agent identity
-     */
-    get identity() {
-        return this.options.identity;
-    }
-    /**
-     * Set agent identity
-     */
-    set identity(value) {
-        this.options.identity = value;
-    }
-    /**
-     * Get agent personality
-     */
-    get personality() {
-        return this.options.personality;
-    }
-    /**
-     * Set agent personality
-     */
-    set personality(value) {
-        this.options.personality = value;
-    }
     /**
      * Get whether debug mode is enabled
      */
@@ -384,29 +482,17 @@ export class Agent {
         this.options.provider = value;
     }
     /**
-     * Get the composition mode
-     */
-    get compositionMode() {
-        return this.options.compositionMode ?? CompositionMode.FLUID;
-    }
-    /**
-     * Set the composition mode
-     */
-    set compositionMode(value) {
-        this.options.compositionMode = value;
-    }
-    /**
-     * Get the route switch margin
+     * Get the flow switch margin
      * @default 15
      */
-    get routeSwitchMargin() {
-        return this.options.routeSwitchMargin ?? 15;
+    get flowSwitchMargin() {
+        return this.options.flowSwitchMargin ?? 15;
     }
     /**
-     * Set the route switch margin
+     * Set the flow switch margin
      */
-    set routeSwitchMargin(value) {
-        this.options.routeSwitchMargin = value;
+    set flowSwitchMargin(value) {
+        this.options.flowSwitchMargin = value;
     }
     /**
      * Get the prompt section cache instance
@@ -414,19 +500,6 @@ export class Agent {
     get promptSectionCache() {
         return this._promptSectionCache;
     }
-    /**
-     * Get the maximum steps per batch
-     * @default 1
-     */
-    get maxStepsPerBatch() {
-        return this.options.maxStepsPerBatch ?? 1;
-    }
-    /**
-     * Set the maximum steps per batch
-     */
-    set maxStepsPerBatch(value) {
-        this.options.maxStepsPerBatch = value;
-    }
     /**
      * Get all terms
      */
@@ -434,10 +507,10 @@ export class Agent {
         return [...this._terms];
     }
     /**
-     * Get all guidelines
+     * Get all instructions
      */
-    get guidelines() {
-        return [...this._guidelines];
+    get instructions() {
+        return [...this._instructions];
     }
     /**
      * Get all tools
@@ -446,34 +519,10 @@ export class Agent {
         return [...this._tools];
     }
     /**
-     * Get all routes
-     */
-    get routes() {
-        return [...this._routes];
-    }
-    /**
-     * Get agent-level rules
-     */
-    get rules() {
-        return [...this._rules];
-    }
-    /**
-     * Set agent-level rules
-     */
-    set rules(value) {
-        this._rules = [...value];
-    }
-    /**
-     * Get agent-level prohibitions
+     * Get all flows
      */
-    get prohibitions() {
-        return [...this._prohibitions];
-    }
-    /**
-     * Set agent-level prohibitions
-     */
-    set prohibitions(value) {
-        this._prohibitions = [...value];
+    get flows() {
+        return [...this._flows];
     }
     /**
      * Get current schema
@@ -490,6 +539,13 @@ export class Agent {
         }
         this._schema = value;
     }
+    /**
+     * Get the configured signals.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    get signals() {
+        return this._signals;
+    }
     /**
      * Get the agent's knowledge base
      */
@@ -516,98 +572,38 @@ export class Agent {
         this._currentSession = value;
         this._promptSectionCache.invalidateAll();
     }
-    // ---------------------------------------------------------------------------
-    // Deprecated method-based accessors (for backward compatibility)
-    // ---------------------------------------------------------------------------
+    /**
+     * Get all flows
+     */
+    getFlows() {
+        return this.flows;
+    }
     /**
      * Get all terms
-     * @deprecated Use `agent.terms` instead
      */
     getTerms() {
         return this.terms;
     }
     /**
      * Get all tools
-     * @deprecated Use `agent.tools` instead
      */
     getTools() {
         return this.tools;
     }
     /**
-     * Get all guidelines
-     * @deprecated Use `agent.guidelines` instead
+     * Get all instructions
      */
-    getGuidelines() {
-        return this.guidelines;
+    getInstructions() {
+        return this.instructions;
     }
     /**
-     * Get all routes
-     * @deprecated Use `agent.routes` instead
+     * Invalidate flow-dependent prompt cache sections.
+     * Called automatically when the active flow changes.
      */
-    getRoutes() {
-        return this.routes;
-    }
-    /**
-     * Get agent-level rules
-     * @deprecated Use `agent.rules` instead
-     */
-    getRules() {
-        return this.rules;
-    }
-    /**
-     * Get agent-level prohibitions
-     * @deprecated Use `agent.prohibitions` instead
-     */
-    getProhibitions() {
-        return this.prohibitions;
-    }
-    /**
-     * Get current schema
-     * @deprecated Use `agent.schema` instead
-     */
-    getSchema() {
-        return this.schema;
-    }
-    /**
-     * Get the agent's knowledge base
-     * @deprecated Use `agent.knowledgeBase` instead
-     */
-    getKnowledgeBase() {
-        return this.knowledgeBase;
-    }
-    /**
-     * Get the current session (if set)
-     * @deprecated Use `agent.currentSession` instead
-     */
-    getCurrentSession() {
-        return this.currentSession;
-    }
-    /**
-     * Set the current session for convenience methods
-     * @deprecated Use `agent.currentSession = session` instead
-     * @param session - Session step to use for subsequent calls
-     */
-    setCurrentSession(session) {
-        this.currentSession = session;
-        this._promptSectionCache.invalidateAll();
-    }
-    /**
-     * Clear the current session
-     * @deprecated Use `agent.currentSession = undefined` instead
-     */
-    clearCurrentSession() {
-        this._currentSession = undefined;
-        this._promptSectionCache.invalidateAll();
-    }
-    /**
-     * Invalidate route-dependent prompt cache sections.
-     * Called automatically when the active route changes.
-     */
-    invalidateRouteSections() {
-        this._promptSectionCache.invalidate('activeRoutes');
-        this._promptSectionCache.invalidate('routeRules');
-        this._promptSectionCache.invalidate('routeProhibitions');
-        this._promptSectionCache.invalidate('routeKnowledgeBase');
+    invalidateFlowSections() {
+        this._promptSectionCache.invalidate('activeFlows');
+        this._promptSectionCache.invalidate('flowKnowledgeBase');
+        this._promptSectionCache.invalidate('instructionsFlow');
     }
     /**
      * Get the persistence manager (if configured)
@@ -631,28 +627,32 @@ export class Agent {
     // Core methods
     // ---------------------------------------------------------------------------
     /**
-     * Create a new route (journey) using agent-level data type
+     * Create a new flow (journey) using agent-level data type
      */
-    createRoute(options) {
+    createFlow(options) {
         // Validate that requiredFields exist in agent schema
         if (options.requiredFields && this._schema?.properties) {
             const invalidRequiredFields = options.requiredFields.filter(field => !(String(field) in this._schema.properties));
             if (invalidRequiredFields.length > 0) {
-                throw new RouteConfigurationError(options.title, invalidRequiredFields.map(f => String(f)), `Invalid required fields in route '${options.title}': ${invalidRequiredFields.join(', ')}. ` +
-                    `Must be valid keys from agent schema. Available fields: ${Object.keys(this._schema.properties).join(', ')}.`);
+                throw new FlowConfigurationError(options.title, invalidRequiredFields.map(f => String(f)), `[FlowConfigurationError] Invalid required fields in flow "${options.title}": [${invalidRequiredFields.join(', ')}] are not declared in the agent schema. ` +
+                    `Use valid schema keys. Available fields: ${Object.keys(this._schema.properties).join(', ')}.`);
             }
         }
         // Validate that optionalFields exist in agent schema
         if (options.optionalFields && this._schema?.properties) {
             const invalidOptionalFields = options.optionalFields.filter(field => !(String(field) in this._schema.properties));
             if (invalidOptionalFields.length > 0) {
-                throw new RouteConfigurationError(options.title, invalidOptionalFields.map(f => String(f)), `Invalid optional fields in route '${options.title}': ${invalidOptionalFields.join(', ')}. ` +
-                    `Must be valid keys from agent schema. Available fields: ${Object.keys(this._schema.properties).join(', ')}.`);
+                throw new FlowConfigurationError(options.title, invalidOptionalFields.map(f => String(f)), `[FlowConfigurationError] Invalid optional fields in flow "${options.title}": [${invalidOptionalFields.join(', ')}] are not declared in the agent schema. ` +
+                    `Use valid schema keys. Available fields: ${Object.keys(this._schema.properties).join(', ')}.`);
             }
         }
-        const route = new Route(options, this);
-        this._routes.push(route);
-        return route;
+        const flow = new Flow(options, this);
+        // Validate that step collect fields reference valid schema keys
+        if (this._schema?.properties) {
+            this.validateFlowCollectFields(flow);
+        }
+        this._flows.push(flow);
+        return flow;
     }
     /**
      * Create a domain term for the glossary
@@ -662,20 +662,22 @@ export class Agent {
         return this;
     }
     /**
-     * Create a behavioral guideline
+     * Create an instruction (unified behavioral primitive).
      */
-    createGuideline(guideline) {
-        const guidelineWithId = {
-            ...guideline,
-            id: guideline.id || `guideline_${this._guidelines.length}`,
-            enabled: guideline.enabled !== false, // Default to true
+    createInstruction(instruction) {
+        const instructionWithId = {
+            ...instruction,
+            kind: instruction.kind || 'should',
+            id: instruction.id || `instruction_${this._instructions.length}`,
+            enabled: instruction.enabled !== false, // Default to true
         };
-        this._guidelines.push(guidelineWithId);
+        this._instructions.push(instructionWithId);
+        this._promptSectionCache.invalidate('instructionsGlobal');
         return this;
     }
     /**
      * Add a tool to the agent using the unified Tool interface
-     * Creates and adds the tool to agent scope in one operation (BREAKING CHANGE: replaces createTool)
+     * Creates and adds the tool to agent scope in one operation
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     addTool(tool) {
@@ -688,20 +690,6 @@ export class Agent {
         logger.debug(`[Agent] Added tool to agent scope: ${tool.id}`);
         return this;
     }
-    /**
-     * Register a tool at the agent level (legacy method for backward compatibility)
-     * @deprecated Use addTool() with Tool interface instead
-     */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    createTool(tool) {
-        // Validate tool before adding
-        if (!tool || !tool.id || !tool.handler) {
-            throw new Error('Invalid tool: must have id and handler properties');
-        }
-        this._tools.push(tool);
-        logger.debug(`[Agent] Created tool (legacy): ${tool.id}`);
-        return this;
-    }
     /**
      * Register multiple tools at the agent level
      */
@@ -719,7 +707,7 @@ export class Agent {
     }
     /**
      * Update the agent's context
-     * Triggers both agent-level and route-specific onContextUpdate lifecycle hooks if configured
+     * Triggers both agent-level and flow-specific onContextUpdate lifecycle hooks if configured
      */
     async updateContext(updates) {
         const previousContext = this._context;
@@ -728,12 +716,12 @@ export class Agent {
             ...this._context,
             ...updates,
         };
-        // Trigger route-specific lifecycle hook if configured and session has current route
-        if (this._currentSession?.currentRoute) {
-            const currentRoute = this._routes.find((r) => r.id === this._currentSession.currentRoute?.id);
-            if (currentRoute?.hooks?.onContextUpdate &&
+        // Trigger flow-specific lifecycle hook if configured and session has current flow
+        if (this._currentSession?.currentFlow) {
+            const currentFlow = this._flows.find((r) => r.id === this._currentSession.currentFlow?.id);
+            if (currentFlow?.hooks?.onContextUpdate &&
                 previousContext !== undefined) {
-                await currentRoute.handleContextUpdate(this._context, previousContext);
+                await currentFlow.handleContextUpdate(this._context, previousContext);
             }
         }
         // Trigger agent-level lifecycle hook if configured
@@ -743,10 +731,11 @@ export class Agent {
         // Invalidate context-dependent prompt cache sections
         this._promptSectionCache.invalidate('agentMeta');
         this._promptSectionCache.invalidate('knowledgeBase');
+        this._promptSectionCache.invalidate('instructionsGlobal');
     }
     /**
      * Update collected data in session with lifecycle hook support
-     * Triggers both agent-level and route-specific onDataUpdate lifecycle hooks if configured
+     * Triggers both agent-level and flow-specific onDataUpdate lifecycle hooks if configured
      * @internal
      */
     async updateData(session, dataUpdate) {
@@ -756,11 +745,11 @@ export class Agent {
             ...session.data,
             ...dataUpdate,
         };
-        // Trigger route-specific lifecycle hook if configured and session has a current route
-        if (session.currentRoute) {
-            const currentRoute = this._routes.find((r) => r.id === session.currentRoute?.id);
-            if (currentRoute?.hooks?.onDataUpdate) {
-                newCollected = await currentRoute.handleDataUpdate(newCollected, previousCollected);
+        // Trigger flow-specific lifecycle hook if configured and session has a current flow
+        if (session.currentFlow) {
+            const currentFlow = this._flows.find((r) => r.id === session.currentFlow?.id);
+            if (currentFlow?.hooks?.onDataUpdate) {
+                newCollected = await currentFlow.handleDataUpdate(newCollected, previousCollected);
             }
         }
         // Trigger agent-level lifecycle hook if configured
@@ -805,10 +794,10 @@ export class Agent {
         return this.options;
     }
     /**
-     * Get routing engine
+     * Get flow router
      * @internal Used by ResponseModal
      */
-    getRoutingEngine() {
+    getFlowRouter() {
         return this._routingEngine;
     }
     /**
@@ -818,51 +807,11 @@ export class Agent {
     getUpdateDataMethod() {
         return this.updateData.bind(this);
     }
-    /**
-     * Evaluate and match active guidelines based on their conditions
-     * Returns guidelines that should be active given the current context
-     */
-    async evaluateGuidelines(context, session, history) {
-        const templateContext = { context, session, history, data: session?.data };
-        const evaluator = createConditionEvaluator(templateContext);
-        const matches = [];
-        for (const guideline of this._guidelines) {
-            // Skip disabled guidelines
-            if (guideline.enabled === false) {
-                continue;
-            }
-            if (guideline.condition) {
-                const evaluation = await evaluator.evaluateCondition(guideline.condition, 'AND');
-                // Include guideline if:
-                // 1. No programmatic conditions (only strings) - always active
-                // 2. Programmatic conditions evaluate to true
-                if (!evaluation.hasProgrammaticConditions || evaluation.programmaticResult) {
-                    const rationale = evaluation.aiContextStrings.length > 0
-                        ? `Condition met: ${evaluation.aiContextStrings.join(" AND ")}`
-                        : evaluation.hasProgrammaticConditions
-                            ? "Programmatic condition evaluated to true"
-                            : "Always active (no conditions)";
-                    matches.push({
-                        guideline,
-                        rationale
-                    });
-                }
-            }
-            else {
-                // No condition means always active
-                matches.push({
-                    guideline,
-                    rationale: "Always active (no conditions)"
-                });
-            }
-        }
-        return matches;
-    }
     /**
      * Execute a prepare or finalize function/tool
      * @internal Used by ResponseModal
      */
-    async executePrepareFinalize(prepareOrFinalize, context, data, route, step) {
+    async executePrepareFinalize(prepareOrFinalize, context, data, flow, step) {
         if (!prepareOrFinalize)
             return;
         if (typeof prepareOrFinalize === "function") {
@@ -874,7 +823,7 @@ export class Agent {
             let tool;
             if (typeof prepareOrFinalize === "string") {
                 // Tool ID - use ToolManager to find it across all scopes
-                tool = this.tool.find(prepareOrFinalize, undefined, step, route);
+                tool = this.tool.find(prepareOrFinalize, undefined, step, flow);
             }
             else {
                 // Tool object - validate it has required properties
@@ -921,7 +870,6 @@ export class Agent {
     }
     /**
      * Get collected data from current session or agent-level collected data
-     * @param routeId - Optional route ID to get data for (uses current route if not provided)
      * @returns The collected data from the current session or agent-level data
      */
     getData() {
@@ -929,64 +877,263 @@ export class Agent {
         this.syncSessionDataToCollectedData();
         // If we have a current session, use session data
         if (this._currentSession) {
-            // With agent-level data, all routes share the same data structure
-            // No need for route-specific data access
+            // With agent-level data, all flows share the same data structure
+            // No need for flow-specific data access
             return (this._currentSession.data) || {};
         }
         // Otherwise, return agent-level collected data
         return this.getCollectedData();
     }
     /**
-     * Manually transition to a different route
-     * Sets a pending transition that will be executed on the next respond() call
+     * Dispatch a directive (or a flow shorthand) into a session.
+     * Sets `pendingDirective` on the session without triggering a `respond()` call.
+     * The directive will be applied at the start of the next turn.
+     *
+     * String form desugars to `{ goTo: target }`.
      *
-     * @param routeIdOrTitle - Route ID or title to transition to
-     * @param session - Session step to update (uses current session if not provided)
-     * @param condition - Optional AI-evaluated condition for the transition
-     * @returns Updated session with pending transition
+     * @param target - Flow ID/title string (desugars to `{ goTo: target }`) or a full Directive
+     * @param session - Session to update (uses current session if not provided)
+     * @returns Updated session with `pendingDirective` set
+     *
+     * @throws FlowConfigurationError if the string target doesn't match any flow
+     * @throws FlowConfigurationError if the directive fails validation
+     *
+     * @example
+     * // String shorthand — desugars to { goTo: 'Feedback' }
+     * const updated = await agent.dispatch('Feedback', session);
      *
      * @example
-     * // After route completes
-     * if (response.isRouteComplete && response.session) {
-     *   const updatedSession = agent.nextStepRoute("feedback-collection", response.session);
-     *   // Next respond() call will automatically transition to feedback route
-     *   const nextResponse = await agent.respond({ history, session: updatedSession });
-     * }
-     */
-    async nextStepRoute(routeIdOrTitle, session, condition, history) {
+     * // Full directive
+     * const updated = await agent.dispatch({ goTo: 'Billing', reply: 'Transferring you now.' }, session);
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async dispatch(target, session) {
         const targetSession = session || this._currentSession;
         if (!targetSession) {
-            throw new Error("No session provided and no current session available. Please provide a session to transition.");
-        }
-        // Find target route by ID or title
-        const targetRoute = this._routes.find((r) => r.id === routeIdOrTitle || r.title === routeIdOrTitle);
-        if (!targetRoute) {
-            throw new Error(`Route not found: ${routeIdOrTitle}. Available routes: ${this._routes
-                .map((r) => r.title)
-                .join(", ")}`);
-        }
-        const templateContext = createTemplateContext({
-            context: this._context,
-            session,
-            history,
-            data: this._currentSession?.data,
-        });
-        const renderedCondition = await render(condition, templateContext);
+            throw new Error("No session provided and no current session available. Please provide a session to dispatch into.");
+        }
+        // Desugar string form to { goTo: target }
+        const directive = typeof target === 'string'
+            ? { goTo: target }
+            : target;
+        // Validate the directive: check for multiple position fields, empty goTo, etc.
+        this.validateDirective(directive);
+        // If goTo is a string, validate it references a known flow
+        if (typeof directive.goTo === 'string') {
+            const flowTarget = directive.goTo;
+            const matchesFlow = this._flows.some(f => f.id === flowTarget || f.title === flowTarget);
+            if (!matchesFlow) {
+                throw new StepFlowConfigurationError(`[FlowConfigurationError] Unknown flow: "${flowTarget}" does not match any flow id or title. ` +
+                    `Available flows: ${this._flows.map(f => f.title).join(', ')}.`);
+            }
+        }
+        else if (directive.goTo && typeof directive.goTo === 'object' && directive.goTo.flow) {
+            const flowTarget = directive.goTo.flow;
+            const matchesFlow = this._flows.some(f => f.id === flowTarget || f.title === flowTarget);
+            if (!matchesFlow) {
+                throw new StepFlowConfigurationError(`[FlowConfigurationError] Unknown flow: "${flowTarget}" does not match any flow id or title. ` +
+                    `Available flows: ${this._flows.map(f => f.title).join(', ')}.`);
+            }
+        }
+        // Strip PreDirective-only fields before storing
+        const stripped = this.stripPreDirectiveFields(directive);
+        // Set pendingDirective on the session without applying it
         const updatedSession = {
             ...targetSession,
-            pendingTransition: {
-                targetRouteId: targetRoute.id,
-                condition: renderedCondition,
-                reason: "route_complete",
+            pendingDirective: stripped,
+            metadata: {
+                ...targetSession.metadata,
+                lastUpdatedAt: new Date(),
             },
         };
-        // Update current session if using it
+        // Update current session in place if no explicit session was passed
         if (!session && this._currentSession) {
             this._currentSession = updatedSession;
         }
-        logger.debug(`[Agent] Set pending transition to route: ${targetRoute.title}`);
+        logger.debug(`[Agent] Dispatched directive: pendingDirective set on session ${updatedSession.id}`);
+        return updatedSession;
+    }
+    /**
+     * Apply a directive synchronously to a session without invoking `respond()`.
+     * Performs in-place application: updates flow/step position, merges state writes.
+     *
+     * This is the synchronous counterpart to `dispatch` — it applies immediately
+     * rather than deferring to the next turn.
+     *
+     * @param directive - The directive to apply
+     * @param session - The session to apply the directive to
+     * @returns The updated session with the directive applied
+     */
+    applyDirective(directive, session) {
+        // Validate the directive
+        this.validateDirective(directive);
+        let updatedSession = { ...session };
+        const now = new Date();
+        // Apply state writes
+        if (directive.contextUpdate) {
+            // Context updates are applied to the agent, not the session
+            this._context = {
+                ...this._context,
+                ...directive.contextUpdate,
+            };
+        }
+        if (directive.dataUpdate) {
+            updatedSession = {
+                ...updatedSession,
+                data: {
+                    ...updatedSession.data,
+                    ...directive.dataUpdate,
+                },
+            };
+        }
+        // Apply position control
+        if (directive.goTo) {
+            const flowTarget = typeof directive.goTo === 'string'
+                ? directive.goTo
+                : directive.goTo.flow;
+            if (flowTarget) {
+                const targetFlow = this._flows.find(f => f.id === flowTarget || f.title === flowTarget);
+                if (targetFlow) {
+                    // Merge goTo.data if present
+                    if (typeof directive.goTo === 'object' && directive.goTo.data) {
+                        updatedSession = {
+                            ...updatedSession,
+                            data: {
+                                ...updatedSession.data,
+                                ...directive.goTo.data,
+                            },
+                        };
+                    }
+                    updatedSession = enterFlow(updatedSession, targetFlow.id, targetFlow.title);
+                    // If a specific step is targeted
+                    if (typeof directive.goTo === 'object' && directive.goTo.step) {
+                        updatedSession = enterStep(updatedSession, directive.goTo.step);
+                    }
+                }
+            }
+        }
+        else if (directive.goToStep) {
+            const stepTarget = typeof directive.goToStep === 'string'
+                ? directive.goToStep
+                : directive.goToStep.step;
+            // Merge goToStep.data if present
+            if (typeof directive.goToStep === 'object' && directive.goToStep.data) {
+                updatedSession = {
+                    ...updatedSession,
+                    data: {
+                        ...updatedSession.data,
+                        ...directive.goToStep.data,
+                    },
+                };
+            }
+            updatedSession = enterStep(updatedSession, stepTarget);
+        }
+        else if (directive.complete) {
+            updatedSession = completeCurrentFlow(updatedSession);
+            // If complete carries a chained directive, set it as pendingDirective
+            if (typeof directive.complete === 'object' && directive.complete.next) {
+                updatedSession = {
+                    ...updatedSession,
+                    pendingDirective: directive.complete.next,
+                };
+            }
+        }
+        else if (directive.abort) {
+            const clearSession = typeof directive.abort === 'object'
+                ? directive.abort.clearSession !== false
+                : true;
+            if (clearSession) {
+                updatedSession = {
+                    ...updatedSession,
+                    currentFlow: undefined,
+                    currentStep: undefined,
+                    data: {},
+                };
+            }
+            else {
+                updatedSession = {
+                    ...updatedSession,
+                    currentFlow: undefined,
+                    currentStep: undefined,
+                };
+            }
+        }
+        else if (directive.reset) {
+            const currentFlowId = updatedSession.currentFlow?.id;
+            const currentFlowTitle = updatedSession.currentFlow?.title;
+            if (currentFlowId && currentFlowTitle) {
+                // Clear data if requested
+                if (typeof directive.reset === 'object' && directive.reset.clearData) {
+                    const currentFlow = this._flows.find(f => f.id === currentFlowId);
+                    if (currentFlow) {
+                        const ownedFields = [
+                            ...(currentFlow.requiredFields || []),
+                            ...(currentFlow.optionalFields || []),
+                        ];
+                        updatedSession = completeCurrentFlow(updatedSession, { clearOwnedFields: ownedFields });
+                        // Re-enter the same flow
+                        updatedSession = enterFlow(updatedSession, currentFlowId, currentFlowTitle);
+                    }
+                }
+                else {
+                    // Re-enter the flow from the beginning (or specified step)
+                    updatedSession = enterFlow(updatedSession, currentFlowId, currentFlowTitle);
+                }
+                // If a specific step is targeted for reset
+                if (typeof directive.reset === 'object' && directive.reset.step) {
+                    updatedSession = enterStep(updatedSession, directive.reset.step);
+                }
+            }
+        }
+        // Update metadata
+        updatedSession = {
+            ...updatedSession,
+            metadata: {
+                ...updatedSession.metadata,
+                lastUpdatedAt: now,
+            },
+        };
         return updatedSession;
     }
+    /**
+     * Validate a directive for structural correctness.
+     * Throws FlowConfigurationError for invalid combinations.
+     * @private
+     */
+    validateDirective(directive) {
+        // Check for multiple position fields
+        const positionFields = ['goTo', 'goToStep', 'complete', 'abort', 'reset'];
+        const setPositionFields = positionFields.filter(field => directive[field] !== undefined);
+        if (setPositionFields.length > 1) {
+            throw new StepFlowConfigurationError(`[FlowConfigurationError] Multiple position fields: a Directive may set at most one position field. ` +
+                `Found: ${setPositionFields.join(', ')}. Remove all but one.`);
+        }
+        // Check for empty goTo object
+        if (directive.goTo && typeof directive.goTo === 'object') {
+            const goToObj = directive.goTo;
+            if (!goToObj.flow && !goToObj.step) {
+                throw new StepFlowConfigurationError(`[FlowConfigurationError] Empty goTo: "goTo" requires at least a "flow" field. ` +
+                    `Provide { goTo: { flow: '<id>' } } or use the string shorthand { goTo: '<id>' }.`);
+            }
+        }
+    }
+    /**
+     * Strip PreDirective-only fields (appendPrompt, injectTools, halt) from a directive.
+     * These fields are transient (one-turn lifetime) and must not be persisted.
+     * @private
+     */
+    stripPreDirectiveFields(directive) {
+        const raw = directive;
+        if (!raw.appendPrompt && !raw.injectTools && raw.halt === undefined) {
+            return directive;
+        }
+        const { appendPrompt, injectTools, halt, ...rest } = raw;
+        if (appendPrompt || injectTools || halt !== undefined) {
+            logger.debug(`[Agent] Stripped PreDirective-only fields before storing pendingDirective: ` +
+                `${[appendPrompt && 'appendPrompt', injectTools && 'injectTools', halt !== undefined && 'halt'].filter(Boolean).join(', ')}`);
+        }
+        return rest;
+    }
     /**
      * Simplified respond method using SessionManager
      * Automatically manages conversation history through the session