@snap-agent/core 0.1.0 → 0.1.3

package/dist/index.mjs

@@ -2,10 +2,10 @@ import {
   MemoryStorage,
   MongoDBStorage,
   UpstashStorage
-} from "./chunk-Y5TTFQWC.mjs";
+} from "./chunk-FS7G3ID4.mjs";
 
 // src/core/Agent.ts
-import { generateText, streamText } from "ai";
+import { generateText, streamText, Output } from "ai";
 
 // src/core/PluginManager.ts
 var PluginManager = class {
@@ -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);
+      }
     }
   }
   /**
@@ -297,11 +352,37 @@ var Agent = class _Agent {
       ragMetadata = allMetadata;
     }
     const model = await this.providerFactory.getModel(this.data.provider, this.data.model);
-    const { text } = await generateText({
-      model,
-      messages: beforeResult.messages,
-      system: systemPrompt
-    });
+    let text;
+    let parsed;
+    if (options?.output?.mode === "object") {
+      const result = await generateText({
+        model,
+        messages: beforeResult.messages,
+        system: systemPrompt,
+        experimental_output: Output.object({ schema: options.output.schema })
+      });
+      text = JSON.stringify(result.experimental_output);
+      parsed = result.experimental_output;
+    } else if (options?.output?.mode === "json") {
+      const jsonSystemPrompt = systemPrompt + "\n\n---\nOUTPUT FORMAT: You MUST respond with valid JSON only. No markdown code blocks, no explanations, no additional text - just raw JSON that can be parsed directly.";
+      const result = await generateText({
+        model,
+        messages: beforeResult.messages,
+        system: jsonSystemPrompt
+      });
+      text = result.text;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+      }
+    } else {
+      const result = await generateText({
+        model,
+        messages: beforeResult.messages,
+        system: systemPrompt
+      });
+      text = result.text;
+    }
     const afterResult = await this.pluginManager.executeAfterResponse(text, {
       agentId: this.data.id,
       threadId: options?.threadId,
@@ -317,6 +398,7 @@ var Agent = class _Agent {
     });
     return {
       text: afterResult.response,
+      ...parsed !== void 0 && { parsed },
       metadata: {
         ...afterResult.metadata,
         ragMetadata,
@@ -1058,6 +1140,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 +1183,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 +1362,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 +1520,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,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@snap-agent/core",
-  "version": "0.1.0",
-  "description": "SnapAgent - The lightweight, snap-in AI agent SDK. Multi-provider support (OpenAI, Anthropic, Google). Edge-runtime compatible.",
+  "version": "0.1.3",
+  "description": "SnapAgent - The lightweight, snap-in AI agent SDK. Multi-provider support. Edge-runtime compatible.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -63,8 +63,8 @@
   "author": "ViloTech",
   "license": "MIT",
   "peerDependencies": {
-    "@ai-sdk/openai": "^2.0.0",
-    "ai": "^5.0.0",
+    "@ai-sdk/openai": "^2.0.0 || ^3.0.0",
+    "ai": "^5.0.0 || ^6.0.0",
     "mongodb": "^6.0.0 || ^7.0.0"
   },
   "peerDependenciesMeta": {
@@ -82,13 +82,14 @@
     }
   },
   "devDependencies": {
-    "@ai-sdk/anthropic": "^2.0.0",
-    "@ai-sdk/google": "^2.0.0",
+    "@ai-sdk/anthropic": "^2.0.0 || ^3.0.0",
+    "@ai-sdk/google": "^2.0.0 || ^3.0.0",
     "@types/node": "^24.0.0",
     "dotenv": "^17.2.3",
     "eslint": "^8.0.0",
     "mongodb": "^7.0.0",
     "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.8.0",
     "vitest": "^1.0.0"
   },