@dexto/core 1.1.10 → 1.2.0

package/dist/plugins/manager.cjs

@@ -0,0 +1,386 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var manager_exports = {};
+__export(manager_exports, {
+  PluginManager: () => PluginManager
+});
+module.exports = __toCommonJS(manager_exports);
+var import_logger = require("../logger/index.js");
+var import_errors = require("../errors/index.js");
+var import_error_codes = require("./error-codes.js");
+var import_loader = require("./loader.js");
+var import_async_context = require("../utils/async-context.js");
+class PluginManager {
+  plugins = /* @__PURE__ */ new Map();
+  pluginsByExtensionPoint = /* @__PURE__ */ new Map();
+  options;
+  initialized = false;
+  /** Default timeout for plugin execution (milliseconds) */
+  static DEFAULT_TIMEOUT = 5e3;
+  constructor(options) {
+    this.options = options;
+    import_logger.logger.debug("PluginManager created");
+  }
+  /**
+   * Register a built-in plugin
+   * Called by the built-in plugin registry before initialize()
+   *
+   * @param name - Plugin name
+   * @param PluginClass - Plugin class constructor
+   * @param config - Plugin configuration
+   */
+  registerBuiltin(name, PluginClass, config) {
+    if (this.initialized) {
+      throw new import_errors.DextoRuntimeError(
+        import_error_codes.PluginErrorCode.PLUGIN_CONFIGURATION_INVALID,
+        import_errors.ErrorScope.PLUGIN,
+        import_errors.ErrorType.SYSTEM,
+        "Cannot register built-in plugins after initialization"
+      );
+    }
+    const plugin = new PluginClass();
+    const loadedPlugin = {
+      plugin,
+      config: {
+        name,
+        module: `<builtin:${name}>`,
+        enabled: config.enabled ?? true,
+        blocking: config.blocking,
+        priority: config.priority,
+        config: config.config ?? void 0
+      }
+    };
+    this.plugins.set(name, loadedPlugin);
+    import_logger.logger.debug(`Built-in plugin registered: ${name}`);
+  }
+  /**
+   * Initialize all plugins from configuration
+   * Loads custom plugins, validates priorities, sorts by priority, and calls initialize()
+   *
+   * @param customPlugins - Array of custom plugin configurations from YAML
+   * @throws {DextoRuntimeError} If any plugin fails to load or initialize (fail-fast)
+   */
+  async initialize(customPlugins = []) {
+    if (this.initialized) {
+      throw new import_errors.DextoRuntimeError(
+        import_error_codes.PluginErrorCode.PLUGIN_CONFIGURATION_INVALID,
+        import_errors.ErrorScope.PLUGIN,
+        import_errors.ErrorType.SYSTEM,
+        "PluginManager already initialized"
+      );
+    }
+    const priorities = /* @__PURE__ */ new Set();
+    const allPlugins = [...this.plugins.values(), ...customPlugins.map((c) => ({ config: c }))];
+    for (const item of allPlugins) {
+      const config = "config" in item ? item.config : item;
+      if (!config.enabled) continue;
+      if (priorities.has(config.priority)) {
+        throw new import_errors.DextoRuntimeError(
+          import_error_codes.PluginErrorCode.PLUGIN_DUPLICATE_PRIORITY,
+          import_errors.ErrorScope.PLUGIN,
+          import_errors.ErrorType.USER,
+          `Duplicate plugin priority: ${config.priority}. Each plugin must have a unique priority.`,
+          {
+            priority: config.priority,
+            hint: "Ensure all enabled plugins (built-in and custom) have unique priority values."
+          }
+        );
+      }
+      priorities.add(config.priority);
+    }
+    for (const pluginConfig of customPlugins) {
+      if (!pluginConfig.enabled) {
+        import_logger.logger.debug(`Skipping disabled plugin: ${pluginConfig.name}`);
+        continue;
+      }
+      try {
+        const modulePath = (0, import_loader.resolvePluginPath)(pluginConfig.module, this.options.configDir);
+        const PluginClass = await (0, import_loader.loadPluginModule)(modulePath, pluginConfig.name);
+        const plugin = new PluginClass();
+        const loadedPlugin = {
+          plugin,
+          config: pluginConfig
+        };
+        this.plugins.set(pluginConfig.name, loadedPlugin);
+        import_logger.logger.info(`Custom plugin loaded: ${pluginConfig.name}`);
+      } catch (error) {
+        throw new import_errors.DextoRuntimeError(
+          import_error_codes.PluginErrorCode.PLUGIN_INITIALIZATION_FAILED,
+          import_errors.ErrorScope.PLUGIN,
+          import_errors.ErrorType.SYSTEM,
+          `Failed to load plugin '${pluginConfig.name}': ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    for (const [name, loadedPlugin] of this.plugins.entries()) {
+      if (!loadedPlugin.config.enabled) continue;
+      try {
+        if (loadedPlugin.plugin.initialize) {
+          await loadedPlugin.plugin.initialize(loadedPlugin.config.config || {});
+          import_logger.logger.debug(`Plugin initialized: ${name}`);
+        }
+      } catch (error) {
+        throw new import_errors.DextoRuntimeError(
+          import_error_codes.PluginErrorCode.PLUGIN_INITIALIZATION_FAILED,
+          import_errors.ErrorScope.PLUGIN,
+          import_errors.ErrorType.SYSTEM,
+          `Plugin '${name}' initialization failed: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    for (const loadedPlugin of this.plugins.values()) {
+      if (!loadedPlugin.config.enabled) continue;
+      this.registerToExtensionPoints(loadedPlugin);
+    }
+    for (const [extensionPoint, plugins] of this.pluginsByExtensionPoint.entries()) {
+      plugins.sort((a, b) => a.config.priority - b.config.priority);
+      import_logger.logger.debug(
+        `Extension point '${extensionPoint}': ${plugins.length} plugin(s) registered`,
+        {
+          plugins: plugins.map((p) => ({
+            name: p.config.name,
+            priority: p.config.priority
+          }))
+        }
+      );
+    }
+    this.initialized = true;
+    import_logger.logger.info(`PluginManager initialized with ${this.plugins.size} plugin(s)`);
+  }
+  /**
+   * Register a plugin to the extension points it implements
+   */
+  registerToExtensionPoints(loadedPlugin) {
+    const extensionPoints = [
+      "beforeLLMRequest",
+      "beforeToolCall",
+      "afterToolResult",
+      "beforeResponse"
+    ];
+    for (const point of extensionPoints) {
+      if (typeof loadedPlugin.plugin[point] === "function") {
+        if (!this.pluginsByExtensionPoint.has(point)) {
+          this.pluginsByExtensionPoint.set(point, []);
+        }
+        this.pluginsByExtensionPoint.get(point).push(loadedPlugin);
+      }
+    }
+  }
+  /**
+   * Execute all plugins at a specific extension point
+   * Plugins execute sequentially in priority order
+   *
+   * @param extensionPoint - Which extension point to execute
+   * @param payload - Payload for this extension point (must be an object)
+   * @param options - Options for building execution context
+   * @returns Modified payload after all plugins execute
+   * @throws {DextoRuntimeError} If a blocking plugin cancels execution or payload is not an object
+   */
+  async executePlugins(extensionPoint, payload, options) {
+    const plugins = this.pluginsByExtensionPoint.get(extensionPoint) || [];
+    if (plugins.length === 0) {
+      return payload;
+    }
+    if (payload === null || typeof payload !== "object") {
+      throw new import_errors.DextoRuntimeError(
+        import_error_codes.PluginErrorCode.PLUGIN_INVALID_SHAPE,
+        import_errors.ErrorScope.PLUGIN,
+        import_errors.ErrorType.USER,
+        `Payload for ${extensionPoint} must be an object (got ${payload === null ? "null" : typeof payload})`,
+        { extensionPoint, payloadType: typeof payload }
+      );
+    }
+    let currentPayload = { ...payload };
+    const asyncCtx = (0, import_async_context.getContext)();
+    const llmConfig = options.stateManager.getLLMConfig(options.sessionId);
+    const context = {
+      sessionId: options.sessionId ?? void 0,
+      userId: asyncCtx?.userId ?? void 0,
+      tenantId: asyncCtx?.tenantId ?? void 0,
+      llmConfig,
+      logger: import_logger.logger,
+      abortSignal: options.abortSignal ?? void 0,
+      agent: {
+        sessionManager: options.sessionManager,
+        mcpManager: options.mcpManager,
+        toolManager: options.toolManager,
+        stateManager: options.stateManager,
+        agentEventBus: this.options.agentEventBus,
+        storageManager: this.options.storageManager
+      }
+    };
+    for (const { plugin, config } of plugins) {
+      const method = plugin[extensionPoint];
+      if (!method) continue;
+      const startTime = Date.now();
+      try {
+        const result = await this.executeWithTimeout(
+          method.call(plugin, currentPayload, context),
+          config.name,
+          PluginManager.DEFAULT_TIMEOUT
+        );
+        const duration = Date.now() - startTime;
+        import_logger.logger.debug(`Plugin '${config.name}' executed at ${extensionPoint}`, {
+          ok: result.ok,
+          cancelled: result.cancel,
+          duration,
+          hasModifications: !!result.modify
+        });
+        if (result.notices && result.notices.length > 0) {
+          for (const notice of result.notices) {
+            const level = notice.kind === "block" || notice.kind === "warn" ? "warn" : "info";
+            import_logger.logger[level](`Plugin notice (${notice.kind}): ${notice.message}`, {
+              plugin: config.name,
+              code: notice.code,
+              details: notice.details
+            });
+          }
+        }
+        if (!result.ok) {
+          import_logger.logger.warn(`Plugin '${config.name}' returned error`, {
+            message: result.message
+          });
+          if (config.blocking && result.cancel) {
+            throw new import_errors.DextoRuntimeError(
+              import_error_codes.PluginErrorCode.PLUGIN_BLOCKED_EXECUTION,
+              import_errors.ErrorScope.PLUGIN,
+              import_errors.ErrorType.FORBIDDEN,
+              result.message || `Operation blocked by plugin '${config.name}'`,
+              {
+                plugin: config.name,
+                extensionPoint,
+                notices: result.notices
+              }
+            );
+          }
+          continue;
+        }
+        if (result.modify) {
+          currentPayload = { ...currentPayload, ...result.modify };
+          import_logger.logger.debug(`Plugin '${config.name}' modified payload`, {
+            keys: Object.keys(result.modify)
+          });
+        }
+        if (result.cancel && config.blocking) {
+          throw new import_errors.DextoRuntimeError(
+            import_error_codes.PluginErrorCode.PLUGIN_BLOCKED_EXECUTION,
+            import_errors.ErrorScope.PLUGIN,
+            import_errors.ErrorType.FORBIDDEN,
+            result.message || `Operation cancelled by plugin '${config.name}'`,
+            {
+              plugin: config.name,
+              extensionPoint,
+              notices: result.notices
+            }
+          );
+        }
+      } catch (error) {
+        const duration = Date.now() - startTime;
+        if (error instanceof import_errors.DextoRuntimeError) {
+          throw error;
+        }
+        import_logger.logger.error(`Plugin '${config.name}' threw error`, {
+          error: error instanceof Error ? error.message : String(error),
+          duration
+        });
+        if (config.blocking) {
+          throw new import_errors.DextoRuntimeError(
+            import_error_codes.PluginErrorCode.PLUGIN_EXECUTION_FAILED,
+            import_errors.ErrorScope.PLUGIN,
+            import_errors.ErrorType.SYSTEM,
+            `Plugin '${config.name}' failed: ${error instanceof Error ? error.message : String(error)}`,
+            {
+              plugin: config.name,
+              extensionPoint
+            }
+          );
+        }
+        import_logger.logger.debug(`Non-blocking plugin error, continuing execution`);
+      }
+    }
+    return currentPayload;
+  }
+  /**
+   * Execute a promise with timeout, properly clearing timer on completion
+   * Prevents timer leaks and unhandled rejections from Promise.race
+   */
+  async executeWithTimeout(promise, pluginName, ms) {
+    let timer;
+    return await new Promise((resolve, reject) => {
+      timer = setTimeout(() => {
+        reject(
+          new import_errors.DextoRuntimeError(
+            import_error_codes.PluginErrorCode.PLUGIN_EXECUTION_TIMEOUT,
+            import_errors.ErrorScope.PLUGIN,
+            import_errors.ErrorType.TIMEOUT,
+            `Plugin '${pluginName}' execution timed out after ${ms}ms`
+          )
+        );
+      }, ms);
+      promise.then(
+        (val) => {
+          if (timer) clearTimeout(timer);
+          resolve(val);
+        },
+        (err) => {
+          if (timer) clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+  /**
+   * Cleanup all plugins
+   * Called when agent shuts down
+   */
+  async cleanup() {
+    for (const [name, loadedPlugin] of this.plugins.entries()) {
+      if (loadedPlugin.plugin.cleanup) {
+        try {
+          await loadedPlugin.plugin.cleanup();
+          import_logger.logger.debug(`Plugin cleaned up: ${name}`);
+        } catch (error) {
+          import_logger.logger.error(`Plugin cleanup failed: ${name}`, {
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    }
+    import_logger.logger.info("PluginManager cleanup complete");
+  }
+  /**
+   * Get plugin statistics
+   */
+  getStats() {
+    const enabled = Array.from(this.plugins.values()).filter((p) => p.config.enabled).length;
+    const byExtensionPoint = {};
+    for (const [point, plugins] of this.pluginsByExtensionPoint.entries()) {
+      byExtensionPoint[point] = plugins.length;
+    }
+    return {
+      total: this.plugins.size,
+      enabled,
+      byExtensionPoint
+    };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PluginManager
+});

package/dist/plugins/manager.d.ts

@@ -0,0 +1,97 @@
+import type { ExtensionPoint, PluginConfig } from './types.js';
+import type { AgentEventBus } from '../events/index.js';
+import type { StorageManager } from '../storage/index.js';
+import type { SessionManager } from '../session/index.js';
+import type { MCPManager } from '../mcp/manager.js';
+import type { ToolManager } from '../tools/tool-manager.js';
+import type { AgentStateManager } from '../agent/state-manager.js';
+/**
+ * Options for PluginManager construction
+ */
+export interface PluginManagerOptions {
+    agentEventBus: AgentEventBus;
+    storageManager: StorageManager;
+    configDir: string;
+}
+/**
+ * Options for building ExecutionContext
+ * Used when calling executePlugins
+ */
+export interface ExecutionContextOptions {
+    sessionManager: SessionManager;
+    mcpManager: MCPManager;
+    toolManager: ToolManager;
+    stateManager: AgentStateManager;
+    sessionId?: string;
+    abortSignal?: AbortSignal;
+}
+/**
+ * Plugin Manager - Orchestrates plugin loading and execution
+ *
+ * Responsibilities:
+ * - Load plugins from configuration (built-in + custom)
+ * - Validate plugin shape and priority uniqueness
+ * - Manage plugin lifecycle (initialize, execute, cleanup)
+ * - Execute plugins sequentially at extension points
+ * - Handle timeouts and errors with fail-fast policy
+ */
+export declare class PluginManager {
+    private plugins;
+    private pluginsByExtensionPoint;
+    private options;
+    private initialized;
+    /** Default timeout for plugin execution (milliseconds) */
+    private static readonly DEFAULT_TIMEOUT;
+    constructor(options: PluginManagerOptions);
+    /**
+     * Register a built-in plugin
+     * Called by the built-in plugin registry before initialize()
+     *
+     * @param name - Plugin name
+     * @param PluginClass - Plugin class constructor
+     * @param config - Plugin configuration
+     */
+    registerBuiltin(name: string, PluginClass: any, config: Omit<PluginConfig, 'module'>): void;
+    /**
+     * Initialize all plugins from configuration
+     * Loads custom plugins, validates priorities, sorts by priority, and calls initialize()
+     *
+     * @param customPlugins - Array of custom plugin configurations from YAML
+     * @throws {DextoRuntimeError} If any plugin fails to load or initialize (fail-fast)
+     */
+    initialize(customPlugins?: PluginConfig[]): Promise<void>;
+    /**
+     * Register a plugin to the extension points it implements
+     */
+    private registerToExtensionPoints;
+    /**
+     * Execute all plugins at a specific extension point
+     * Plugins execute sequentially in priority order
+     *
+     * @param extensionPoint - Which extension point to execute
+     * @param payload - Payload for this extension point (must be an object)
+     * @param options - Options for building execution context
+     * @returns Modified payload after all plugins execute
+     * @throws {DextoRuntimeError} If a blocking plugin cancels execution or payload is not an object
+     */
+    executePlugins<T extends Record<string, any>>(extensionPoint: ExtensionPoint, payload: T, options: ExecutionContextOptions): Promise<T>;
+    /**
+     * Execute a promise with timeout, properly clearing timer on completion
+     * Prevents timer leaks and unhandled rejections from Promise.race
+     */
+    private executeWithTimeout;
+    /**
+     * Cleanup all plugins
+     * Called when agent shuts down
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get plugin statistics
+     */
+    getStats(): {
+        total: number;
+        enabled: number;
+        byExtensionPoint: Record<ExtensionPoint, number>;
+    };
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/plugins/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/plugins/manager.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACR,cAAc,EAEd,YAAY,EAGf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,cAAc,EAAE,cAAc,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACpC,cAAc,EAAE,cAAc,CAAC;IAC/B,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,iBAAiB,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,OAAO,CAAwC;IACvD,OAAO,CAAC,uBAAuB,CAAkD;IACjF,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,WAAW,CAAkB;IAErC,0DAA0D;IAC1D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAQ;gBAEnC,OAAO,EAAE,oBAAoB;IAKzC;;;;;;;OAOG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,GAAG,IAAI;IA8B3F;;;;;;OAMG;IACG,UAAU,CAAC,aAAa,GAAE,YAAY,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAqHnE;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAkBjC;;;;;;;;;OASG;IACG,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9C,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,CAAC,EACV,OAAO,EAAE,uBAAuB,GACjC,OAAO,CAAC,CAAC,CAAC;IAoKb;;;OAGG;YACW,kBAAkB;IA8BhC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B;;OAEG;IACH,QAAQ,IAAI;QACR,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;KACpD;CAcJ"}