@falai/agent 3.4.5 → 4.0.0-alpha.2

package/dist/core/Agent.js

@@ -1,1194 +1,120 @@
 /**
- * Core Agent implementation
+ * Agent: immutable configuration plus one entry point, `turn`.
+ *
+ * One instance serves every session; context and history arrive per turn.
+ * A turn is the eight phases of docs/rfc/v4-one-flow.md §4 in one line each:
+ * Runner moves the runs by code, Understand and Speak spend at most one
+ * provider call apiece, and Runner settles what they returned.
  */
-import { NotImplementedError } from "../types/errors.js";
-import { SignalProcessor } from "./SignalProcessor.js";
-import { SignalEvaluator } from "./SignalEvaluator.js";
-import { mergeCollected, dropUndeclaredFields, enterFlow, enterStep, completeCurrentFlow, logger, LoggerLevel, generateSignalId, } from "../utils/index.js";
-import { Flow } from "./Flow.js";
-import { FlowConfigurationError as StepFlowConfigurationError } from "./Step.js";
-import { PersistenceManager } from "./PersistenceManager.js";
-import { SessionManager } from "./SessionManager.js";
-import { FlowRouter } from "./FlowRouter.js";
-import { PromptSectionCache } from "./PromptSectionCache.js";
-import { ResponseModal } from "./ResponseModal.js";
-import { ToolManager } from "./ToolManager.js";
+import { FlowConfigurationError } from "../types/errors.js";
+import { logger, LoggerLevel } from "../utils/logger.js";
+import { addUsage } from "../utils/usage.js";
 import { CompactionEngine } from "./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
- */
+import { validateFlow } from "./FlowSpec.js";
+import { Runner } from "./Runner.js";
+import { Speak } from "./Speak.js";
+import { Understand } from "./Understand.js";
 export 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 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. 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) {
-            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.`);
+        if (options.debug)
             logger.setLevel(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);
-            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 };
-            logger.debug("[Agent] Initial data set:", this._pendingData);
-        }
-        // Initialize prompt section cache
-        this._promptSectionCache = new PromptSectionCache(options.promptCache);
-        // Initialize flow router
-        this._routingEngine = new 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(this);
-        // Initialize ResponseModal for handling all response generation
-        this._responseModal = new 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(options.persistence);
-                // Initialize the adapter if it has an initialize method
-                if (options.persistence.adapter.initialize) {
-                    options.persistence.adapter.initialize().catch((error) => {
-                        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);
-                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.validateOptions(compactionOptions);
-            this._compactionOptions = compactionOptions;
-            logger.debug("[Agent] Compaction options initialized and validated");
-        }
-        // Initialize session manager — the single owner of the live session
-        this.session = new 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) => {
-                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' } } }");
-        }
-        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.
-     *
-     * 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 = 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(', ');
-            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;
-        }
-        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;
-        logger.setLevel(value ? LoggerLevel.DEBUG : 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];
+        validate(options);
+        this.compaction = compactionOptions(options);
+        this.runner = new Runner(options);
+        this.understand = new Understand(options);
+        this.speak = new Speak(options);
+    }
+    /** Take whatever just happened and return the messages to send and the timers to set. */
+    async turn(input) {
+        const { turn, talk } = await this.open(input);
+        await this.runner.settle(turn, talk ? await this.speak.run(this.runner.speakRequest(turn, talk)) : null);
+        return this.runner.finish(turn);
+    }
+    /** `turn`, streaming the spoken text as it is generated; the last chunk carries the result. */
+    async *turnStream(input) {
+        const { turn, talk } = await this.open(input);
+        let outcome = null;
+        if (talk) {
+            for await (const chunk of this.speak.stream(this.runner.speakRequest(turn, talk))) {
+                if ("delta" in chunk)
+                    yield { delta: chunk.delta };
+                else
+                    outcome = chunk.outcome;
+            }
+        }
+        await this.runner.settle(turn, outcome);
+        yield { done: true, result: this.runner.finish(turn) };
+    }
+    /** Load, Ingest, Understand, Decide and Run: everything before the one speaker is known. */
+    async open(input) {
+        const { runner } = this;
+        const compacted = await this.compacted(input);
+        const turn = runner.begin(compacted.input);
+        turn.llmCalls += compacted.llmCalls;
+        turn.usage = addUsage(turn.usage, compacted.usage);
+        const request = runner.understandRequest(turn);
+        runner.decide(turn, request ? await this.understand.run(request) : null);
+        return { turn, talk: await runner.advance(turn) };
+    }
+    /** With `compaction` set, the history both calls see is trimmed once per turn; a summarization is one model call. */
+    async compacted(input) {
+        const history = input.history ?? input.session?.history;
+        if (!this.compaction || !history?.length)
+            return { input, llmCalls: 0 };
+        const result = await CompactionEngine.checkAndCompact(history, this.compaction);
+        const llmCalls = result.strategy === "auto_compact" ? 1 : 0;
+        const usage = result.usage ? { usage: result.usage } : {};
+        if (result.history === history)
+            return { input, llmCalls, ...usage };
+        const trimmed = Object.assign({}, input);
+        trimmed.history = result.history;
+        return { input: trimmed, llmCalls, ...usage };
     }
-    /**
-     * 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) {
-                    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(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);
-        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);
-        });
-        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 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 {
-                    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) {
-                    logger.error(`[Agent] Tool execution failed in prepare/finalize: ${result.error}`);
-                    throw new Error(`Tool execution failed: ${result.error}`);
-                }
-            }
-            else {
-                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 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 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);
-            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);
-        }
-        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>' }.`);
+}
+function compactionOptions(options) {
+    const config = options.compaction;
+    if (!config || config.enabled === false)
+        return undefined;
+    const resolved = {
+        maxTokens: config.maxTokens,
+        compactionThreshold: config.compactionThreshold ?? 0.8,
+        preserveRecentCount: config.preserveRecentCount ?? 4,
+        maxToolResultChars: config.maxToolResultChars ?? 5000,
+        provider: options.provider,
+    };
+    CompactionEngine.validateOptions(resolved);
+    return resolved;
+}
+/** Every name a flow uses must resolve now, not on the turn that first reaches it. */
+function validate(options) {
+    const ids = new Set();
+    for (const flow of options.flows ?? []) {
+        if (ids.has(flow.id)) {
+            throw new FlowConfigurationError(`[FlowConfigurationError] flow "${flow.id}" is declared twice: flow ids must be unique. Rename one of them.`);
+        }
+        ids.add(flow.id);
+        for (const warning of validateFlow(flow, options).warnings)
+            logger.warn(`[Agent] ${warning}`);
+    }
+    for (const tool of options.tools ?? []) {
+        // A function's parameters are a JSON Schema object, so anything else is a
+        // mistake — most often the action's `{ name: { type } }` map written in a
+        // tool. Only DeepSeek rejects it on the wire; everywhere else the tool is
+        // simply never callable, and nothing says so.
+        if (tool.parameters && tool.parameters.type !== "object") {
+            throw new FlowConfigurationError(`[FlowConfigurationError] tool "${tool.id}": parameters must be a JSON Schema object. ` +
+                `Write { type: "object", properties: { ... }, required: [...] }.`);
+        }
+    }
+    const { idle } = options;
+    if (idle && idle !== "silent") {
+        const known = new Set((options.tools ?? []).map((tool) => tool.id));
+        for (const name of idle.tools ?? []) {
+            if (!known.has(name)) {
+                throw new FlowConfigurationError(`[FlowConfigurationError] idle: unknown tool "${name}". Register it in the agent's tools or fix the name.`);
             }
         }
     }
-    /**
-     * 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) {
-            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,
-        });
-    }
 }
 //# sourceMappingURL=Agent.js.map