@falai/agent 3.4.3 → 3.4.4

package/dist/cjs/core/Agent.js

@@ -0,0 +1,1198 @@
+"use strict";
+/**
+ * Core Agent implementation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const errors_js_1 = require("../types/errors.js");
+const SignalProcessor_js_1 = require("./SignalProcessor.js");
+const SignalEvaluator_js_1 = require("./SignalEvaluator.js");
+const index_js_1 = require("../utils/index.js");
+const Flow_js_1 = require("./Flow.js");
+const Step_js_1 = require("./Step.js");
+const PersistenceManager_js_1 = require("./PersistenceManager.js");
+const SessionManager_js_1 = require("./SessionManager.js");
+const FlowRouter_js_1 = require("./FlowRouter.js");
+const PromptSectionCache_js_1 = require("./PromptSectionCache.js");
+const ResponseModal_js_1 = require("./ResponseModal.js");
+const ToolManager_js_1 = require("./ToolManager.js");
+const CompactionEngine_js_1 = require("./CompactionEngine.js");
+/**
+ * Error thrown when data validation fails
+ */
+class DataValidationError extends Error {
+    constructor(errors, message) {
+        super(message || "Data validation failed");
+        this.errors = errors;
+        this.name = "DataValidationError";
+    }
+}
+/**
+ * Error thrown when flow configuration is invalid
+ */
+class FlowConfigurationError extends Error {
+    constructor(flowTitle, invalidFields, message) {
+        super(message || `Flow configuration error in '${flowTitle}'`);
+        this.flowTitle = flowTitle;
+        this.invalidFields = invalidFields;
+        this.name = "FlowConfigurationError";
+    }
+}
+/**
+ * Main Agent class with generic context and data support
+ */
+class Agent {
+    constructor(options) {
+        this.options = options;
+        this._terms = [];
+        this._instructions = [];
+        this._tools = [];
+        this._flows = [];
+        this._knowledgeBase = {};
+        /**
+         * Staging buffer for data set before any session exists (initialData and
+         * pre-session updateCollectedData calls). Consumed when a session is
+         * created; once a session exists, `session.data` is the single source of
+         * truth and this buffer stays empty.
+         */
+        this._pendingData = {};
+        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 errors_js_1.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: (0, index_js_1.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 Step_js_1.FlowConfigurationError(`[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 Step_js_1.FlowConfigurationError(`[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) {
+                index_js_1.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 Step_js_1.FlowConfigurationError(`[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_js_1.SignalEvaluator(options.provider);
+            this.signalProcessor = new SignalProcessor_js_1.SignalProcessor(rawSignals, options.provider, evaluator, { batchSize: options.signalBatchSize ?? 10 });
+        }
+        else {
+            this.signalProcessor = undefined;
+        }
+        // Set log level based on debug option. NOTE: loglevel's default logger is
+        // process-global — one agent enabling debug turns on DEBUG for every agent
+        // in the process. Warned so multi-tenant embedders aren't surprised.
+        if (options.debug) {
+            index_js_1.logger.warn(`[Agent] "${options.name}" enabled debug logging via the PROCESS-GLOBAL loglevel level. ` +
+                `Every agent in this process now logs at DEBUG. Scope logging in your host if needed.`);
+            index_js_1.logger.setLevel(index_js_1.LoggerLevel.DEBUG);
+        }
+        // Validate context configuration
+        if (options.context !== undefined && options.contextProvider) {
+            throw new Error("Cannot provide both 'context' and 'contextProvider'. Choose one.");
+        }
+        // Initialize and validate agent-level schema if provided
+        if (options.schema) {
+            this._schema = options.schema;
+            this.validateSchema(this._schema);
+            index_js_1.logger.debug("[Agent] Agent-level schema initialized and validated");
+        }
+        // Initialize context if provided
+        this._context = options.context;
+        // Initialize collected data with initial data if provided
+        if (options.initialData) {
+            if (this._schema) {
+                const validation = this.validateData(options.initialData);
+                if (!validation.valid) {
+                    throw new Error(`Initial data validation failed: ${validation.errors.map(e => e.message).join(', ')}`);
+                }
+            }
+            this._pendingData = { ...options.initialData };
+            index_js_1.logger.debug("[Agent] Initial data set:", this._pendingData);
+        }
+        // Initialize prompt section cache
+        this._promptSectionCache = new PromptSectionCache_js_1.PromptSectionCache(options.promptCache);
+        // Initialize flow router
+        this._routingEngine = new FlowRouter_js_1.FlowRouter({
+            flowSwitchMargin: options.flowSwitchMargin,
+            onFlowSwitch: () => this.invalidateFlowSections(),
+            promptSectionCache: this._promptSectionCache,
+        });
+        // Initialize tool manager BEFORE ResponseModal (it reads agent.tool in constructor)
+        this.tool = new ToolManager_js_1.ToolManager(this);
+        // Initialize ResponseModal for handling all response generation
+        this._responseModal = new ResponseModal_js_1.ResponseModal(this, {
+            maxToolLoops: options.maxToolLoops,
+        });
+        // Initialize persistence if configured
+        if (options.persistence) {
+            try {
+                // Validate persistence configuration
+                if (!options.persistence.adapter) {
+                    throw new Error("Persistence adapter is required when persistence is configured");
+                }
+                if (!options.persistence.adapter.sessionRepository) {
+                    throw new Error("Persistence adapter must provide a sessionRepository");
+                }
+                if (!options.persistence.adapter.messageRepository) {
+                    throw new Error("Persistence adapter must provide a messageRepository");
+                }
+                this._persistenceManager = new PersistenceManager_js_1.PersistenceManager(options.persistence);
+                // Initialize the adapter if it has an initialize method
+                if (options.persistence.adapter.initialize) {
+                    options.persistence.adapter.initialize().catch((error) => {
+                        index_js_1.logger.error("[Agent] Persistence adapter initialization failed:", error instanceof Error ? error.message : String(error));
+                    });
+                }
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                index_js_1.logger.error("[Agent] Failed to initialize persistence:", errorMessage);
+                throw new Error(`Failed to initialize persistence: ${errorMessage}`);
+            }
+        }
+        // Initialize from options - use create methods for consistency
+        if (options.terms) {
+            options.terms.forEach((term) => {
+                this.createTerm(term);
+            });
+        }
+        // Initialize instructions (new unified form)
+        if (options.instructions) {
+            options.instructions.forEach((instruction) => {
+                this.createInstruction(instruction);
+            });
+        }
+        if (options.tools) {
+            options.tools.forEach((tool) => {
+                this.addTool(tool);
+            });
+        }
+        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 };
+        }
+        // Initialize compaction options if configured
+        if (options.compaction && options.compaction.enabled !== false) {
+            const compactionOptions = {
+                maxTokens: options.compaction.maxTokens,
+                compactionThreshold: options.compaction.compactionThreshold ?? 0.8,
+                preserveRecentCount: options.compaction.preserveRecentCount ?? 4,
+                maxToolResultChars: options.compaction.maxToolResultChars ?? 5000,
+                provider: options.provider,
+            };
+            CompactionEngine_js_1.CompactionEngine.validateOptions(compactionOptions);
+            this._compactionOptions = compactionOptions;
+            index_js_1.logger.debug("[Agent] Compaction options initialized and validated");
+        }
+        // Initialize session manager — the single owner of the live session
+        this.session = new SessionManager_js_1.SessionManager(this._persistenceManager, this);
+        // Adopt an explicitly provided session
+        if (options.session) {
+            this.session.syncSession(options.session);
+        }
+        // Store sessionId for later use in getOrCreate calls
+        if (options.sessionId) {
+            this.session.setDefaultSessionId(options.sessionId);
+            // The session will be loaded on first getOrCreate call; session.data
+            // is the source of truth, so no data sync is needed here
+            this.session.getOrCreate(options.sessionId).catch((err) => {
+                index_js_1.logger.error("Failed to start session", err);
+            });
+        }
+    }
+    /**
+     * Drain the pre-session data staging buffer.
+     * @internal Called by SessionManager when a session is created or loaded.
+     */
+    consumePendingData() {
+        const pending = this._pendingData;
+        this._pendingData = {};
+        return pending;
+    }
+    /**
+     * Validate the agent-level schema structure
+     * @private
+     */
+    validateSchema(schema) {
+        if (!schema || typeof schema !== 'object') {
+            throw new Error("Agent schema must be a valid JSON Schema object. " +
+                "Provide a schema with 'type': 'object' and 'properties' to define the data structure.");
+        }
+        if (schema.type !== 'object') {
+            throw new Error(`Agent schema must be of type 'object', but received '${String(schema.type)}'. ` +
+                "Agent-level schemas must define object structures for data collection.");
+        }
+        if (!schema.properties || typeof schema.properties !== 'object') {
+            throw new Error("Agent schema must have a 'properties' field defining the data fields. " +
+                "Example: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string' } } }");
+        }
+        index_js_1.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 Step_js_1.FlowConfigurationError(`[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 Step_js_1.FlowConfigurationError(`[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.
+     *
+     * A field the schema does not declare is a warning, not an error: a model
+     * can extract a key nobody asked for, and `updateCollectedData` drops it
+     * instead of failing the turn. `valid` is false only when `errors` is not empty.
+     */
+    validateData(data) {
+        if (!this._schema) {
+            // No schema defined, consider all data valid
+            return { valid: true, errors: [], warnings: [] };
+        }
+        const errors = [];
+        const warnings = [];
+        // Undeclared fields are warnings — updateCollectedData drops them
+        if (this._schema.properties) {
+            for (const [key, value] of Object.entries(data)) {
+                if (!(key in this._schema.properties)) {
+                    warnings.push({
+                        field: key,
+                        value,
+                        message: `Field '${key}' is not defined in agent schema`,
+                        schemaPath: `properties.${key}`
+                    });
+                }
+            }
+        }
+        // Check required fields if specified
+        if (this._schema.required && Array.isArray(this._schema.required)) {
+            for (const requiredField of this._schema.required) {
+                if (!(requiredField in data) || data[requiredField] === undefined) {
+                    warnings.push({
+                        field: requiredField,
+                        value: undefined,
+                        message: `Required field '${requiredField}' is missing`,
+                        schemaPath: `required`
+                    });
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * Check if a field is valid according to the agent schema
+     * @param field - The field key to validate
+     * @returns true if field exists in schema or no schema is defined, false otherwise
+     */
+    isValidSchemaField(field) {
+        if (!this._schema || !this._schema.properties) {
+            // No schema defined, consider all fields valid
+            return true;
+        }
+        return field in this._schema.properties;
+    }
+    /**
+     * Get the current collected data.
+     * Reads from the live session when one exists; otherwise from the
+     * pre-session staging buffer.
+     */
+    getCollectedData() {
+        const session = this.session.current;
+        return session ? { ...session.data } : { ...this._pendingData };
+    }
+    /**
+     * Update collected data with validation.
+     * Writes to the live session when one exists; otherwise stages the data
+     * for the session that will be created. Fields the agent schema does not
+     * declare are dropped with a warning, never stored.
+     */
+    async updateCollectedData(updates) {
+        const declaredUpdates = (0, index_js_1.dropUndeclaredFields)(updates, this._schema);
+        // Validate the updates
+        const validation = this.validateData(declaredUpdates);
+        if (!validation.valid) {
+            const errorMessages = validation.errors.map(e => e.message).join(', ');
+            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) {
+            const warningMessages = validation.warnings.map(w => w.message).join(', ');
+            index_js_1.logger.warn(`[Agent] Data validation warnings: ${warningMessages}`);
+        }
+        const session = this.session.current;
+        const previousData = session ? { ...session.data } : { ...this._pendingData };
+        let newData = {
+            ...previousData,
+            ...declaredUpdates
+        };
+        // Trigger agent-level lifecycle hook if configured
+        if (this.options.hooks?.onDataUpdate) {
+            newData = await this.options.hooks.onDataUpdate(newData, previousData);
+        }
+        if (session) {
+            session.data = newData;
+            session.metadata.lastUpdatedAt = new Date();
+        }
+        else {
+            this._pendingData = newData;
+        }
+        index_js_1.logger.debug("[Agent] Collected data updated:", declaredUpdates);
+    }
+    // ---------------------------------------------------------------------------
+    // Property accessors (get / set)
+    // ---------------------------------------------------------------------------
+    /**
+     * Get agent name
+     */
+    get name() {
+        return this.options.name;
+    }
+    /**
+     * Set agent name
+     */
+    set name(value) {
+        this.options.name = value;
+    }
+    /**
+     * Get agent persona
+     */
+    get persona() {
+        return this.options.persona;
+    }
+    /**
+     * Set agent persona
+     */
+    set persona(value) {
+        this.options.persona = value;
+    }
+    /**
+     * Get agent goal
+     */
+    get goal() {
+        return this.options.goal;
+    }
+    /**
+     * Set agent goal
+     */
+    set goal(value) {
+        this.options.goal = value;
+    }
+    /**
+     * Get whether debug mode is enabled
+     */
+    get debug() {
+        return this.options.debug ?? false;
+    }
+    /**
+     * Set debug mode (also updates logger level)
+     */
+    set debug(value) {
+        this.options.debug = value;
+        index_js_1.logger.setLevel(value ? index_js_1.LoggerLevel.DEBUG : index_js_1.LoggerLevel.INFO);
+    }
+    /**
+     * Get the AI provider
+     */
+    get provider() {
+        return this.options.provider;
+    }
+    /**
+     * Set the AI provider
+     */
+    set provider(value) {
+        this.options.provider = value;
+    }
+    /**
+     * Get the flow switch margin
+     * @default 15
+     */
+    get flowSwitchMargin() {
+        return this.options.flowSwitchMargin ?? 15;
+    }
+    /**
+     * Set the flow switch margin
+     */
+    set flowSwitchMargin(value) {
+        this.options.flowSwitchMargin = value;
+    }
+    /**
+     * Get the prompt section cache instance
+     */
+    get promptSectionCache() {
+        return this._promptSectionCache;
+    }
+    /**
+     * Get all terms
+     */
+    get terms() {
+        return [...this._terms];
+    }
+    /**
+     * Get all instructions
+     */
+    get instructions() {
+        return [...this._instructions];
+    }
+    /**
+     * Get all tools
+     */
+    get tools() {
+        return [...this._tools];
+    }
+    /**
+     * Get all flows
+     */
+    get flows() {
+        return [...this._flows];
+    }
+    /**
+     * Get current schema
+     */
+    get schema() {
+        return this._schema;
+    }
+    /**
+     * Set schema (validates structure)
+     */
+    set schema(value) {
+        if (value) {
+            this.validateSchema(value);
+        }
+        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
+     */
+    get knowledgeBase() {
+        return { ...this._knowledgeBase };
+    }
+    /**
+     * Set the agent's knowledge base
+     */
+    set knowledgeBase(value) {
+        this._knowledgeBase = { ...value };
+    }
+    /**
+     * Get the current session (if set). Delegates to the SessionManager —
+     * the single owner of the live session.
+     */
+    get currentSession() {
+        return this.session.current;
+    }
+    /**
+     * Set the current session for convenience methods
+     * Set to undefined to clear the current session
+     */
+    set currentSession(value) {
+        this.session.syncSession(value);
+        this._promptSectionCache.invalidateAll();
+    }
+    /**
+     * Get all flows
+     */
+    getFlows() {
+        return this.flows;
+    }
+    /**
+     * Get all terms
+     */
+    getTerms() {
+        return this.terms;
+    }
+    /**
+     * Get all tools
+     */
+    getTools() {
+        return this.tools;
+    }
+    /**
+     * Get all instructions
+     */
+    getInstructions() {
+        return this.instructions;
+    }
+    /**
+     * Invalidate flow-dependent prompt cache sections.
+     * Called automatically when the active flow changes.
+     */
+    invalidateFlowSections() {
+        this._promptSectionCache.invalidate('activeFlows');
+        this._promptSectionCache.invalidate('flowKnowledgeBase');
+        this._promptSectionCache.invalidate('instructionsFlow');
+    }
+    /**
+     * Get the persistence manager (if configured)
+     */
+    getPersistenceManager() {
+        return this._persistenceManager;
+    }
+    /**
+     * Check if persistence is enabled
+     */
+    hasPersistence() {
+        return this._persistenceManager !== undefined;
+    }
+    /**
+     * Get the resolved compaction options (if compaction is configured)
+     */
+    getCompactionOptions() {
+        return this._compactionOptions;
+    }
+    // ---------------------------------------------------------------------------
+    // Core methods
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a new flow (journey) using agent-level data type
+     */
+    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 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 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(', ')}.`);
+            }
+        }
+        // Overlap detection: warn (don't throw) when the incoming flow's
+        // requiredFields intersect another registered flow's — the schema is
+        // agent-level, so both flows complete together and one is silently
+        // excluded from routing.
+        if (options.requiredFields && options.requiredFields.length > 0) {
+            const incoming = new Set(options.requiredFields.map(String));
+            for (const existing of this._flows) {
+                const shared = (existing.requiredFields ?? [])
+                    .map(String)
+                    .filter((f) => incoming.has(f));
+                if (shared.length > 0) {
+                    index_js_1.logger.warn(`[FlowConfigurationError] Overlapping requiredFields: flows "${existing.title}" and "${options.title}" share [${shared.join(', ')}]. ` +
+                        `The schema is agent-level, so data collected for one flow marks the other complete and excludes it from routing. ` +
+                        `Give each flow distinct requiredFields, or set \`reentrant: true\` on flows that legitimately share fields.`);
+                }
+            }
+        }
+        const flow = new Flow_js_1.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
+     */
+    createTerm(term) {
+        this._terms.push(term);
+        return this;
+    }
+    /**
+     * Create an instruction (unified behavioral primitive).
+     */
+    createInstruction(instruction) {
+        const instructionWithId = {
+            ...instruction,
+            kind: instruction.kind || 'should',
+            id: instruction.id || `instruction_${this._instructions.length}`,
+            enabled: instruction.enabled !== false, // Default to true
+        };
+        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
+     */
+    addTool(tool) {
+        // Validate tool before adding
+        if (!tool || !tool.id || !tool.handler) {
+            throw new Error('Invalid tool: must have id and handler properties');
+        }
+        // Add directly to agent's tools array, preserving the TResult type
+        this._tools.push(tool);
+        index_js_1.logger.debug(`[Agent] Added tool to agent scope: ${tool.id}`);
+        return this;
+    }
+    /**
+     * Register multiple tools at the agent level
+     */
+    registerTools(tools) {
+        tools.forEach((tool) => {
+            // Validate each tool before adding
+            if (!tool || !tool.id || !tool.handler) {
+                throw new Error(`Invalid tool in batch: must have id and handler properties (tool: ${tool?.id || 'unknown'})`);
+            }
+            this._tools.push(tool);
+        });
+        index_js_1.logger.debug(`[Agent] Registered ${tools.length} tools`);
+        return this;
+    }
+    /**
+     * Update the agent's context
+     * Triggers both agent-level and flow-specific onContextUpdate lifecycle hooks if configured
+     */
+    async updateContext(updates) {
+        const previousContext = this._context;
+        // Merge updates with current context
+        this._context = {
+            ...this._context,
+            ...updates,
+        };
+        // Trigger flow-specific lifecycle hook if configured and session has current flow
+        const activeSession = this.session.current;
+        if (activeSession?.currentFlow) {
+            const currentFlow = this._flows.find((r) => r.id === activeSession.currentFlow?.id);
+            if (currentFlow?.hooks?.onContextUpdate &&
+                previousContext !== undefined) {
+                await currentFlow.handleContextUpdate(this._context, previousContext);
+            }
+        }
+        // Trigger agent-level lifecycle hook if configured
+        if (this.options.hooks?.onContextUpdate && previousContext !== undefined) {
+            await this.options.hooks.onContextUpdate(this._context, previousContext);
+        }
+        // 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 flow-specific onDataUpdate lifecycle hooks if configured
+     * @internal
+     */
+    async updateData(session, dataUpdate) {
+        const previousCollected = { ...session.data };
+        // Merge new collected data
+        let newCollected = {
+            ...session.data,
+            ...dataUpdate,
+        };
+        // 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
+        if (this.options.hooks?.onDataUpdate) {
+            newCollected = (await this.options.hooks.onDataUpdate(newCollected, previousCollected));
+        }
+        // Return updated session — session.data is the single source of truth,
+        // so no agent-side copy is kept
+        return (0, index_js_1.mergeCollected)(session, newCollected);
+    }
+    /**
+     * Get current context (fetches from provider if configured)
+     */
+    async getContext() {
+        // If context provider is configured, use it to fetch fresh context
+        if (this.options.contextProvider) {
+            return await this.options.contextProvider();
+        }
+        // Otherwise return the stored context
+        return this._context;
+    }
+    /**
+     * Generate a response based on history and context as a stream
+     */
+    async *respondStream(params) {
+        // Delegate to ResponseModal
+        yield* this._responseModal.respondStream(params);
+    }
+    /**
+     * Generate a response based on history and context
+     */
+    async respond(params) {
+        // Delegate to ResponseModal
+        return this._responseModal.respond(params);
+    }
+    /**
+     * Get agent options
+     * @internal Used by ResponseModal
+     */
+    getAgentOptions() {
+        return this.options;
+    }
+    /**
+     * Get flow router
+     * @internal Used by ResponseModal
+     */
+    getFlowRouter() {
+        return this._routingEngine;
+    }
+    /**
+     * Get the updateData method bound to this agent
+     * @internal Used by ResponseModal
+     */
+    getUpdateDataMethod() {
+        return this.updateData.bind(this);
+    }
+    /**
+     * Execute a prepare or finalize function/tool
+     * @internal Used by ResponseModal
+     */
+    async executePrepareFinalize(prepareOrFinalize, context, data, flow, step) {
+        if (!prepareOrFinalize)
+            return;
+        if (typeof prepareOrFinalize === "function") {
+            // It's a function - call it directly
+            await prepareOrFinalize(context, data);
+        }
+        else {
+            // It's a tool reference - find and execute the tool
+            let tool;
+            if (typeof prepareOrFinalize === "string") {
+                // Tool ID - use ToolManager to find it across all scopes
+                tool = this.tool.find(prepareOrFinalize, undefined, step, flow);
+            }
+            else {
+                // Tool object - validate it has required properties
+                if (prepareOrFinalize.id && typeof prepareOrFinalize.handler === 'function') {
+                    tool = prepareOrFinalize;
+                }
+                else {
+                    index_js_1.logger.error(`[Agent] Invalid tool object for prepare/finalize: missing id or invalid handler`);
+                    return;
+                }
+            }
+            if (tool) {
+                // Use ToolManager for execution
+                const result = await this.tool.executeTool({
+                    tool,
+                    context,
+                    updateContext: this.updateContext.bind(this),
+                    updateData: this.updateCollectedData.bind(this),
+                    history: [], // Empty history for prepare/finalize
+                    data,
+                });
+                if (!result.success) {
+                    index_js_1.logger.error(`[Agent] Tool execution failed in prepare/finalize: ${result.error}`);
+                    throw new Error(`Tool execution failed: ${result.error}`);
+                }
+            }
+            else {
+                index_js_1.logger.warn(`[Agent] Tool not found for prepare/finalize: ${typeof prepareOrFinalize === "string"
+                    ? prepareOrFinalize
+                    : "inline tool"}`);
+            }
+        }
+    }
+    /**
+     * Get collected data from the current session (or the pre-session staging
+     * buffer when no session exists yet). Alias of getCollectedData().
+     */
+    getData() {
+        return this.getCollectedData();
+    }
+    /**
+     * 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 }`.
+     *
+     * Durability: with a persistence adapter and autoSave configured (the
+     * defaults), the queued directive is persisted immediately — safe for
+     * out-of-process callers like webhooks or cron. Without an adapter it is
+     * memory-only, as is `persistence.autoSave: false` (then persisting before
+     * the next turn is the caller's job).
+     *
+     * @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
+     * @throws SessionConflictError when persistence is enabled and another writer
+     * moved the stored session since this copy was loaded
+     *
+     * @example
+     * // String shorthand — desugars to { goTo: 'Feedback' }
+     * const updated = await agent.dispatch('Feedback', session);
+     *
+     * @example
+     * // Full directive
+     * const updated = await agent.dispatch({ goTo: 'Billing', reply: 'Transferring you now.' }, session);
+     */
+    async dispatch(target, session) {
+        const targetSession = session || this.session.current;
+        if (!targetSession) {
+            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 Step_js_1.FlowConfigurationError(`[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 Step_js_1.FlowConfigurationError(`[FlowConfigurationError] Unknown flow: "${flowTarget}" does not match any flow id or title. ` +
+                    `Available flows: ${this._flows.map(f => f.title).join(', ')}.`);
+            }
+        }
+        // Strip pre-LLM-only fields before storing
+        const stripped = this.stripPreDirectiveFields(directive);
+        // Set pendingDirective on the session without applying it
+        const updatedSession = {
+            ...targetSession,
+            pendingDirective: stripped,
+            metadata: {
+                ...targetSession.metadata,
+                lastUpdatedAt: new Date(),
+            },
+        };
+        // Durability: with an adapter + autoSave configured, dispatch persists
+        // immediately — webhooks/cron run out-of-process from the responder, and a
+        // memory-only queue would evaporate with this process. The save stamps the
+        // new version back onto updatedSession, so the next turn's auto-save CAS
+        // stays clean. Persisting BEFORE the in-memory sync keeps the existing
+        // invariant: a throwing dispatch leaves the session untouched.
+        if (this._persistenceManager && this.options.persistence?.autoSave !== false) {
+            await this._persistenceManager.saveSessionState(updatedSession.id, updatedSession);
+            index_js_1.logger.debug(`[Agent] Dispatched directive persisted to adapter for session ${updatedSession.id}`);
+        }
+        // Update current session in place if no explicit session was passed
+        if (!session && this.session.current) {
+            this.session.syncSession(updatedSession);
+        }
+        index_js_1.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 = (0, index_js_1.enterFlow)(updatedSession, targetFlow.id, targetFlow.title);
+                    // If a specific step is targeted
+                    if (typeof directive.goTo === 'object' && directive.goTo.step) {
+                        updatedSession = (0, index_js_1.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 = (0, index_js_1.enterStep)(updatedSession, stepTarget);
+        }
+        else if (directive.complete) {
+            updatedSession = (0, index_js_1.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 = (0, index_js_1.completeCurrentFlow)(updatedSession, { clearOwnedFields: ownedFields });
+                        // Re-enter the same flow
+                        updatedSession = (0, index_js_1.enterFlow)(updatedSession, currentFlowId, currentFlowTitle);
+                    }
+                }
+                else {
+                    // Re-enter the flow from the beginning (or specified step)
+                    updatedSession = (0, index_js_1.enterFlow)(updatedSession, currentFlowId, currentFlowTitle);
+                }
+                // If a specific step is targeted for reset
+                if (typeof directive.reset === 'object' && directive.reset.step) {
+                    updatedSession = (0, index_js_1.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 Step_js_1.FlowConfigurationError(`[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 Step_js_1.FlowConfigurationError(`[FlowConfigurationError] Empty goTo: "goTo" requires at least a "flow" field. ` +
+                    `Provide { goTo: { flow: '<id>' } } or use the string shorthand { goTo: '<id>' }.`);
+            }
+        }
+    }
+    /**
+     * Strip pre-LLM-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) {
+            index_js_1.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(', ')}`);
+        }
+        return rest;
+    }
+    /**
+     * Simplified respond method using SessionManager
+     * Automatically manages conversation history through the session
+     */
+    async chat(message, options) {
+        // Delegate to ResponseModal.generate()
+        return this._responseModal.generate(message, options);
+    }
+    /**
+     * Modern streaming API - simple interface like chat() but returns a stream
+     * Automatically manages conversation history through the session
+     */
+    async *stream(message, options) {
+        // Delegate to ResponseModal with the same options structure as chat()
+        yield* this._responseModal.stream(message, {
+            history: options?.history,
+            contextOverride: options?.contextOverride,
+            signal: options?.signal,
+        });
+    }
+}
+exports.Agent = Agent;
+//# sourceMappingURL=Agent.js.map