@snap-agent/core 0.1.0 → 0.1.2

package/dist/index.js

@@ -7327,12 +7327,16 @@ __export(index_exports, {
   Models: () => Models,
   MongoDBStorage: () => MongoDBStorage,
   PluginManager: () => PluginManager,
+  PluginRegistry: () => PluginRegistry,
   ProviderFactory: () => ProviderFactory,
   ProviderNotFoundError: () => ProviderNotFoundError,
   Thread: () => Thread,
   ThreadNotFoundError: () => ThreadNotFoundError,
   UpstashStorage: () => UpstashStorage,
-  createClient: () => createClient
+  createClient: () => createClient,
+  envRef: () => envRef,
+  pluginRegistry: () => pluginRegistry,
+  resolveEnvVars: () => resolveEnvVars
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -7551,33 +7555,88 @@ var Agent = class _Agent {
   }
   /**
    * Create a new agent
+   *
+   * If plugins are provided, their configurations will be extracted (if they implement getConfig())
+   * and stored in the database for later reinstantiation.
    */
   static async create(config, storage, providerFactory) {
-    const agentId = await storage.createAgent(config);
+    const pluginConfigs = config.pluginConfigs || [];
+    if (config.plugins && config.plugins.length > 0) {
+      for (const plugin of config.plugins) {
+        if ("getConfig" in plugin && typeof plugin.getConfig === "function") {
+          pluginConfigs.push({
+            type: plugin.type,
+            name: plugin.name,
+            config: plugin.getConfig(),
+            priority: plugin.priority,
+            enabled: true
+          });
+        }
+      }
+    }
+    const configWithPluginConfigs = {
+      ...config,
+      pluginConfigs
+    };
+    const agentId = await storage.createAgent(configWithPluginConfigs);
     const data = await storage.getAgent(agentId);
     if (!data) {
       throw new AgentNotFoundError(agentId);
     }
+    data.plugins = config.plugins || [];
     return new _Agent(data, storage, providerFactory);
   }
   /**
    * Load an existing agent by ID
+   *
+   * Plugins can be attached in three ways (in order of priority):
+   * 1. Direct plugins array - runtime plugin instances passed directly
+   * 2. Plugin registry - reinstantiate from stored configs using registered factories
+   * 3. No plugins - agent loads without plugin functionality
+   *
+   * @param agentId - The agent ID to load
+   * @param storage - Storage adapter
+   * @param providerFactory - Provider factory
+   * @param options - Either:
+   *   - Plugin[] array (legacy, for backwards compatibility)
+   *   - Options object with plugins and/or registry
    */
-  static async load(agentId, storage, providerFactory) {
+  static async load(agentId, storage, providerFactory, options) {
     const data = await storage.getAgent(agentId);
     if (!data) {
       return null;
     }
+    if (Array.isArray(options)) {
+      data.plugins = options;
+      return new _Agent(data, storage, providerFactory);
+    }
+    if (options?.plugins && options.plugins.length > 0) {
+      data.plugins = options.plugins;
+    } else if (options?.registry && data.pluginConfigs && data.pluginConfigs.length > 0) {
+      try {
+        data.plugins = await options.registry.instantiateAll(data.pluginConfigs);
+      } catch (error) {
+        console.error("Failed to reinstantiate plugins from stored configs:", error);
+        throw error;
+      }
+    } else {
+      data.plugins = [];
+    }
     return new _Agent(data, storage, providerFactory);
   }
   /**
    * Update agent properties
    */
   async update(updates) {
+    const currentPlugins = this.data.plugins || [];
     await this.storage.updateAgent(this.data.id, updates);
     const updatedData = await this.storage.getAgent(this.data.id);
     if (updatedData) {
+      updatedData.plugins = updates.plugins || currentPlugins;
       this.data = updatedData;
+      if (updates.plugins) {
+        this.pluginManager = new PluginManager(updatedData.plugins);
+      }
     }
   }
   /**
@@ -8390,6 +8449,7 @@ var AgentClient = class {
     this.storage = config.storage;
     this.providers = config.providers;
     this.providerFactory = new ProviderFactory(config.providers);
+    this.pluginRegistry = config.pluginRegistry;
   }
   validateConfig(config) {
     if (!config.storage) {
@@ -8432,9 +8492,28 @@ var AgentClient = class {
   }
   /**
    * Get an agent by ID
+   *
+   * Plugin loading priority:
+   * 1. Direct plugins array passed to this method
+   * 2. Plugin registry (if configured) - reinstantiates from stored configs
+   * 3. No plugins
+   *
+   * @param agentId - The agent ID to load
+   * @param options - Either Plugin[] for backwards compatibility, or options object
    */
-  async getAgent(agentId) {
-    const agent = await Agent.load(agentId, this.storage, this.providerFactory);
+  async getAgent(agentId, options) {
+    if (Array.isArray(options)) {
+      const agent2 = await Agent.load(agentId, this.storage, this.providerFactory, options);
+      if (!agent2) {
+        throw new AgentNotFoundError(agentId);
+      }
+      return agent2;
+    }
+    const registry = options?.registry || this.pluginRegistry;
+    const agent = await Agent.load(agentId, this.storage, this.providerFactory, {
+      plugins: options?.plugins,
+      registry
+    });
     if (!agent) {
       throw new AgentNotFoundError(agentId);
     }
@@ -8592,6 +8671,149 @@ Return only the title without additional explanations.`
   }
 };
 
+// src/core/PluginRegistry.ts
+function resolveEnvVars(config) {
+  const resolved = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (typeof value === "string") {
+      const envMatch = value.match(/^\$\{([^}:]+)(?::([^}]*))?\}$/);
+      if (envMatch) {
+        const [, envVar, defaultValue] = envMatch;
+        const envValue = process.env[envVar];
+        if (envValue !== void 0) {
+          resolved[key] = envValue;
+        } else if (defaultValue !== void 0) {
+          resolved[key] = defaultValue;
+        } else {
+          throw new Error(
+            `Environment variable ${envVar} is required for plugin config but not set`
+          );
+        }
+      } else {
+        resolved[key] = value;
+      }
+    } else if (value && typeof value === "object" && !Array.isArray(value)) {
+      resolved[key] = resolveEnvVars(value);
+    } else {
+      resolved[key] = value;
+    }
+  }
+  return resolved;
+}
+var PluginRegistry = class {
+  constructor() {
+    this.registrations = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a plugin factory
+   *
+   * @param name - Unique plugin identifier (e.g., "@snap-agent/rag-ecommerce")
+   * @param factory - Function that creates plugin instance from config
+   * @param defaultConfig - Optional default configuration values
+   */
+  register(name14, factory6, defaultConfig) {
+    if (this.registrations.has(name14)) {
+      console.warn(`Plugin "${name14}" is already registered. Overwriting.`);
+    }
+    this.registrations.set(name14, { factory: factory6, defaultConfig });
+  }
+  /**
+   * Unregister a plugin factory
+   */
+  unregister(name14) {
+    return this.registrations.delete(name14);
+  }
+  /**
+   * Check if a plugin is registered
+   */
+  isRegistered(name14) {
+    return this.registrations.has(name14);
+  }
+  /**
+   * Get all registered plugin names
+   */
+  getRegisteredPlugins() {
+    return Array.from(this.registrations.keys());
+  }
+  /**
+   * Instantiate a plugin from stored configuration
+   *
+   * @param storedConfig - Serialized plugin configuration from database
+   * @returns Plugin instance
+   * @throws Error if plugin is not registered
+   */
+  async instantiate(storedConfig) {
+    const registration = this.registrations.get(storedConfig.name);
+    if (!registration) {
+      throw new Error(
+        `Plugin "${storedConfig.name}" is not registered. Available plugins: ${this.getRegisteredPlugins().join(", ") || "none"}. Make sure to register the plugin before loading the agent.`
+      );
+    }
+    const mergedConfig = {
+      ...registration.defaultConfig,
+      ...storedConfig.config
+    };
+    const resolvedConfig = resolveEnvVars(mergedConfig);
+    const plugin = await registration.factory(resolvedConfig);
+    if (storedConfig.priority !== void 0) {
+      plugin.priority = storedConfig.priority;
+    }
+    return plugin;
+  }
+  /**
+   * Instantiate multiple plugins from stored configurations
+   *
+   * @param storedConfigs - Array of serialized plugin configurations
+   * @returns Array of plugin instances (skips disabled plugins)
+   */
+  async instantiateAll(storedConfigs) {
+    const plugins = [];
+    for (const config of storedConfigs) {
+      if (config.enabled === false) {
+        continue;
+      }
+      try {
+        const plugin = await this.instantiate(config);
+        plugins.push(plugin);
+      } catch (error) {
+        console.error(`Failed to instantiate plugin "${config.name}":`, error);
+        throw error;
+      }
+    }
+    return plugins;
+  }
+  /**
+   * Extract serializable configuration from a plugin instance
+   * Requires the plugin to implement getConfig() method
+   *
+   * @param plugin - Plugin instance
+   * @returns Stored plugin configuration
+   */
+  extractConfig(plugin) {
+    const config = plugin.getConfig?.() ?? {};
+    return {
+      type: plugin.type,
+      name: plugin.name,
+      config,
+      priority: plugin.priority,
+      enabled: true
+    };
+  }
+  /**
+   * Extract configurations from multiple plugins
+   */
+  extractAllConfigs(plugins) {
+    return plugins.map((plugin) => this.extractConfig(plugin));
+  }
+};
+var pluginRegistry = new PluginRegistry();
+function envRef(envVarName, defaultValue) {
+  if (defaultValue !== void 0) {
+    return `\${${envVarName}:${defaultValue}}`;
+  }
+  return `\${${envVarName}}`;
+}
+
 // src/storage/MongoDBStorage.ts
 var import_mongodb = require("mongodb");
 var MongoDBStorage = class {
@@ -8645,7 +8867,8 @@ var MongoDBStorage = class {
       createdAt: /* @__PURE__ */ new Date(),
       updatedAt: /* @__PURE__ */ new Date(),
       files: [],
-      metadata: config.metadata || {}
+      metadata: config.metadata || {},
+      pluginConfigs: config.pluginConfigs || []
     };
     const result = await collection.insertOne(doc);
     return result.insertedId.toString();
@@ -8828,7 +9051,8 @@ var MongoDBStorage = class {
       createdAt: doc.createdAt,
       updatedAt: doc.updatedAt,
       files: doc.files,
-      metadata: doc.metadata
+      metadata: doc.metadata,
+      pluginConfigs: doc.pluginConfigs
     };
   }
   threadDocToData(doc) {
@@ -9404,10 +9628,14 @@ function createClient(config) {
   Models,
   MongoDBStorage,
   PluginManager,
+  PluginRegistry,
   ProviderFactory,
   ProviderNotFoundError,
   Thread,
   ThreadNotFoundError,
   UpstashStorage,
-  createClient
+  createClient,
+  envRef,
+  pluginRegistry,
+  resolveEnvVars
 });

package/dist/index.mjs

@@ -2,7 +2,7 @@ import {
   MemoryStorage,
   MongoDBStorage,
   UpstashStorage
-} from "./chunk-Y5TTFQWC.mjs";
+} from "./chunk-FS7G3ID4.mjs";
 
 // src/core/Agent.ts
 import { generateText, streamText } from "ai";
@@ -219,33 +219,88 @@ var Agent = class _Agent {
   }
   /**
    * Create a new agent
+   *
+   * If plugins are provided, their configurations will be extracted (if they implement getConfig())
+   * and stored in the database for later reinstantiation.
    */
   static async create(config, storage, providerFactory) {
-    const agentId = await storage.createAgent(config);
+    const pluginConfigs = config.pluginConfigs || [];
+    if (config.plugins && config.plugins.length > 0) {
+      for (const plugin of config.plugins) {
+        if ("getConfig" in plugin && typeof plugin.getConfig === "function") {
+          pluginConfigs.push({
+            type: plugin.type,
+            name: plugin.name,
+            config: plugin.getConfig(),
+            priority: plugin.priority,
+            enabled: true
+          });
+        }
+      }
+    }
+    const configWithPluginConfigs = {
+      ...config,
+      pluginConfigs
+    };
+    const agentId = await storage.createAgent(configWithPluginConfigs);
     const data = await storage.getAgent(agentId);
     if (!data) {
       throw new AgentNotFoundError(agentId);
     }
+    data.plugins = config.plugins || [];
     return new _Agent(data, storage, providerFactory);
   }
   /**
    * Load an existing agent by ID
-   */
-  static async load(agentId, storage, providerFactory) {
+   *
+   * Plugins can be attached in three ways (in order of priority):
+   * 1. Direct plugins array - runtime plugin instances passed directly
+   * 2. Plugin registry - reinstantiate from stored configs using registered factories
+   * 3. No plugins - agent loads without plugin functionality
+   *
+   * @param agentId - The agent ID to load
+   * @param storage - Storage adapter
+   * @param providerFactory - Provider factory
+   * @param options - Either:
+   *   - Plugin[] array (legacy, for backwards compatibility)
+   *   - Options object with plugins and/or registry
+   */
+  static async load(agentId, storage, providerFactory, options) {
     const data = await storage.getAgent(agentId);
     if (!data) {
       return null;
     }
+    if (Array.isArray(options)) {
+      data.plugins = options;
+      return new _Agent(data, storage, providerFactory);
+    }
+    if (options?.plugins && options.plugins.length > 0) {
+      data.plugins = options.plugins;
+    } else if (options?.registry && data.pluginConfigs && data.pluginConfigs.length > 0) {
+      try {
+        data.plugins = await options.registry.instantiateAll(data.pluginConfigs);
+      } catch (error) {
+        console.error("Failed to reinstantiate plugins from stored configs:", error);
+        throw error;
+      }
+    } else {
+      data.plugins = [];
+    }
     return new _Agent(data, storage, providerFactory);
   }
   /**
    * Update agent properties
    */
   async update(updates) {
+    const currentPlugins = this.data.plugins || [];
     await this.storage.updateAgent(this.data.id, updates);
     const updatedData = await this.storage.getAgent(this.data.id);
     if (updatedData) {
+      updatedData.plugins = updates.plugins || currentPlugins;
       this.data = updatedData;
+      if (updates.plugins) {
+        this.pluginManager = new PluginManager(updatedData.plugins);
+      }
     }
   }
   /**
@@ -1058,6 +1113,7 @@ var AgentClient = class {
     this.storage = config.storage;
     this.providers = config.providers;
     this.providerFactory = new ProviderFactory(config.providers);
+    this.pluginRegistry = config.pluginRegistry;
   }
   validateConfig(config) {
     if (!config.storage) {
@@ -1100,9 +1156,28 @@ var AgentClient = class {
   }
   /**
    * Get an agent by ID
-   */
-  async getAgent(agentId) {
-    const agent = await Agent.load(agentId, this.storage, this.providerFactory);
+   *
+   * Plugin loading priority:
+   * 1. Direct plugins array passed to this method
+   * 2. Plugin registry (if configured) - reinstantiates from stored configs
+   * 3. No plugins
+   *
+   * @param agentId - The agent ID to load
+   * @param options - Either Plugin[] for backwards compatibility, or options object
+   */
+  async getAgent(agentId, options) {
+    if (Array.isArray(options)) {
+      const agent2 = await Agent.load(agentId, this.storage, this.providerFactory, options);
+      if (!agent2) {
+        throw new AgentNotFoundError(agentId);
+      }
+      return agent2;
+    }
+    const registry = options?.registry || this.pluginRegistry;
+    const agent = await Agent.load(agentId, this.storage, this.providerFactory, {
+      plugins: options?.plugins,
+      registry
+    });
     if (!agent) {
       throw new AgentNotFoundError(agentId);
     }
@@ -1260,6 +1335,149 @@ Return only the title without additional explanations.`
   }
 };
 
+// src/core/PluginRegistry.ts
+function resolveEnvVars(config) {
+  const resolved = {};
+  for (const [key, value] of Object.entries(config)) {
+    if (typeof value === "string") {
+      const envMatch = value.match(/^\$\{([^}:]+)(?::([^}]*))?\}$/);
+      if (envMatch) {
+        const [, envVar, defaultValue] = envMatch;
+        const envValue = process.env[envVar];
+        if (envValue !== void 0) {
+          resolved[key] = envValue;
+        } else if (defaultValue !== void 0) {
+          resolved[key] = defaultValue;
+        } else {
+          throw new Error(
+            `Environment variable ${envVar} is required for plugin config but not set`
+          );
+        }
+      } else {
+        resolved[key] = value;
+      }
+    } else if (value && typeof value === "object" && !Array.isArray(value)) {
+      resolved[key] = resolveEnvVars(value);
+    } else {
+      resolved[key] = value;
+    }
+  }
+  return resolved;
+}
+var PluginRegistry = class {
+  constructor() {
+    this.registrations = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a plugin factory
+   *
+   * @param name - Unique plugin identifier (e.g., "@snap-agent/rag-ecommerce")
+   * @param factory - Function that creates plugin instance from config
+   * @param defaultConfig - Optional default configuration values
+   */
+  register(name, factory, defaultConfig) {
+    if (this.registrations.has(name)) {
+      console.warn(`Plugin "${name}" is already registered. Overwriting.`);
+    }
+    this.registrations.set(name, { factory, defaultConfig });
+  }
+  /**
+   * Unregister a plugin factory
+   */
+  unregister(name) {
+    return this.registrations.delete(name);
+  }
+  /**
+   * Check if a plugin is registered
+   */
+  isRegistered(name) {
+    return this.registrations.has(name);
+  }
+  /**
+   * Get all registered plugin names
+   */
+  getRegisteredPlugins() {
+    return Array.from(this.registrations.keys());
+  }
+  /**
+   * Instantiate a plugin from stored configuration
+   *
+   * @param storedConfig - Serialized plugin configuration from database
+   * @returns Plugin instance
+   * @throws Error if plugin is not registered
+   */
+  async instantiate(storedConfig) {
+    const registration = this.registrations.get(storedConfig.name);
+    if (!registration) {
+      throw new Error(
+        `Plugin "${storedConfig.name}" is not registered. Available plugins: ${this.getRegisteredPlugins().join(", ") || "none"}. Make sure to register the plugin before loading the agent.`
+      );
+    }
+    const mergedConfig = {
+      ...registration.defaultConfig,
+      ...storedConfig.config
+    };
+    const resolvedConfig = resolveEnvVars(mergedConfig);
+    const plugin = await registration.factory(resolvedConfig);
+    if (storedConfig.priority !== void 0) {
+      plugin.priority = storedConfig.priority;
+    }
+    return plugin;
+  }
+  /**
+   * Instantiate multiple plugins from stored configurations
+   *
+   * @param storedConfigs - Array of serialized plugin configurations
+   * @returns Array of plugin instances (skips disabled plugins)
+   */
+  async instantiateAll(storedConfigs) {
+    const plugins = [];
+    for (const config of storedConfigs) {
+      if (config.enabled === false) {
+        continue;
+      }
+      try {
+        const plugin = await this.instantiate(config);
+        plugins.push(plugin);
+      } catch (error) {
+        console.error(`Failed to instantiate plugin "${config.name}":`, error);
+        throw error;
+      }
+    }
+    return plugins;
+  }
+  /**
+   * Extract serializable configuration from a plugin instance
+   * Requires the plugin to implement getConfig() method
+   *
+   * @param plugin - Plugin instance
+   * @returns Stored plugin configuration
+   */
+  extractConfig(plugin) {
+    const config = plugin.getConfig?.() ?? {};
+    return {
+      type: plugin.type,
+      name: plugin.name,
+      config,
+      priority: plugin.priority,
+      enabled: true
+    };
+  }
+  /**
+   * Extract configurations from multiple plugins
+   */
+  extractAllConfigs(plugins) {
+    return plugins.map((plugin) => this.extractConfig(plugin));
+  }
+};
+var pluginRegistry = new PluginRegistry();
+function envRef(envVarName, defaultValue) {
+  if (defaultValue !== void 0) {
+    return `\${${envVarName}:${defaultValue}}`;
+  }
+  return `\${${envVarName}}`;
+}
+
 // src/index.ts
 function createClient(config) {
   return new AgentClient(config);
@@ -1275,10 +1493,14 @@ export {
   Models,
   MongoDBStorage,
   PluginManager,
+  PluginRegistry,
   ProviderFactory,
   ProviderNotFoundError,
   Thread,
   ThreadNotFoundError,
   UpstashStorage,
-  createClient
+  createClient,
+  envRef,
+  pluginRegistry,
+  resolveEnvVars
 };

package/dist/storage/index.d.mts

@@ -1 +1 @@
-export { L as MemoryStorage, K as MongoDBStorage, O as MongoDBStorageConfig, N as UpstashStorage, Q as UpstashStorageConfig } from '../index-CDsqnM8L.mjs';
+export { W as MemoryStorage, V as MongoDBStorage, Y as MongoDBStorageConfig, X as UpstashStorage, Z as UpstashStorageConfig } from '../index-m2vDW79n.mjs';

package/dist/storage/index.d.ts

@@ -1 +1 @@
-export { L as MemoryStorage, K as MongoDBStorage, O as MongoDBStorageConfig, N as UpstashStorage, Q as UpstashStorageConfig } from '../index-CDsqnM8L.js';
+export { W as MemoryStorage, V as MongoDBStorage, Y as MongoDBStorageConfig, X as UpstashStorage, Z as UpstashStorageConfig } from '../index-m2vDW79n.js';

package/dist/storage/index.js

@@ -79,7 +79,8 @@ var MongoDBStorage = class {
       createdAt: /* @__PURE__ */ new Date(),
       updatedAt: /* @__PURE__ */ new Date(),
       files: [],
-      metadata: config.metadata || {}
+      metadata: config.metadata || {},
+      pluginConfigs: config.pluginConfigs || []
     };
     const result = await collection.insertOne(doc);
     return result.insertedId.toString();
@@ -262,7 +263,8 @@ var MongoDBStorage = class {
       createdAt: doc.createdAt,
       updatedAt: doc.updatedAt,
       files: doc.files,
-      metadata: doc.metadata
+      metadata: doc.metadata,
+      pluginConfigs: doc.pluginConfigs
     };
   }
   threadDocToData(doc) {

package/dist/storage/index.mjs

@@ -2,7 +2,7 @@ import {
   MemoryStorage,
   MongoDBStorage,
   UpstashStorage
-} from "../chunk-Y5TTFQWC.mjs";
+} from "../chunk-FS7G3ID4.mjs";
 export {
   MemoryStorage,
   MongoDBStorage,