@dexto/core 1.1.10 → 1.2.0

package/dist/plugins/builtins/response-sanitizer.js

@@ -0,0 +1,79 @@
+import "../../chunk-C6A6W6XS.js";
+const DEFAULTS = {
+  redactEmails: false,
+  redactApiKeys: false,
+  maxResponseLength: 0
+};
+class ResponseSanitizerPlugin {
+  redactEmails = DEFAULTS.redactEmails;
+  redactApiKeys = DEFAULTS.redactApiKeys;
+  maxResponseLength = DEFAULTS.maxResponseLength;
+  async initialize(config) {
+    const sanitizerConfig = config;
+    this.redactEmails = sanitizerConfig.redactEmails ?? DEFAULTS.redactEmails;
+    this.redactApiKeys = sanitizerConfig.redactApiKeys ?? DEFAULTS.redactApiKeys;
+    this.maxResponseLength = sanitizerConfig.maxResponseLength ?? DEFAULTS.maxResponseLength;
+  }
+  async beforeResponse(payload, _context) {
+    const notices = [];
+    let modified = payload.content;
+    if (this.redactEmails) {
+      const replaced = modified.replace(
+        /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g,
+        "[redacted-email]"
+      );
+      if (replaced !== modified) {
+        notices.push({
+          kind: "info",
+          code: "response_sanitizer.redact_email",
+          message: "Email addresses were redacted from the response."
+        });
+        modified = replaced;
+      }
+    }
+    if (this.redactApiKeys) {
+      const replaced = modified.replace(
+        /(api[_-]?key|apikey|token|bearer|secret)\s*[:=]?\s*['"]?([A-Za-z0-9_-]{12,})['"]?/gi,
+        "$1 [redacted]"
+      );
+      if (replaced !== modified) {
+        notices.push({
+          kind: "info",
+          code: "response_sanitizer.redact_api_key",
+          message: "Potential API keys were redacted from the response."
+        });
+        modified = replaced;
+      }
+    }
+    if (this.maxResponseLength > 0 && modified.length > this.maxResponseLength) {
+      const originalLength = modified.length;
+      const suffix = "... [truncated]";
+      if (this.maxResponseLength <= suffix.length) {
+        modified = suffix.slice(0, this.maxResponseLength);
+      } else {
+        const adjustedLength = this.maxResponseLength - suffix.length;
+        modified = modified.slice(0, adjustedLength) + suffix;
+      }
+      notices.push({
+        kind: "warn",
+        code: "response_sanitizer.truncated",
+        message: `Response truncated to ${this.maxResponseLength} characters.`,
+        details: { originalLength }
+      });
+    }
+    if (modified !== payload.content) {
+      const result = {
+        ok: true,
+        modify: { content: modified }
+      };
+      if (notices.length > 0) {
+        result.notices = notices;
+      }
+      return result;
+    }
+    return { ok: true };
+  }
+}
+export {
+  ResponseSanitizerPlugin
+};

package/dist/plugins/error-codes.cjs

@@ -0,0 +1,39 @@
+"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 error_codes_exports = {};
+__export(error_codes_exports, {
+  PluginErrorCode: () => PluginErrorCode
+});
+module.exports = __toCommonJS(error_codes_exports);
+var PluginErrorCode = /* @__PURE__ */ ((PluginErrorCode2) => {
+  PluginErrorCode2["PLUGIN_LOAD_FAILED"] = "PLUGIN_LOAD_FAILED";
+  PluginErrorCode2["PLUGIN_INVALID_SHAPE"] = "PLUGIN_INVALID_SHAPE";
+  PluginErrorCode2["PLUGIN_INSTANTIATION_FAILED"] = "PLUGIN_INSTANTIATION_FAILED";
+  PluginErrorCode2["PLUGIN_INITIALIZATION_FAILED"] = "PLUGIN_INITIALIZATION_FAILED";
+  PluginErrorCode2["PLUGIN_CONFIGURATION_INVALID"] = "PLUGIN_CONFIGURATION_INVALID";
+  PluginErrorCode2["PLUGIN_EXECUTION_FAILED"] = "PLUGIN_EXECUTION_FAILED";
+  PluginErrorCode2["PLUGIN_EXECUTION_TIMEOUT"] = "PLUGIN_EXECUTION_TIMEOUT";
+  PluginErrorCode2["PLUGIN_BLOCKED_EXECUTION"] = "PLUGIN_BLOCKED_EXECUTION";
+  PluginErrorCode2["PLUGIN_DUPLICATE_PRIORITY"] = "PLUGIN_DUPLICATE_PRIORITY";
+  return PluginErrorCode2;
+})(PluginErrorCode || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PluginErrorCode
+});

package/dist/plugins/error-codes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Plugin-specific error codes
+ * Used for plugin loading, validation, and execution errors
+ */
+export declare enum PluginErrorCode {
+    /** Plugin file not found or cannot be loaded */
+    PLUGIN_LOAD_FAILED = "PLUGIN_LOAD_FAILED",
+    /** Plugin does not implement required interface */
+    PLUGIN_INVALID_SHAPE = "PLUGIN_INVALID_SHAPE",
+    /** Plugin constructor threw an error */
+    PLUGIN_INSTANTIATION_FAILED = "PLUGIN_INSTANTIATION_FAILED",
+    /** Plugin initialization failed */
+    PLUGIN_INITIALIZATION_FAILED = "PLUGIN_INITIALIZATION_FAILED",
+    /** Plugin configuration is invalid */
+    PLUGIN_CONFIGURATION_INVALID = "PLUGIN_CONFIGURATION_INVALID",
+    /** Plugin execution failed */
+    PLUGIN_EXECUTION_FAILED = "PLUGIN_EXECUTION_FAILED",
+    /** Plugin execution timed out */
+    PLUGIN_EXECUTION_TIMEOUT = "PLUGIN_EXECUTION_TIMEOUT",
+    /** Plugin blocked execution */
+    PLUGIN_BLOCKED_EXECUTION = "PLUGIN_BLOCKED_EXECUTION",
+    /** Duplicate plugin priority */
+    PLUGIN_DUPLICATE_PRIORITY = "PLUGIN_DUPLICATE_PRIORITY"
+}
+export type { PluginErrorCode as default };
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/plugins/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../src/plugins/error-codes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,oBAAY,eAAe;IACvB,gDAAgD;IAChD,kBAAkB,uBAAuB;IAEzC,mDAAmD;IACnD,oBAAoB,yBAAyB;IAE7C,wCAAwC;IACxC,2BAA2B,gCAAgC;IAE3D,mCAAmC;IACnC,4BAA4B,iCAAiC;IAE7D,sCAAsC;IACtC,4BAA4B,iCAAiC;IAE7D,8BAA8B;IAC9B,uBAAuB,4BAA4B;IAEnD,iCAAiC;IACjC,wBAAwB,6BAA6B;IAErD,+BAA+B;IAC/B,wBAAwB,6BAA6B;IAErD,gCAAgC;IAChC,yBAAyB,8BAA8B;CAC1D;AAED,YAAY,EAAE,eAAe,IAAI,OAAO,EAAE,CAAC"}

package/dist/plugins/error-codes.js

@@ -0,0 +1,16 @@
+import "../chunk-C6A6W6XS.js";
+var PluginErrorCode = /* @__PURE__ */ ((PluginErrorCode2) => {
+  PluginErrorCode2["PLUGIN_LOAD_FAILED"] = "PLUGIN_LOAD_FAILED";
+  PluginErrorCode2["PLUGIN_INVALID_SHAPE"] = "PLUGIN_INVALID_SHAPE";
+  PluginErrorCode2["PLUGIN_INSTANTIATION_FAILED"] = "PLUGIN_INSTANTIATION_FAILED";
+  PluginErrorCode2["PLUGIN_INITIALIZATION_FAILED"] = "PLUGIN_INITIALIZATION_FAILED";
+  PluginErrorCode2["PLUGIN_CONFIGURATION_INVALID"] = "PLUGIN_CONFIGURATION_INVALID";
+  PluginErrorCode2["PLUGIN_EXECUTION_FAILED"] = "PLUGIN_EXECUTION_FAILED";
+  PluginErrorCode2["PLUGIN_EXECUTION_TIMEOUT"] = "PLUGIN_EXECUTION_TIMEOUT";
+  PluginErrorCode2["PLUGIN_BLOCKED_EXECUTION"] = "PLUGIN_BLOCKED_EXECUTION";
+  PluginErrorCode2["PLUGIN_DUPLICATE_PRIORITY"] = "PLUGIN_DUPLICATE_PRIORITY";
+  return PluginErrorCode2;
+})(PluginErrorCode || {});
+export {
+  PluginErrorCode
+};

package/dist/plugins/index.cjs

@@ -0,0 +1,54 @@
+"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 plugins_exports = {};
+__export(plugins_exports, {
+  BuiltInPluginConfigSchema: () => import_schemas.BuiltInPluginConfigSchema,
+  ContentPolicyPlugin: () => import_content_policy.ContentPolicyPlugin,
+  CustomPluginConfigSchema: () => import_schemas.CustomPluginConfigSchema,
+  PluginErrorCode: () => import_error_codes.PluginErrorCode,
+  PluginManager: () => import_manager.PluginManager,
+  PluginsConfigSchema: () => import_schemas.PluginsConfigSchema,
+  ResponseSanitizerPlugin: () => import_response_sanitizer.ResponseSanitizerPlugin,
+  loadPluginModule: () => import_loader.loadPluginModule,
+  registerBuiltInPlugins: () => import_builtins.registerBuiltInPlugins,
+  resolvePluginPath: () => import_loader.resolvePluginPath,
+  validatePluginShape: () => import_loader.validatePluginShape
+});
+module.exports = __toCommonJS(plugins_exports);
+var import_manager = require("./manager.js");
+var import_schemas = require("./schemas.js");
+var import_error_codes = require("./error-codes.js");
+var import_loader = require("./loader.js");
+var import_builtins = require("./registrations/builtins.js");
+var import_content_policy = require("./builtins/content-policy.js");
+var import_response_sanitizer = require("./builtins/response-sanitizer.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BuiltInPluginConfigSchema,
+  ContentPolicyPlugin,
+  CustomPluginConfigSchema,
+  PluginErrorCode,
+  PluginManager,
+  PluginsConfigSchema,
+  ResponseSanitizerPlugin,
+  loadPluginModule,
+  registerBuiltInPlugins,
+  resolvePluginPath,
+  validatePluginShape
+});

package/dist/plugins/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Plugin System
+ *
+ * Unified plugin architecture for extending agent behavior at key extension points.
+ * Replaces the hooks system from PR #385 with a more flexible plugin model.
+ */
+export type { DextoPlugin, PluginConfig, PluginExecutionContext, PluginResult, PluginNotice, ExtensionPoint, BeforeLLMRequestPayload, BeforeToolCallPayload, AfterToolResultPayload, BeforeResponsePayload, } from './types.js';
+export { PluginManager } from './manager.js';
+export type { PluginManagerOptions, ExecutionContextOptions } from './manager.js';
+export { CustomPluginConfigSchema, BuiltInPluginConfigSchema, PluginsConfigSchema, } from './schemas.js';
+export type { PluginsConfig, ValidatedPluginsConfig } from './schemas.js';
+export { PluginErrorCode } from './error-codes.js';
+export { loadPluginModule, resolvePluginPath, validatePluginShape } from './loader.js';
+export { registerBuiltInPlugins } from './registrations/builtins.js';
+export { ContentPolicyPlugin } from './builtins/content-policy.js';
+export type { ContentPolicyConfig } from './builtins/content-policy.js';
+export { ResponseSanitizerPlugin } from './builtins/response-sanitizer.js';
+export type { ResponseSanitizerConfig } from './builtins/response-sanitizer.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EACR,WAAW,EACX,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,GACxB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAGlF,OAAO,EACH,wBAAwB,EACxB,yBAAyB,EACzB,mBAAmB,GACtB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAG1E,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvF,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,YAAY,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,YAAY,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/plugins/index.js

@@ -0,0 +1,25 @@
+import "../chunk-C6A6W6XS.js";
+import { PluginManager } from "./manager.js";
+import {
+  CustomPluginConfigSchema,
+  BuiltInPluginConfigSchema,
+  PluginsConfigSchema
+} from "./schemas.js";
+import { PluginErrorCode } from "./error-codes.js";
+import { loadPluginModule, resolvePluginPath, validatePluginShape } from "./loader.js";
+import { registerBuiltInPlugins } from "./registrations/builtins.js";
+import { ContentPolicyPlugin } from "./builtins/content-policy.js";
+import { ResponseSanitizerPlugin } from "./builtins/response-sanitizer.js";
+export {
+  BuiltInPluginConfigSchema,
+  ContentPolicyPlugin,
+  CustomPluginConfigSchema,
+  PluginErrorCode,
+  PluginManager,
+  PluginsConfigSchema,
+  ResponseSanitizerPlugin,
+  loadPluginModule,
+  registerBuiltInPlugins,
+  resolvePluginPath,
+  validatePluginShape
+};

package/dist/plugins/loader.cjs

@@ -0,0 +1,151 @@
+"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 loader_exports = {};
+__export(loader_exports, {
+  loadPluginModule: () => loadPluginModule,
+  resolvePluginPath: () => resolvePluginPath,
+  validatePluginShape: () => validatePluginShape
+});
+module.exports = __toCommonJS(loader_exports);
+var import_path = require("path");
+var import_url = require("url");
+var import_errors = require("../errors/index.js");
+var import_error_codes = require("./error-codes.js");
+const import_meta = {};
+function validatePluginShape(PluginClass, pluginName) {
+  if (typeof PluginClass !== "function" || !PluginClass.prototype) {
+    throw new import_errors.DextoRuntimeError(
+      import_error_codes.PluginErrorCode.PLUGIN_INVALID_SHAPE,
+      import_errors.ErrorScope.PLUGIN,
+      import_errors.ErrorType.USER,
+      `Plugin '${pluginName}' default export must be a class or constructor function`
+    );
+  }
+  const proto = PluginClass.prototype;
+  const extensionPoints = [
+    "beforeLLMRequest",
+    "beforeToolCall",
+    "afterToolResult",
+    "beforeResponse"
+  ];
+  const hasExtensionPoint = extensionPoints.some((point) => typeof proto[point] === "function");
+  if (!hasExtensionPoint) {
+    throw new import_errors.DextoRuntimeError(
+      import_error_codes.PluginErrorCode.PLUGIN_INVALID_SHAPE,
+      import_errors.ErrorScope.PLUGIN,
+      import_errors.ErrorType.USER,
+      `Plugin '${pluginName}' must implement at least one extension point method`,
+      { availableExtensionPoints: extensionPoints }
+    );
+  }
+  if ("initialize" in proto && typeof proto.initialize !== "function") {
+    throw new import_errors.DextoRuntimeError(
+      import_error_codes.PluginErrorCode.PLUGIN_INVALID_SHAPE,
+      import_errors.ErrorScope.PLUGIN,
+      import_errors.ErrorType.USER,
+      `Plugin '${pluginName}' initialize property must be a function (found ${typeof proto.initialize})`
+    );
+  }
+  if ("cleanup" in proto && typeof proto.cleanup !== "function") {
+    throw new import_errors.DextoRuntimeError(
+      import_error_codes.PluginErrorCode.PLUGIN_INVALID_SHAPE,
+      import_errors.ErrorScope.PLUGIN,
+      import_errors.ErrorType.USER,
+      `Plugin '${pluginName}' cleanup property must be a function (found ${typeof proto.cleanup})`
+    );
+  }
+}
+function resolvePluginPath(modulePath, configDir) {
+  if (!(0, import_path.isAbsolute)(modulePath)) {
+    throw new import_errors.DextoRuntimeError(
+      import_error_codes.PluginErrorCode.PLUGIN_CONFIGURATION_INVALID,
+      import_errors.ErrorScope.PLUGIN,
+      import_errors.ErrorType.USER,
+      "Plugin module path must be absolute (got '" + modulePath + "'). Use ${{dexto.agent_dir}} template variable for agent-relative paths.",
+      {
+        modulePath,
+        configDir,
+        hint: 'Example: module: "${{dexto.agent_dir}}/plugins/my-plugin.ts"'
+      }
+    );
+  }
+  return modulePath;
+}
+async function loadPluginModule(modulePath, pluginName) {
+  try {
+    let pluginModule;
+    if (modulePath.endsWith(".ts") || modulePath.endsWith(".tsx")) {
+      if (typeof process === "undefined" || !process.versions?.node) {
+        throw new import_errors.DextoRuntimeError(
+          import_error_codes.PluginErrorCode.PLUGIN_LOAD_FAILED,
+          import_errors.ErrorScope.PLUGIN,
+          import_errors.ErrorType.SYSTEM,
+          `Cannot load TypeScript plugin '${pluginName}' in browser environment. Plugins with .ts extension require Node.js runtime.`,
+          { modulePath, pluginName }
+        );
+      }
+      const tsxPackage = "tsx/esm/api";
+      const tsx = await import(
+        /* webpackIgnore: true */
+        tsxPackage
+      );
+      const moduleUrl = (0, import_url.pathToFileURL)(modulePath).href;
+      pluginModule = await tsx.tsImport(moduleUrl, import_meta.url);
+    } else {
+      const moduleUrl = (0, import_url.pathToFileURL)(modulePath).href;
+      pluginModule = await import(
+        /* webpackIgnore: true */
+        moduleUrl
+      );
+    }
+    const PluginClass = pluginModule.default;
+    if (!PluginClass) {
+      throw new import_errors.DextoRuntimeError(
+        import_error_codes.PluginErrorCode.PLUGIN_INVALID_SHAPE,
+        import_errors.ErrorScope.PLUGIN,
+        import_errors.ErrorType.USER,
+        `Plugin '${pluginName}' at '${modulePath}' has no default export. Ensure your plugin exports a class as default.`,
+        { modulePath, pluginName }
+      );
+    }
+    validatePluginShape(PluginClass, pluginName);
+    return PluginClass;
+  } catch (error) {
+    if (error instanceof import_errors.DextoRuntimeError) {
+      throw error;
+    }
+    throw new import_errors.DextoRuntimeError(
+      import_error_codes.PluginErrorCode.PLUGIN_LOAD_FAILED,
+      import_errors.ErrorScope.PLUGIN,
+      import_errors.ErrorType.SYSTEM,
+      `Failed to load plugin '${pluginName}' from '${modulePath}': ${error instanceof Error ? error.message : String(error)}`,
+      {
+        modulePath,
+        pluginName,
+        originalError: error instanceof Error ? error.message : String(error)
+      }
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  loadPluginModule,
+  resolvePluginPath,
+  validatePluginShape
+});

package/dist/plugins/loader.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Validate that a loaded plugin implements the DextoPlugin interface correctly
+ * Performs runtime checks that complement TypeScript's compile-time type checking
+ *
+ * @param PluginClass - The plugin class constructor
+ * @param pluginName - Name for error messages
+ * @throws {DextoRuntimeError} If validation fails
+ */
+export declare function validatePluginShape(PluginClass: any, pluginName: string): void;
+/**
+ * Resolve and validate plugin module path
+ * Ensures path is absolute after template variable expansion
+ *
+ * @param modulePath - Path from config (after template expansion)
+ * @param configDir - Directory containing agent config (for validation context)
+ * @returns Resolved absolute path
+ * @throws {DextoRuntimeError} If path is not absolute
+ */
+export declare function resolvePluginPath(modulePath: string, configDir: string): string;
+/**
+ * Load a plugin from a module path
+ * Supports both .ts (via tsx) and .js files
+ *
+ * @param modulePath - Absolute path to plugin module
+ * @param pluginName - Name for error messages
+ * @returns Plugin class constructor
+ * @throws {DextoRuntimeError} If loading or validation fails
+ */
+export declare function loadPluginModule(modulePath: string, pluginName: string): Promise<any>;
+//# sourceMappingURL=loader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAqD9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAoB/E;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAiF3F"}

package/dist/plugins/loader.js

@@ -0,0 +1,125 @@
+import "../chunk-C6A6W6XS.js";
+import { isAbsolute } from "path";
+import { pathToFileURL } from "url";
+import { DextoRuntimeError, ErrorScope, ErrorType } from "../errors/index.js";
+import { PluginErrorCode } from "./error-codes.js";
+function validatePluginShape(PluginClass, pluginName) {
+  if (typeof PluginClass !== "function" || !PluginClass.prototype) {
+    throw new DextoRuntimeError(
+      PluginErrorCode.PLUGIN_INVALID_SHAPE,
+      ErrorScope.PLUGIN,
+      ErrorType.USER,
+      `Plugin '${pluginName}' default export must be a class or constructor function`
+    );
+  }
+  const proto = PluginClass.prototype;
+  const extensionPoints = [
+    "beforeLLMRequest",
+    "beforeToolCall",
+    "afterToolResult",
+    "beforeResponse"
+  ];
+  const hasExtensionPoint = extensionPoints.some((point) => typeof proto[point] === "function");
+  if (!hasExtensionPoint) {
+    throw new DextoRuntimeError(
+      PluginErrorCode.PLUGIN_INVALID_SHAPE,
+      ErrorScope.PLUGIN,
+      ErrorType.USER,
+      `Plugin '${pluginName}' must implement at least one extension point method`,
+      { availableExtensionPoints: extensionPoints }
+    );
+  }
+  if ("initialize" in proto && typeof proto.initialize !== "function") {
+    throw new DextoRuntimeError(
+      PluginErrorCode.PLUGIN_INVALID_SHAPE,
+      ErrorScope.PLUGIN,
+      ErrorType.USER,
+      `Plugin '${pluginName}' initialize property must be a function (found ${typeof proto.initialize})`
+    );
+  }
+  if ("cleanup" in proto && typeof proto.cleanup !== "function") {
+    throw new DextoRuntimeError(
+      PluginErrorCode.PLUGIN_INVALID_SHAPE,
+      ErrorScope.PLUGIN,
+      ErrorType.USER,
+      `Plugin '${pluginName}' cleanup property must be a function (found ${typeof proto.cleanup})`
+    );
+  }
+}
+function resolvePluginPath(modulePath, configDir) {
+  if (!isAbsolute(modulePath)) {
+    throw new DextoRuntimeError(
+      PluginErrorCode.PLUGIN_CONFIGURATION_INVALID,
+      ErrorScope.PLUGIN,
+      ErrorType.USER,
+      "Plugin module path must be absolute (got '" + modulePath + "'). Use ${{dexto.agent_dir}} template variable for agent-relative paths.",
+      {
+        modulePath,
+        configDir,
+        hint: 'Example: module: "${{dexto.agent_dir}}/plugins/my-plugin.ts"'
+      }
+    );
+  }
+  return modulePath;
+}
+async function loadPluginModule(modulePath, pluginName) {
+  try {
+    let pluginModule;
+    if (modulePath.endsWith(".ts") || modulePath.endsWith(".tsx")) {
+      if (typeof process === "undefined" || !process.versions?.node) {
+        throw new DextoRuntimeError(
+          PluginErrorCode.PLUGIN_LOAD_FAILED,
+          ErrorScope.PLUGIN,
+          ErrorType.SYSTEM,
+          `Cannot load TypeScript plugin '${pluginName}' in browser environment. Plugins with .ts extension require Node.js runtime.`,
+          { modulePath, pluginName }
+        );
+      }
+      const tsxPackage = "tsx/esm/api";
+      const tsx = await import(
+        /* webpackIgnore: true */
+        tsxPackage
+      );
+      const moduleUrl = pathToFileURL(modulePath).href;
+      pluginModule = await tsx.tsImport(moduleUrl, import.meta.url);
+    } else {
+      const moduleUrl = pathToFileURL(modulePath).href;
+      pluginModule = await import(
+        /* webpackIgnore: true */
+        moduleUrl
+      );
+    }
+    const PluginClass = pluginModule.default;
+    if (!PluginClass) {
+      throw new DextoRuntimeError(
+        PluginErrorCode.PLUGIN_INVALID_SHAPE,
+        ErrorScope.PLUGIN,
+        ErrorType.USER,
+        `Plugin '${pluginName}' at '${modulePath}' has no default export. Ensure your plugin exports a class as default.`,
+        { modulePath, pluginName }
+      );
+    }
+    validatePluginShape(PluginClass, pluginName);
+    return PluginClass;
+  } catch (error) {
+    if (error instanceof DextoRuntimeError) {
+      throw error;
+    }
+    throw new DextoRuntimeError(
+      PluginErrorCode.PLUGIN_LOAD_FAILED,
+      ErrorScope.PLUGIN,
+      ErrorType.SYSTEM,
+      `Failed to load plugin '${pluginName}' from '${modulePath}': ${error instanceof Error ? error.message : String(error)}`,
+      {
+        modulePath,
+        pluginName,
+        originalError: error instanceof Error ? error.message : String(error)
+      }
+    );
+  }
+}
+export {
+  loadPluginModule,
+  resolvePluginPath,
+  validatePluginShape
+};