@dexto/core 1.5.7 → 1.6.0

package/dist/plugins/manager.js

@@ -1,450 +0,0 @@
-import "../chunk-PTJYTZNU.js";
-import { DextoRuntimeError, ErrorScope, ErrorType } from "../errors/index.js";
-import { PluginErrorCode } from "./error-codes.js";
-import { loadPluginModule, resolvePluginPath } from "./loader.js";
-import { getContext } from "../utils/async-context.js";
-import { pluginRegistry } from "./registry.js";
-import { DextoLogComponent } from "../logger/v2/types.js";
-class PluginManager {
-  plugins = /* @__PURE__ */ new Map();
-  pluginsByExtensionPoint = /* @__PURE__ */ new Map();
-  options;
-  initialized = false;
-  logger;
-  /** Default timeout for plugin execution (milliseconds) */
-  static DEFAULT_TIMEOUT = 5e3;
-  constructor(options, logger) {
-    this.options = options;
-    this.logger = logger.createChild(DextoLogComponent.PLUGIN);
-    this.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 DextoRuntimeError(
-        PluginErrorCode.PLUGIN_CONFIGURATION_INVALID,
-        ErrorScope.PLUGIN,
-        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);
-    this.logger.debug(`Built-in plugin registered: ${name}`);
-  }
-  /**
-   * Initialize all plugins from configuration
-   * Loads custom plugins (file-based), registry plugins (programmatic), validates priorities,
-   * sorts by priority, and calls initialize()
-   *
-   * TODO: Consider adding an MCP server-like convention for plugin discovery.
-   * Instead of requiring explicit file paths, plugins could be connected as
-   * plugin servers to the PluginManager.
-   *
-   * @param customPlugins - Array of custom plugin configurations from YAML (file-based)
-   * @param registryPlugins - Array of registry plugin configurations from YAML (programmatic)
-   * @throws {DextoRuntimeError} If any plugin fails to load or initialize (fail-fast)
-   */
-  async initialize(customPlugins = [], registryPlugins = []) {
-    if (this.initialized) {
-      throw new DextoRuntimeError(
-        PluginErrorCode.PLUGIN_CONFIGURATION_INVALID,
-        ErrorScope.PLUGIN,
-        ErrorType.SYSTEM,
-        "PluginManager already initialized"
-      );
-    }
-    const priorities = /* @__PURE__ */ new Set();
-    const allPluginConfigs = [
-      ...Array.from(this.plugins.values()).map((p) => p.config),
-      ...customPlugins,
-      ...registryPlugins.map((r) => ({
-        name: r.type,
-        module: `<registry:${r.type}>`,
-        enabled: r.enabled,
-        blocking: r.blocking,
-        priority: r.priority,
-        config: r.config
-      }))
-    ];
-    for (const config of allPluginConfigs) {
-      if (!config.enabled) continue;
-      if (priorities.has(config.priority)) {
-        throw new DextoRuntimeError(
-          PluginErrorCode.PLUGIN_DUPLICATE_PRIORITY,
-          ErrorScope.PLUGIN,
-          ErrorType.USER,
-          `Duplicate plugin priority: ${config.priority}. Each plugin must have a unique priority.`,
-          {
-            priority: config.priority,
-            hint: "Ensure all enabled plugins (built-in, custom, and registry) have unique priority values."
-          }
-        );
-      }
-      priorities.add(config.priority);
-    }
-    for (const registryConfig of registryPlugins) {
-      if (!registryConfig.enabled) {
-        this.logger.debug(`Skipping disabled registry plugin: ${registryConfig.type}`);
-        continue;
-      }
-      try {
-        const provider = pluginRegistry.get(registryConfig.type);
-        if (!provider) {
-          throw new DextoRuntimeError(
-            PluginErrorCode.PLUGIN_PROVIDER_NOT_FOUND,
-            ErrorScope.PLUGIN,
-            ErrorType.USER,
-            `Plugin provider '${registryConfig.type}' not found in registry`,
-            {
-              type: registryConfig.type,
-              available: pluginRegistry.getTypes()
-            },
-            `Available plugin providers: ${pluginRegistry.getTypes().join(", ") || "none"}. Register the provider using pluginRegistry.register() before agent initialization.`
-          );
-        }
-        const validatedConfig = provider.configSchema.safeParse({
-          type: registryConfig.type,
-          ...registryConfig.config
-        });
-        if (!validatedConfig.success) {
-          throw new DextoRuntimeError(
-            PluginErrorCode.PLUGIN_PROVIDER_VALIDATION_FAILED,
-            ErrorScope.PLUGIN,
-            ErrorType.USER,
-            `Invalid configuration for plugin provider '${registryConfig.type}'`,
-            {
-              type: registryConfig.type,
-              errors: validatedConfig.error.errors
-            },
-            "Check the configuration schema for this plugin provider"
-          );
-        }
-        const creationContext = {
-          config: registryConfig.config || {},
-          blocking: registryConfig.blocking,
-          priority: registryConfig.priority
-        };
-        const plugin = provider.create(validatedConfig.data, creationContext);
-        const loadedPlugin = {
-          plugin,
-          config: {
-            name: registryConfig.type,
-            module: `<registry:${registryConfig.type}>`,
-            enabled: registryConfig.enabled,
-            blocking: registryConfig.blocking,
-            priority: registryConfig.priority,
-            config: registryConfig.config
-          }
-        };
-        this.plugins.set(registryConfig.type, loadedPlugin);
-        this.logger.info(`Registry plugin loaded: ${registryConfig.type}`);
-      } catch (error) {
-        if (error instanceof DextoRuntimeError) {
-          throw error;
-        }
-        throw new DextoRuntimeError(
-          PluginErrorCode.PLUGIN_INITIALIZATION_FAILED,
-          ErrorScope.PLUGIN,
-          ErrorType.SYSTEM,
-          `Failed to load registry plugin '${registryConfig.type}': ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-    }
-    for (const pluginConfig of customPlugins) {
-      if (!pluginConfig.enabled) {
-        this.logger.debug(`Skipping disabled plugin: ${pluginConfig.name}`);
-        continue;
-      }
-      try {
-        const modulePath = resolvePluginPath(pluginConfig.module, this.options.configDir);
-        const PluginClass = await loadPluginModule(modulePath, pluginConfig.name);
-        const plugin = new PluginClass();
-        const loadedPlugin = {
-          plugin,
-          config: pluginConfig
-        };
-        this.plugins.set(pluginConfig.name, loadedPlugin);
-        this.logger.info(`Custom plugin loaded: ${pluginConfig.name}`);
-      } catch (error) {
-        throw new DextoRuntimeError(
-          PluginErrorCode.PLUGIN_INITIALIZATION_FAILED,
-          ErrorScope.PLUGIN,
-          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 || {});
-          this.logger.debug(`Plugin initialized: ${name}`);
-        }
-      } catch (error) {
-        throw new DextoRuntimeError(
-          PluginErrorCode.PLUGIN_INITIALIZATION_FAILED,
-          ErrorScope.PLUGIN,
-          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);
-      this.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;
-    this.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 DextoRuntimeError(
-        PluginErrorCode.PLUGIN_INVALID_SHAPE,
-        ErrorScope.PLUGIN,
-        ErrorType.USER,
-        `Payload for ${extensionPoint} must be an object (got ${payload === null ? "null" : typeof payload})`,
-        { extensionPoint, payloadType: typeof payload }
-      );
-    }
-    let currentPayload = { ...payload };
-    const asyncCtx = 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: this.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;
-        this.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";
-            this.logger[level](`Plugin notice (${notice.kind}): ${notice.message}`, {
-              plugin: config.name,
-              code: notice.code,
-              details: notice.details
-            });
-          }
-        }
-        if (!result.ok) {
-          this.logger.warn(`Plugin '${config.name}' returned error`, {
-            message: result.message
-          });
-          if (config.blocking && result.cancel) {
-            throw new DextoRuntimeError(
-              PluginErrorCode.PLUGIN_BLOCKED_EXECUTION,
-              ErrorScope.PLUGIN,
-              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 };
-          this.logger.debug(`Plugin '${config.name}' modified payload`, {
-            keys: Object.keys(result.modify)
-          });
-        }
-        if (result.cancel && config.blocking) {
-          throw new DextoRuntimeError(
-            PluginErrorCode.PLUGIN_BLOCKED_EXECUTION,
-            ErrorScope.PLUGIN,
-            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 DextoRuntimeError) {
-          throw error;
-        }
-        this.logger.error(`Plugin '${config.name}' threw error`, {
-          error: error instanceof Error ? error.message : String(error),
-          duration
-        });
-        if (config.blocking) {
-          throw new DextoRuntimeError(
-            PluginErrorCode.PLUGIN_EXECUTION_FAILED,
-            ErrorScope.PLUGIN,
-            ErrorType.SYSTEM,
-            `Plugin '${config.name}' failed: ${error instanceof Error ? error.message : String(error)}`,
-            {
-              plugin: config.name,
-              extensionPoint
-            }
-          );
-        }
-        this.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 DextoRuntimeError(
-            PluginErrorCode.PLUGIN_EXECUTION_TIMEOUT,
-            ErrorScope.PLUGIN,
-            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();
-          this.logger.debug(`Plugin cleaned up: ${name}`);
-        } catch (error) {
-          this.logger.error(`Plugin cleanup failed: ${name}`, {
-            error: error instanceof Error ? error.message : String(error)
-          });
-        }
-      }
-    }
-    this.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
-    };
-  }
-}
-export {
-  PluginManager
-};

package/dist/plugins/registrations/builtins.cjs

@@ -1,51 +0,0 @@
-"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 builtins_exports = {};
-__export(builtins_exports, {
-  registerBuiltInPlugins: () => registerBuiltInPlugins
-});
-module.exports = __toCommonJS(builtins_exports);
-var import_content_policy = require("../builtins/content-policy.js");
-var import_response_sanitizer = require("../builtins/response-sanitizer.js");
-function registerBuiltInPlugins(args) {
-  const cp = args.config.plugins?.contentPolicy;
-  if (cp && typeof cp === "object" && cp.enabled !== false) {
-    args.pluginManager.registerBuiltin("content-policy", import_content_policy.ContentPolicyPlugin, {
-      name: "content-policy",
-      enabled: cp.enabled ?? true,
-      priority: cp.priority,
-      blocking: cp.blocking ?? true,
-      config: cp
-    });
-  }
-  const rs = args.config.plugins?.responseSanitizer;
-  if (rs && typeof rs === "object" && rs.enabled !== false) {
-    args.pluginManager.registerBuiltin("response-sanitizer", import_response_sanitizer.ResponseSanitizerPlugin, {
-      name: "response-sanitizer",
-      enabled: rs.enabled ?? true,
-      priority: rs.priority,
-      blocking: rs.blocking ?? false,
-      config: rs
-    });
-  }
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  registerBuiltInPlugins
-});

package/dist/plugins/registrations/builtins.d.ts

@@ -1,17 +0,0 @@
-import type { PluginManager } from '../manager.js';
-import type { ValidatedAgentConfig } from '../../agent/schemas.js';
-/**
- * Register all built-in plugins with the PluginManager
- * Called during agent initialization before custom plugins are loaded
- *
- * Built-in plugins are referenced by name in the config (e.g., contentPolicy, responseSanitizer)
- * and activated based on presence of their configuration object.
- *
- * @param pluginManager - The PluginManager instance
- * @param config - Validated agent configuration
- */
-export declare function registerBuiltInPlugins(args: {
-    pluginManager: PluginManager;
-    config: ValidatedAgentConfig;
-}): void;
-//# sourceMappingURL=builtins.d.ts.map

package/dist/plugins/registrations/builtins.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../../src/plugins/registrations/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAInE;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IACzC,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,oBAAoB,CAAC;CAChC,GAAG,IAAI,CAwBP"}

package/dist/plugins/registrations/builtins.js

@@ -1,28 +0,0 @@
-import "../../chunk-PTJYTZNU.js";
-import { ContentPolicyPlugin } from "../builtins/content-policy.js";
-import { ResponseSanitizerPlugin } from "../builtins/response-sanitizer.js";
-function registerBuiltInPlugins(args) {
-  const cp = args.config.plugins?.contentPolicy;
-  if (cp && typeof cp === "object" && cp.enabled !== false) {
-    args.pluginManager.registerBuiltin("content-policy", ContentPolicyPlugin, {
-      name: "content-policy",
-      enabled: cp.enabled ?? true,
-      priority: cp.priority,
-      blocking: cp.blocking ?? true,
-      config: cp
-    });
-  }
-  const rs = args.config.plugins?.responseSanitizer;
-  if (rs && typeof rs === "object" && rs.enabled !== false) {
-    args.pluginManager.registerBuiltin("response-sanitizer", ResponseSanitizerPlugin, {
-      name: "response-sanitizer",
-      enabled: rs.enabled ?? true,
-      priority: rs.priority,
-      blocking: rs.blocking ?? false,
-      config: rs
-    });
-  }
-}
-export {
-  registerBuiltInPlugins
-};

package/dist/plugins/registry.cjs

@@ -1,63 +0,0 @@
-"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 registry_exports = {};
-__export(registry_exports, {
-  PluginRegistry: () => PluginRegistry,
-  pluginRegistry: () => pluginRegistry
-});
-module.exports = __toCommonJS(registry_exports);
-var import_errors = require("../errors/index.js");
-var import_error_codes = require("./error-codes.js");
-var import_base_registry = require("../providers/base-registry.js");
-const pluginRegistryErrorFactory = {
-  alreadyRegistered: (type) => new import_errors.DextoRuntimeError(
-    import_error_codes.PluginErrorCode.PLUGIN_PROVIDER_ALREADY_REGISTERED,
-    import_errors.ErrorScope.PLUGIN,
-    import_errors.ErrorType.USER,
-    `Plugin provider '${type}' is already registered`,
-    { type },
-    "Each plugin provider type can only be registered once"
-  ),
-  notFound: (type, availableTypes) => new import_errors.DextoRuntimeError(
-    import_error_codes.PluginErrorCode.PLUGIN_PROVIDER_NOT_FOUND,
-    import_errors.ErrorScope.PLUGIN,
-    import_errors.ErrorType.USER,
-    `Plugin provider '${type}' not found`,
-    { type, available: availableTypes },
-    `Available plugin providers: ${availableTypes.join(", ") || "none"}`
-  )
-};
-class PluginRegistry extends import_base_registry.BaseRegistry {
-  constructor() {
-    super(pluginRegistryErrorFactory);
-  }
-  /**
-   * Get all registered plugin providers.
-   * Alias for getAll() to match other registry patterns.
-   */
-  getProviders() {
-    return this.getAll();
-  }
-}
-const pluginRegistry = new PluginRegistry();
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  PluginRegistry,
-  pluginRegistry
-});