@dexto/core 1.4.0 → 1.5.0

package/dist/plugins/registry.d.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import type { DextoPlugin } from './types.js';
+import { BaseRegistry } from '../providers/base-registry.js';
+/**
+ * Context passed to plugin providers when creating plugin instances.
+ * Provides access to configuration and optional services.
+ */
+export interface PluginCreationContext {
+    /** Plugin-specific configuration from YAML */
+    config: Record<string, any>;
+    /** Whether this plugin should block execution on errors */
+    blocking: boolean;
+    /** Execution priority (lower runs first) */
+    priority: number;
+}
+/**
+ * Plugin provider interface.
+ * Allows external code to register plugin providers that create plugin instances.
+ * Follows the same pattern as BlobStoreProvider, CompressionProvider, and CustomToolProvider.
+ *
+ * @template TType - The provider type discriminator (must match config.type)
+ * @template TConfig - The provider configuration type (must include { type: TType })
+ */
+export interface PluginProvider<TType extends string = string, TConfig extends {
+    type: TType;
+} = any> {
+    /** Unique type identifier matching the discriminator in config */
+    type: TType;
+    /** Zod schema for runtime validation of provider configuration */
+    configSchema: z.ZodType<TConfig, any, any>;
+    /**
+     * Factory function to create a plugin instance from validated configuration
+     * @param config - Validated configuration matching configSchema
+     * @param context - Plugin creation context with priority and blocking settings
+     * @returns A DextoPlugin instance
+     */
+    create(config: TConfig, context: PluginCreationContext): DextoPlugin;
+    /** Optional metadata for display and categorization */
+    metadata?: {
+        displayName: string;
+        description: string;
+        /** Which extension points this plugin implements */
+        extensionPoints?: Array<'beforeLLMRequest' | 'beforeToolCall' | 'afterToolResult' | 'beforeResponse'>;
+        /** Category for grouping (e.g., 'security', 'logging', 'integration') */
+        category?: string;
+    };
+}
+/**
+ * Registry for plugin providers.
+ * Follows the same pattern as BlobStoreRegistry, CompressionRegistry, and CustomToolRegistry.
+ *
+ * Plugin providers can be registered from external code (CLI, apps, distributions)
+ * and are validated at runtime using their Zod schemas.
+ *
+ * Extends BaseRegistry for common registry functionality.
+ *
+ * @example
+ * ```typescript
+ * // Define a plugin provider
+ * const myPluginProvider: PluginProvider<'my-plugin', MyPluginConfig> = {
+ *     type: 'my-plugin',
+ *     configSchema: MyPluginConfigSchema,
+ *     create(config, context) {
+ *         return new MyPlugin(config, context);
+ *     },
+ *     metadata: {
+ *         displayName: 'My Plugin',
+ *         description: 'Does something useful',
+ *         extensionPoints: ['beforeLLMRequest'],
+ *         category: 'custom',
+ *     },
+ * };
+ *
+ * // Register in dexto.config.ts
+ * import { pluginRegistry } from '@dexto/core';
+ * pluginRegistry.register(myPluginProvider);
+ *
+ * // Use in agent YAML
+ * plugins:
+ *   registry:
+ *     - type: my-plugin
+ *       priority: 50
+ *       blocking: false
+ *       config:
+ *         key: value
+ * ```
+ */
+export declare class PluginRegistry extends BaseRegistry<PluginProvider> {
+    constructor();
+    /**
+     * Get all registered plugin providers.
+     * Alias for getAll() to match other registry patterns.
+     */
+    getProviders(): PluginProvider[];
+}
+/**
+ * Global singleton instance of the plugin registry.
+ * Plugin providers should be registered at application startup.
+ */
+export declare const pluginRegistry: PluginRegistry;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/plugins/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,OAAO,EAAE,YAAY,EAA6B,MAAM,+BAA+B,CAAC;AAExF;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IAClC,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAC3B,KAAK,SAAS,MAAM,GAAG,MAAM,EAC7B,OAAO,SAAS;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GAAG,GAAG;IAErC,kEAAkE;IAClE,IAAI,EAAE,KAAK,CAAC;IAEZ,kEAAkE;IAClE,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,GAAG,WAAW,CAAC;IAErE,uDAAuD;IACvD,QAAQ,CAAC,EAAE;QACP,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,oDAAoD;QACpD,eAAe,CAAC,EAAE,KAAK,CACnB,kBAAkB,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,gBAAgB,CAC/E,CAAC;QACF,yEAAyE;QACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACL;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,cAAe,SAAQ,YAAY,CAAC,cAAc,CAAC;;IAK5D;;;OAGG;IACH,YAAY,IAAI,cAAc,EAAE;CAGnC;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,gBAAuB,CAAC"}

package/dist/plugins/registry.js

@@ -0,0 +1,39 @@
+import "../chunk-PTJYTZNU.js";
+import { DextoRuntimeError, ErrorScope, ErrorType } from "../errors/index.js";
+import { PluginErrorCode } from "./error-codes.js";
+import { BaseRegistry } from "../providers/base-registry.js";
+const pluginRegistryErrorFactory = {
+  alreadyRegistered: (type) => new DextoRuntimeError(
+    PluginErrorCode.PLUGIN_PROVIDER_ALREADY_REGISTERED,
+    ErrorScope.PLUGIN,
+    ErrorType.USER,
+    `Plugin provider '${type}' is already registered`,
+    { type },
+    "Each plugin provider type can only be registered once"
+  ),
+  notFound: (type, availableTypes) => new DextoRuntimeError(
+    PluginErrorCode.PLUGIN_PROVIDER_NOT_FOUND,
+    ErrorScope.PLUGIN,
+    ErrorType.USER,
+    `Plugin provider '${type}' not found`,
+    { type, available: availableTypes },
+    `Available plugin providers: ${availableTypes.join(", ") || "none"}`
+  )
+};
+class PluginRegistry extends 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();
+export {
+  PluginRegistry,
+  pluginRegistry
+};

package/dist/plugins/schemas.cjs

@@ -20,10 +20,18 @@ var schemas_exports = {};
 __export(schemas_exports, {
   BuiltInPluginConfigSchema: () => BuiltInPluginConfigSchema,
   CustomPluginConfigSchema: () => CustomPluginConfigSchema,
-  PluginsConfigSchema: () => PluginsConfigSchema
+  PluginsConfigSchema: () => PluginsConfigSchema,
+  RegistryPluginConfigSchema: () => RegistryPluginConfigSchema
 });
 module.exports = __toCommonJS(schemas_exports);
 var import_zod = require("zod");
+const RegistryPluginConfigSchema = import_zod.z.object({
+  type: import_zod.z.string().describe("Plugin provider type (must be registered in pluginRegistry)"),
+  enabled: import_zod.z.boolean().default(true).describe("Whether this plugin is enabled"),
+  blocking: import_zod.z.boolean().describe("If true, plugin errors will halt execution"),
+  priority: import_zod.z.number().int().describe("Execution priority (lower runs first)"),
+  config: import_zod.z.record(import_zod.z.any()).optional().describe("Plugin-specific configuration")
+}).strict();
 const CustomPluginConfigSchema = import_zod.z.object({
   name: import_zod.z.string().describe("Unique name for the plugin"),
   module: import_zod.z.string().describe(
@@ -48,14 +56,18 @@ const PluginsConfigSchema = import_zod.z.object({
   responseSanitizer: BuiltInPluginConfigSchema.optional().describe(
     "Response sanitizer plugin for output sanitization"
   ),
-  // Custom plugins - array of plugin configurations
-  custom: import_zod.z.array(CustomPluginConfigSchema).default([]).describe("Array of custom plugin configurations")
+  // Custom plugins - array of plugin configurations (loaded from file paths)
+  custom: import_zod.z.array(CustomPluginConfigSchema).default([]).describe("Array of custom plugin configurations (loaded from file paths)"),
+  // Registry plugins - array of plugin configurations (loaded from pluginRegistry)
+  registry: import_zod.z.array(RegistryPluginConfigSchema).default([]).describe("Array of registry plugin configurations (loaded from pluginRegistry)")
 }).strict().default({
-  custom: []
+  custom: [],
+  registry: []
 }).describe("Plugin system configuration");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BuiltInPluginConfigSchema,
   CustomPluginConfigSchema,
-  PluginsConfigSchema
+  PluginsConfigSchema,
+  RegistryPluginConfigSchema
 });

package/dist/plugins/schemas.d.ts

@@ -1,4 +1,28 @@
 import { z } from 'zod';
+/**
+ * Schema for registry-based plugin configuration.
+ * These plugins are loaded from the pluginRegistry (programmatically registered).
+ */
+export declare const RegistryPluginConfigSchema: z.ZodObject<{
+    type: z.ZodString;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    blocking: z.ZodBoolean;
+    priority: z.ZodNumber;
+    config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    enabled: boolean;
+    priority: number;
+    blocking: boolean;
+    config?: Record<string, any> | undefined;
+}, {
+    type: string;
+    priority: number;
+    blocking: boolean;
+    config?: Record<string, any> | undefined;
+    enabled?: boolean | undefined;
+}>;
+export type RegistryPluginConfig = z.output<typeof RegistryPluginConfigSchema>;
 /**
  * Schema for custom plugin configuration (loaded from file paths)
  */
@@ -13,14 +37,14 @@ export declare const CustomPluginConfigSchema: z.ZodObject<{
     name: string;
     enabled: boolean;
     priority: number;
-    module: string;
     blocking: boolean;
+    module: string;
     config?: Record<string, any> | undefined;
 }, {
     name: string;
     priority: number;
-    module: string;
     blocking: boolean;
+    module: string;
     config?: Record<string, any> | undefined;
     enabled?: boolean | undefined;
 }>;
@@ -43,7 +67,7 @@ export declare const BuiltInPluginConfigSchema: z.ZodObject<{
 }, z.ZodTypeAny, "passthrough">>;
 /**
  * Main plugins configuration schema
- * Supports both built-in plugins (by name) and custom plugins (with module paths)
+ * Supports built-in plugins (by name), custom plugins (file paths), and registry plugins (programmatic)
  */
 export declare const PluginsConfigSchema: z.ZodDefault<z.ZodObject<{
     contentPolicy: z.ZodOptional<z.ZodObject<{
@@ -83,13 +107,32 @@ export declare const PluginsConfigSchema: z.ZodDefault<z.ZodObject<{
         name: string;
         enabled: boolean;
         priority: number;
-        module: string;
         blocking: boolean;
+        module: string;
         config?: Record<string, any> | undefined;
     }, {
         name: string;
         priority: number;
+        blocking: boolean;
         module: string;
+        config?: Record<string, any> | undefined;
+        enabled?: boolean | undefined;
+    }>, "many">>;
+    registry: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        blocking: z.ZodBoolean;
+        priority: z.ZodNumber;
+        config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        enabled: boolean;
+        priority: number;
+        blocking: boolean;
+        config?: Record<string, any> | undefined;
+    }, {
+        type: string;
+        priority: number;
         blocking: boolean;
         config?: Record<string, any> | undefined;
         enabled?: boolean | undefined;
@@ -99,7 +142,14 @@ export declare const PluginsConfigSchema: z.ZodDefault<z.ZodObject<{
         name: string;
         enabled: boolean;
         priority: number;
+        blocking: boolean;
         module: string;
+        config?: Record<string, any> | undefined;
+    }[];
+    registry: {
+        type: string;
+        enabled: boolean;
+        priority: number;
         blocking: boolean;
         config?: Record<string, any> | undefined;
     }[];
@@ -117,8 +167,8 @@ export declare const PluginsConfigSchema: z.ZodDefault<z.ZodObject<{
     custom?: {
         name: string;
         priority: number;
-        module: string;
         blocking: boolean;
+        module: string;
         config?: Record<string, any> | undefined;
         enabled?: boolean | undefined;
     }[] | undefined;
@@ -132,6 +182,13 @@ export declare const PluginsConfigSchema: z.ZodDefault<z.ZodObject<{
         blocking: z.ZodOptional<z.ZodBoolean>;
         enabled: z.ZodDefault<z.ZodBoolean>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
+    registry?: {
+        type: string;
+        priority: number;
+        blocking: boolean;
+        config?: Record<string, any> | undefined;
+        enabled?: boolean | undefined;
+    }[] | undefined;
 }>>;
 export type PluginsConfig = z.input<typeof PluginsConfigSchema>;
 export type ValidatedPluginsConfig = z.output<typeof PluginsConfigSchema>;

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

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/plugins/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;EAaxB,CAAC;AAEd;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;gCAQc,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoBY,CAAC;AAE7C,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/plugins/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;EAQ1B,CAAC;AAEd,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;EAaxB,CAAC;AAEd;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;gCAQc,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BY,CAAC;AAE7C,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAChE,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/plugins/schemas.js

@@ -1,5 +1,12 @@
 import "../chunk-PTJYTZNU.js";
 import { z } from "zod";
+const RegistryPluginConfigSchema = z.object({
+  type: z.string().describe("Plugin provider type (must be registered in pluginRegistry)"),
+  enabled: z.boolean().default(true).describe("Whether this plugin is enabled"),
+  blocking: z.boolean().describe("If true, plugin errors will halt execution"),
+  priority: z.number().int().describe("Execution priority (lower runs first)"),
+  config: z.record(z.any()).optional().describe("Plugin-specific configuration")
+}).strict();
 const CustomPluginConfigSchema = z.object({
   name: z.string().describe("Unique name for the plugin"),
   module: z.string().describe(
@@ -24,13 +31,17 @@ const PluginsConfigSchema = z.object({
   responseSanitizer: BuiltInPluginConfigSchema.optional().describe(
     "Response sanitizer plugin for output sanitization"
   ),
-  // Custom plugins - array of plugin configurations
-  custom: z.array(CustomPluginConfigSchema).default([]).describe("Array of custom plugin configurations")
+  // Custom plugins - array of plugin configurations (loaded from file paths)
+  custom: z.array(CustomPluginConfigSchema).default([]).describe("Array of custom plugin configurations (loaded from file paths)"),
+  // Registry plugins - array of plugin configurations (loaded from pluginRegistry)
+  registry: z.array(RegistryPluginConfigSchema).default([]).describe("Array of registry plugin configurations (loaded from pluginRegistry)")
 }).strict().default({
-  custom: []
+  custom: [],
+  registry: []
 }).describe("Plugin system configuration");
 export {
   BuiltInPluginConfigSchema,
   CustomPluginConfigSchema,
-  PluginsConfigSchema
+  PluginsConfigSchema,
+  RegistryPluginConfigSchema
 };

package/dist/providers/base-registry.cjs

@@ -0,0 +1,147 @@
+"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 base_registry_exports = {};
+__export(base_registry_exports, {
+  BaseRegistry: () => BaseRegistry,
+  defaultErrorFactory: () => defaultErrorFactory
+});
+module.exports = __toCommonJS(base_registry_exports);
+var import_zod = require("zod");
+const defaultErrorFactory = {
+  alreadyRegistered: (type) => new Error(`Provider '${type}' is already registered`),
+  notFound: (type, availableTypes) => new Error(
+    `Provider '${type}' not found. Available: ${availableTypes.join(", ") || "none"}`
+  )
+};
+class BaseRegistry {
+  providers = /* @__PURE__ */ new Map();
+  errorFactory;
+  /**
+   * Create a new registry instance.
+   *
+   * @param errorFactory - Optional custom error factory for registry errors.
+   *                       If not provided, uses default Error instances.
+   */
+  constructor(errorFactory = defaultErrorFactory) {
+    this.errorFactory = errorFactory;
+  }
+  /**
+   * Register a provider.
+   *
+   * @param provider - The provider to register
+   * @throws Error if a provider with the same type is already registered
+   */
+  register(provider) {
+    if (this.providers.has(provider.type)) {
+      throw this.errorFactory.alreadyRegistered(provider.type);
+    }
+    this.providers.set(provider.type, provider);
+  }
+  /**
+   * Unregister a provider.
+   *
+   * @param type - The provider type to unregister
+   * @returns true if the provider was unregistered, false if it wasn't registered
+   */
+  unregister(type) {
+    return this.providers.delete(type);
+  }
+  /**
+   * Get a registered provider by type.
+   *
+   * @param type - The provider type identifier
+   * @returns The provider if found, undefined otherwise
+   */
+  get(type) {
+    return this.providers.get(type);
+  }
+  /**
+   * Check if a provider is registered.
+   *
+   * @param type - The provider type identifier
+   * @returns true if registered, false otherwise
+   */
+  has(type) {
+    return this.providers.has(type);
+  }
+  /**
+   * Get all registered provider types.
+   *
+   * @returns Array of provider type identifiers
+   */
+  getTypes() {
+    return Array.from(this.providers.keys());
+  }
+  /**
+   * Get all registered providers.
+   *
+   * @returns Array of providers
+   */
+  getAll() {
+    return Array.from(this.providers.values());
+  }
+  /**
+   * Get the number of registered providers.
+   *
+   * @returns Count of registered providers
+   */
+  get size() {
+    return this.providers.size;
+  }
+  /**
+   * Clear all registered providers.
+   * Primarily useful for testing.
+   */
+  clear() {
+    this.providers.clear();
+  }
+  /**
+   * Validate a configuration against a provider's schema.
+   *
+   * This method is only available for registries with providers that have
+   * a configSchema property. It:
+   * 1. Extracts the 'type' field to identify the provider
+   * 2. Looks up the provider in the registry
+   * 3. Validates the full config against the provider's schema
+   * 4. Returns the validated configuration
+   *
+   * @param config - Raw configuration object with a 'type' field
+   * @returns Validated configuration object
+   * @throws Error if type is missing, provider not found, or validation fails
+   */
+  validateConfig(config) {
+    const typeSchema = import_zod.z.object({ type: import_zod.z.string() }).passthrough();
+    const parsed = typeSchema.parse(config);
+    const provider = this.providers.get(parsed.type);
+    if (!provider) {
+      throw this.errorFactory.notFound(parsed.type, this.getTypes());
+    }
+    if (!("configSchema" in provider) || !provider.configSchema) {
+      throw new Error(
+        `Provider '${parsed.type}' does not support config validation (no configSchema)`
+      );
+    }
+    return provider.configSchema.parse(config);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseRegistry,
+  defaultErrorFactory
+});

package/dist/providers/base-registry.d.ts

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+/**
+ * Base provider interface - all providers must have a type identifier.
+ */
+export interface BaseProvider {
+    /** Unique type identifier for this provider */
+    type: string;
+}
+/**
+ * Provider with config schema - for providers that support validateConfig.
+ */
+export interface ConfigurableProvider extends BaseProvider {
+    /** Zod schema for validating provider configuration */
+    configSchema: z.ZodType<any, any, any>;
+}
+/**
+ * Error factory interface for customizing registry errors.
+ * Each registry can provide its own error implementations.
+ */
+export interface RegistryErrorFactory {
+    /** Called when attempting to register a provider that already exists */
+    alreadyRegistered(type: string): Error;
+    /** Called when looking up a provider that doesn't exist (for validateConfig) */
+    notFound(type: string, availableTypes: string[]): Error;
+}
+/**
+ * Default error factory that throws plain Error instances.
+ * Used when no custom error factory is provided.
+ */
+export declare const defaultErrorFactory: RegistryErrorFactory;
+/**
+ * Generic base registry for provider patterns.
+ *
+ * This class provides common registry functionality used across Dexto's
+ * provider system (blob storage, compression, custom tools, etc.).
+ *
+ * Features:
+ * - Type-safe provider registration and retrieval
+ * - Duplicate registration prevention
+ * - Customizable error handling via error factory
+ * - Optional config validation for providers with schemas
+ *
+ * @template TProvider - The provider type (must extend BaseProvider)
+ *
+ * @example
+ * ```typescript
+ * // Define your provider interface
+ * interface MyProvider extends BaseProvider {
+ *   type: string;
+ *   configSchema: z.ZodType<any>;
+ *   create(config: any): MyInstance;
+ * }
+ *
+ * // Create a registry
+ * class MyRegistry extends BaseRegistry<MyProvider> {
+ *   constructor() {
+ *     super({
+ *       alreadyRegistered: (type) => new MyError(`Provider ${type} exists`),
+ *       notFound: (type, available) => new MyError(`Unknown: ${type}`),
+ *     });
+ *   }
+ * }
+ *
+ * // Use the registry
+ * const registry = new MyRegistry();
+ * registry.register(myProvider);
+ * const provider = registry.get('my-type');
+ * ```
+ */
+export declare class BaseRegistry<TProvider extends BaseProvider> {
+    protected providers: Map<string, TProvider>;
+    protected errorFactory: RegistryErrorFactory;
+    /**
+     * Create a new registry instance.
+     *
+     * @param errorFactory - Optional custom error factory for registry errors.
+     *                       If not provided, uses default Error instances.
+     */
+    constructor(errorFactory?: RegistryErrorFactory);
+    /**
+     * Register a provider.
+     *
+     * @param provider - The provider to register
+     * @throws Error if a provider with the same type is already registered
+     */
+    register(provider: TProvider): void;
+    /**
+     * Unregister a provider.
+     *
+     * @param type - The provider type to unregister
+     * @returns true if the provider was unregistered, false if it wasn't registered
+     */
+    unregister(type: string): boolean;
+    /**
+     * Get a registered provider by type.
+     *
+     * @param type - The provider type identifier
+     * @returns The provider if found, undefined otherwise
+     */
+    get(type: string): TProvider | undefined;
+    /**
+     * Check if a provider is registered.
+     *
+     * @param type - The provider type identifier
+     * @returns true if registered, false otherwise
+     */
+    has(type: string): boolean;
+    /**
+     * Get all registered provider types.
+     *
+     * @returns Array of provider type identifiers
+     */
+    getTypes(): string[];
+    /**
+     * Get all registered providers.
+     *
+     * @returns Array of providers
+     */
+    getAll(): TProvider[];
+    /**
+     * Get the number of registered providers.
+     *
+     * @returns Count of registered providers
+     */
+    get size(): number;
+    /**
+     * Clear all registered providers.
+     * Primarily useful for testing.
+     */
+    clear(): void;
+    /**
+     * Validate a configuration against a provider's schema.
+     *
+     * This method is only available for registries with providers that have
+     * a configSchema property. It:
+     * 1. Extracts the 'type' field to identify the provider
+     * 2. Looks up the provider in the registry
+     * 3. Validates the full config against the provider's schema
+     * 4. Returns the validated configuration
+     *
+     * @param config - Raw configuration object with a 'type' field
+     * @returns Validated configuration object
+     * @throws Error if type is missing, provider not found, or validation fails
+     */
+    validateConfig(config: unknown): any;
+}
+//# sourceMappingURL=base-registry.d.ts.map

package/dist/providers/base-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-registry.d.ts","sourceRoot":"","sources":["../../src/providers/base-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACtD,uDAAuD;IACvD,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACjC,wEAAwE;IACxE,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACvC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;CAC3D;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,oBAMjC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,YAAY,CAAC,SAAS,SAAS,YAAY;IACpD,SAAS,CAAC,SAAS,yBAAgC;IACnD,SAAS,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAE7C;;;;;OAKG;gBACS,YAAY,GAAE,oBAA0C;IAIpE;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI;IAOnC;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIxC;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;;OAIG;IACH,QAAQ,IAAI,MAAM,EAAE;IAIpB;;;;OAIG;IACH,MAAM,IAAI,SAAS,EAAE;IAIrB;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,GAAG;CAqBvC"}