@snap-agent/core 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # SnapAgent
 
-**The AI Agent SDK that runs everywhere.** A TypeScript-first SDK for building stateful AI agents with multi-provider support (OpenAI, Anthropic, Google). Extensible via plugins. Edge-runtime compatible.
+**The AI Agent SDK that runs everywhere.** A TypeScript-first SDK for building stateful AI agents with multi-provider support. Extensible via plugins. Edge-runtime compatible.
 
 ## Why SnapAgent?
 
@@ -10,6 +10,7 @@
 | **Bundle Size** | ~63 KB | ~150 KB | ~2 MB+ |
 | **Multi-Provider** | OpenAI, Anthropic, Google | OpenAI only | ✅ |
 | **Plugin Architecture** | RAG, Tools, Middleware, Analytics | Tools only | Chains |
+| **Plugin Persistence** | ✅ Registry pattern | ❌ | ❌ |
 | **Persistent Storage** | Upstash, MongoDB, Memory | In-memory only | Via integrations |
 | **Zero-Config RAG** | Built-in | Manual | Manual |
 
@@ -18,6 +19,7 @@
 - **Multi-Provider** — Switch between OpenAI, Anthropic, and Google seamlessly  
 - **Edge Runtime** — Deploy to Cloudflare Workers, Vercel Edge, Deno Deploy  
 - **Plugin Architecture** — Extend with RAG, tools, middleware, and analytics plugins  
+- **Plugin Persistence** — Plugins survive server restarts via the Plugin Registry  
 - **Persistent Storage** — Upstash Redis (edge), MongoDB (server), or bring your own  
 - **Zero-Config RAG** — Add semantic search with one line of config  
 - **Stateful Threads** — Automatic conversation history management  
@@ -201,12 +203,45 @@ SnapAgent is built around a powerful plugin system. Extend your agents with any
 | **Middleware Plugins** | Intercept and transform requests/responses | Rate limiting, content moderation, logging |
 | **Analytics Plugins** | Track usage and performance | Monitoring, billing, optimization |
 
-### Combining Multiple Plugins
+### Understanding Plugin Types
+
+All extensions are added to the `plugins` array, but they serve different purposes:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         plugins: [...]                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  MIDDLEWARES (run first, intercept requests)                   │
+│  ├── RateLimiter      → Abuse prevention (100 req/min)         │
+│  ├── TokenBudget      → Cost control ($10/day)                 │
+│  ├── ContentModeration → Block harmful content                 │
+│  └── SlackNotifications → Alert on errors                      │
+│                                                                 │
+│  PLUGINS (enhance agent capabilities)                          │
+│  ├── EcommerceRAGPlugin → Product search knowledge             │
+│  ├── DocsRAGPlugin      → Documentation knowledge              │
+│  └── CustomTools        → Callable functions                   │
+│                                                                 │
+│  ANALYTICS (run last, track everything)                        │
+│  ├── SnapAgentAnalytics → Full metrics suite                   │
+│  └── ConsoleAnalytics   → Dev-friendly logging                 │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Execution order is handled automatically** via the `priority` field:
+- Middlewares: priority 1-100 (run first)
+- RAG/Tools: priority 100-150
+- Analytics: priority 200+ (run last)
+
+### Combining Plugins and Middlewares
 
 ```typescript
 import { createClient, MemoryStorage } from '@snap-agent/core';
 import { EcommerceRAGPlugin } from '@snap-agent/rag-ecommerce';
 import { RateLimiter } from '@snap-agent/middleware-ratelimit';
+import { TokenBudget } from '@snap-agent/middleware-budget';
 import { SlackNotifications } from '@snap-agent/middleware-slack';
 import { ConsoleAnalytics } from '@snap-agent/analytics-console';
 
@@ -217,27 +252,35 @@ const agent = await client.createAgent({
   model: 'gpt-4o',
   userId: 'user-123',
   plugins: [
-    // RAG: Search product catalog
-    new EcommerceRAGPlugin({
-      mongoUri: process.env.MONGODB_URI!,
-      openaiApiKey: process.env.OPENAI_API_KEY!,
-      tenantId: 'my-store',
-    }),
-    
-    // Middleware: Rate limiting
-    new RateLimiter({
+    // ─────────────────────────────────────────────────────────────
+    // MIDDLEWARES: Request/response interception (run first)
+    // ─────────────────────────────────────────────────────────────
+    new RateLimiter({                    // Abuse prevention
       maxRequests: 100,
       windowMs: 60000,
     }),
-    
-    // Middleware: Slack alerts on errors
-    new SlackNotifications({
+    new TokenBudget({                    // Cost control
+      maxCostPerPeriod: 10.00,
+      period: 'day',
+    }),
+    new SlackNotifications({             // Error alerts
       webhookUrl: process.env.SLACK_WEBHOOK!,
-      onError: true,
+      triggers: { onError: true },
     }),
-    
-    // Analytics: Log everything
-    new ConsoleAnalytics(),
+
+    // ─────────────────────────────────────────────────────────────
+    // PLUGINS: Agent capabilities (RAG, tools)
+    // ─────────────────────────────────────────────────────────────
+    new EcommerceRAGPlugin({             // Product knowledge
+      mongoUri: process.env.MONGODB_URI!,
+      openaiApiKey: process.env.OPENAI_API_KEY!,
+      tenantId: 'my-store',
+    }),
+
+    // ─────────────────────────────────────────────────────────────
+    // ANALYTICS: Tracking and monitoring (run last)
+    // ─────────────────────────────────────────────────────────────
+    new ConsoleAnalytics({ level: 'standard' }),
   ],
 });
 ```
@@ -278,19 +321,230 @@ class CustomAnalytics implements AnalyticsPlugin {
 }
 ```
 
-### Available Plugins
+### Plugin Persistence with Plugin Registry
+
+Plugins are runtime objects (classes with methods, database connections, etc.) that can't be directly saved to a database. The **Plugin Registry** solves this by:
+
+1. Storing serializable plugin configurations in your database
+2. Automatically reinstantiating plugins when you load an agent after a process restart
+
+#### Why Plugin Persistence Matters
+
+Without the Plugin Registry, you'd lose all plugins when:
+- Your server restarts
+- A request is routed to a different server instance
+- You load an agent from the database in a new process
+
+#### Setting Up the Plugin Registry
+
+```typescript
+import { 
+  createClient, 
+  PluginRegistry, 
+  MongoDBStorage 
+} from '@snap-agent/core';
+import { EcommerceRAGPlugin } from '@snap-agent/rag-ecommerce';
+import { RateLimiter } from '@snap-agent/middleware-ratelimit';
+
+// 1. Create and configure the registry
+const registry = new PluginRegistry();
+
+// 2. Register plugin factories (plugin name → factory function)
+registry.register('@snap-agent/rag-ecommerce', (config) => 
+  new EcommerceRAGPlugin(config)
+);
+
+registry.register('@snap-agent/middleware-ratelimit', (config) => 
+  new RateLimiter(config)
+);
+
+// 3. Create client with registry
+const client = createClient({
+  storage: new MongoDBStorage(process.env.MONGODB_URI!),
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  pluginRegistry: registry,  // ← Enable automatic plugin reinstantiation
+});
+```
+
+#### Making Plugins Persistable
+
+For a plugin's configuration to be saved, it must implement the `getConfig()` method:
+
+```typescript
+class MyRAGPlugin implements RAGPlugin {
+  type = 'rag' as const;
+  name = '@myorg/my-rag-plugin';  // Unique identifier
+  
+  private config: MyPluginConfig;
+
+  constructor(config: MyPluginConfig) {
+    this.config = config;
+  }
+
+  // Return serializable configuration
+  // Use env var references for sensitive values!
+  getConfig() {
+    return {
+      // Safe: Use env var reference (not the actual secret)
+      apiKey: '${MY_API_KEY}',
+      mongoUri: '${MONGODB_URI}',
+      
+      // Safe: Non-sensitive values stored directly
+      embeddingModel: this.config.embeddingModel,
+      limit: this.config.limit,
+    };
+  }
+
+  async retrieveContext(message: string, options: any) {
+    // ... implementation
+  }
+}
+```
+
+#### Environment Variable References
+
+Store sensitive values (API keys, connection strings) as environment variable references instead of actual values:
+
+```typescript
+// ✅ GOOD: Environment variable references (safe to store in DB)
+getConfig() {
+  return {
+    openaiKey: '${OPENAI_API_KEY}',           // Required env var
+    timeout: '${TIMEOUT:5000}',                // With default value
+    mongoUri: '${MONGODB_URI}',
+  };
+}
+
+// ❌ BAD: Actual secrets (never store in database!)
+getConfig() {
+  return {
+    openaiKey: 'sk-actual-secret-key',  // Don't do this!
+  };
+}
+```
+
+The `envRef()` helper makes this cleaner:
+
+```typescript
+import { envRef } from '@snap-agent/core';
+
+getConfig() {
+  return {
+    apiKey: envRef('OPENAI_API_KEY'),           // Required
+    timeout: envRef('TIMEOUT', '5000'),          // With default
+  };
+}
+```
+
+#### Complete Example: Persistent Agents
+
+```typescript
+import { createClient, PluginRegistry, MongoDBStorage, envRef } from '@snap-agent/core';
+import { EcommerceRAGPlugin } from '@snap-agent/rag-ecommerce';
+
+// Setup registry
+const registry = new PluginRegistry();
+registry.register('@snap-agent/rag-ecommerce', (config) => 
+  new EcommerceRAGPlugin(config)
+);
+
+const client = createClient({
+  storage: new MongoDBStorage(process.env.MONGODB_URI!),
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  pluginRegistry: registry,
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// INITIAL SETUP (run once)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const agent = await client.createAgent({
+  name: 'Shopping Assistant',
+  instructions: 'Help customers find products.',
+  provider: 'openai',
+  model: 'gpt-4o',
+  userId: 'user-123',
+  plugins: [
+    new EcommerceRAGPlugin({
+      mongoUri: process.env.MONGODB_URI!,
+      voyageApiKey: process.env.VOYAGE_API_KEY!,
+      tenantId: 'my-store',
+    }),
+  ],
+});
+
+console.log('Agent created:', agent.id);
+// Plugin config is automatically extracted and saved to MongoDB!
+
+// ═══════════════════════════════════════════════════════════════════════════
+// AFTER SERVER RESTART (plugins automatically reinstantiated)
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Later, in a different process or after restart:
+const loadedAgent = await client.getAgent('agent-123');
+
+// ✅ Plugins are automatically reinstantiated from stored config!
+// The registry looked up '@snap-agent/rag-ecommerce' and called its factory
+// with the stored config (env vars resolved at runtime)
+
+const response = await client.chat({
+  threadId: 'thread-456',
+  message: 'Find me a red dress under $100',
+  useRAG: true,  // RAG plugin works!
+});
+```
+
+#### Plugin Loading Priority
+
+When loading an agent, plugins are resolved in this order:
+
+1. **Direct plugins** (highest priority) — Plugins passed to `getAgent()`
+2. **Registry** — Reinstantiate from stored configs using registered factories  
+3. **None** — Agent loads without plugins
+
+```typescript
+// Priority 1: Direct plugins (override stored configs)
+const agent = await client.getAgent('agent-123', {
+  plugins: [new CustomPlugin()],  // Uses this, ignores stored configs
+});
+
+// Priority 2: Use registry (automatic from client config)
+const agent = await client.getAgent('agent-123');
+// Uses registry to reinstantiate from stored configs
+
+// Priority 3: Override registry for this call
+const agent = await client.getAgent('agent-123', {
+  registry: differentRegistry,
+});
+```
+
+### Available Packages
+
+**RAG Plugins** — Add knowledge to your agents:
+
+| Package | Description | Links |
+|---------|-------------|-------|
+| `@snap-agent/rag-ecommerce` | E-commerce product search with attribute extraction | [npm](https://www.npmjs.com/package/@snap-agent/rag-ecommerce) · [github](https://github.com/vilo-hq/snap-agent/tree/main/plugins/rag/ecommerce) |
+| `@snap-agent/rag-docs` | General documentation search | [github](https://github.com/vilo-hq/snap-agent/tree/main/plugins/rag/docs) |
+
+**Middlewares** — Intercept requests/responses:
+
+| Package | Description | Links |
+|---------|-------------|-------|
+| `@snap-agent/middleware-ratelimit` | Abuse prevention (100 req/min) | [github](https://github.com/vilo-hq/snap-agent/tree/main/middlewares/ratelimit) |
+| `@snap-agent/middleware-budget` | Cost control ($10/day limits) | [github](https://github.com/vilo-hq/snap-agent/tree/main/middlewares/budget) |
+| `@snap-agent/middleware-slack` | Slack notifications | [github](https://github.com/vilo-hq/snap-agent/tree/main/middlewares/slack) |
+| `@snap-agent/middleware-discord` | Discord notifications | [github](https://github.com/vilo-hq/snap-agent/tree/main/middlewares/discord) |
+| `@snap-agent/middleware-webhooks` | Custom HTTP webhooks | [github](https://github.com/vilo-hq/snap-agent/tree/main/middlewares/webhooks) |
+| `@snap-agent/middleware-moderation` | Content moderation | [github](https://github.com/vilo-hq/snap-agent/tree/main/middlewares/moderation) |
+
+**Analytics** — Track usage and performance:
+
+| Package | Description | Links |
+|---------|-------------|-------|
+| `@snap-agent/analytics` | Full metrics suite (performance, cost, RAG, errors) | [github](https://github.com/vilo-hq/snap-agent/tree/main/plugins/analytics/core) |
+| `@snap-agent/analytics-console` | Dev-friendly console logging | [github](https://github.com/vilo-hq/snap-agent/tree/main/plugins/analytics/console) |
 
-| Package | Description |
-|---------|-------------|
-| `@snap-agent/rag-ecommerce` | E-commerce product search with attribute extraction |
-| `@snap-agent/rag-support` | Support ticket and documentation search |
-| `@snap-agent/rag-docs` | General documentation search |
-| `@snap-agent/middleware-ratelimit` | Request rate limiting |
-| `@snap-agent/middleware-moderation` | Content moderation |
-| `@snap-agent/middleware-slack` | Slack notifications |
-| `@snap-agent/middleware-discord` | Discord notifications |
-| `@snap-agent/middleware-webhooks` | Custom webhook notifications |
-| `@snap-agent/analytics-console` | Console logging analytics |
 
 ## Zero-Config RAG
 
@@ -603,6 +857,7 @@ See [EDGE_RUNTIME.md](./EDGE_RUNTIME.md) for complete documentation.
 | Edge Compatible | ✅ | ❌ | ❌ | ✅ |
 | Multi-Provider | ✅ | OpenAI only | ✅ | ✅ |
 | Plugin Architecture | RAG, Tools, Middleware | Tools only | Chains | No |
+| Plugin Persistence | ✅ Registry pattern | ❌ | ❌ | N/A |
 | Persistent Storage | Upstash, MongoDB | In-memory | Via integrations | No |
 | Zero-Config RAG | ✅ | ❌ | ❌ | ❌ |
 | Agent Management | ✅ | ✅ | Complex | No |
@@ -620,6 +875,6 @@ Contributions are welcome! Please open an issue or submit a pull request on [Git
 MIT © ViloTech
 
 ## Support
-
+- [Vilo](https://vilotech.co)
 - [GitHub Issues](https://github.com/vilo-hq/snap-agent/issues)
 

package/dist/{chunk-Y5TTFQWC.mjs → chunk-FS7G3ID4.mjs}

@@ -51,7 +51,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();
@@ -234,7 +235,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/{index-CDsqnM8L.d.mts → index-m2vDW79n.d.mts}

@@ -5,6 +5,21 @@ interface BasePlugin {
     name: string;
     type: 'rag' | 'tool' | 'middleware' | 'analytics';
     priority?: number;
+    /**
+     * Optional: Return serializable configuration for persistence
+     * Used by PluginRegistry to store plugin config in database
+     * Should NOT include sensitive values - use env var references instead
+     *
+     * @example
+     * getConfig() {
+     *   return {
+     *     mongoUri: '${MONGO_URI}',  // Reference to env var
+     *     embeddingModel: 'voyage-3-lite',  // Safe to store
+     *     limit: 10,
+     *   };
+     * }
+     */
+    getConfig?(): Record<string, any>;
 }
 interface RAGContext {
     content: string;
@@ -342,6 +357,34 @@ interface AnalyticsPlugin extends BasePlugin {
     }): Promise<Record<string, any>>;
 }
 type Plugin = RAGPlugin | ToolPlugin | MiddlewarePlugin | AnalyticsPlugin;
+/**
+ * Serializable plugin configuration stored in database
+ * Used to reinstantiate plugins when loading agents
+ */
+interface StoredPluginConfig {
+    /**
+     * Plugin type (rag, middleware, analytics, tool)
+     */
+    type: Plugin['type'];
+    /**
+     * Unique plugin identifier (e.g., "@snap-agent/rag-ecommerce")
+     * Used to look up the factory function in the registry
+     */
+    name: string;
+    /**
+     * Serializable configuration for the plugin
+     * Use env var references for sensitive values: "${ENV_VAR_NAME}"
+     */
+    config: Record<string, any>;
+    /**
+     * Plugin priority (lower = executed first)
+     */
+    priority?: number;
+    /**
+     * Whether this plugin is enabled
+     */
+    enabled?: boolean;
+}
 
 type ProviderType = 'openai' | 'anthropic' | 'google';
 interface ProviderConfig {
@@ -395,6 +438,7 @@ interface AgentConfig {
     organizationId?: string;
     phone?: string;
     plugins?: Plugin[];
+    pluginConfigs?: StoredPluginConfig[];
     rag?: RAGConfig;
 }
 interface AgentData extends AgentConfig {
@@ -485,9 +529,23 @@ interface StorageAdapter {
         content: string;
     }>>;
 }
+/**
+ * Plugin registry for reinstantiating plugins from stored configs
+ * Import from '@snap-agent/core' or create your own instance
+ */
+interface PluginRegistryInterface {
+    instantiateAll(storedConfigs: StoredPluginConfig[]): Promise<Plugin[]>;
+    isRegistered(name: string): boolean;
+}
 interface ClientConfig {
     storage: StorageAdapter;
     providers: ProviderConfig;
+    /**
+     * Optional plugin registry for automatic plugin reinstantiation
+     * When provided, agents loaded with getAgent() will automatically
+     * reinstantiate their plugins from stored configurations
+     */
+    pluginRegistry?: PluginRegistryInterface;
 }
 declare class AgentSDKError extends Error {
     constructor(message: string);
@@ -677,4 +735,4 @@ declare class UpstashStorage implements StorageAdapter {
     }>;
 }
 
-export { type AgentData as A, type BulkOperation as B, type ClientConfig as C, AgentSDKError as D, type ErrorTrackingData as E, AgentNotFoundError as F, ThreadNotFoundError as G, ProviderNotFoundError as H, type IngestOptions as I, InvalidConfigError as J, MongoDBStorage as K, MemoryStorage as L, type MessageRole as M, UpstashStorage as N, type MongoDBStorageConfig as O, type ProviderConfig as P, type UpstashStorageConfig as Q, type RAGDocument as R, type StorageAdapter as S, type ThreadData as T, type URLSource as U, type ProviderType as a, type AgentConfig as b, type AgentFile as c, type Plugin as d, type IngestResult as e, type BulkResult as f, type URLIngestResult as g, type ThreadConfig as h, type MessageAttachment as i, type MessageData as j, type ChatRequest as k, type ChatResponse as l, type StreamCallbacks as m, type RAGPlugin as n, type ToolPlugin as o, type MiddlewarePlugin as p, type AnalyticsPlugin as q, type RAGContext as r, type RAGConfig as s, type BasePlugin as t, type Tool as u, type PerformanceTimings as v, type RAGMetrics as w, type TokenMetrics as x, type RequestTrackingData as y, type ResponseTrackingData as z };
+export { type AgentData as A, type BulkOperation as B, type ClientConfig as C, type DataTransform as D, type TokenMetrics as E, type RequestTrackingData as F, type ResponseTrackingData as G, type ErrorTrackingData as H, type IngestOptions as I, type PluginRegistryInterface as J, AgentSDKError as K, AgentNotFoundError as L, type MessageRole as M, ThreadNotFoundError as N, ProviderNotFoundError as O, type ProviderConfig as P, InvalidConfigError as Q, type RAGDocument as R, type StoredPluginConfig as S, type ThreadData as T, type URLSource as U, MongoDBStorage as V, MemoryStorage as W, UpstashStorage as X, type MongoDBStorageConfig as Y, type UpstashStorageConfig as Z, type ProviderType as a, type Plugin as b, type StorageAdapter as c, type AgentConfig as d, type AgentFile as e, type IngestResult as f, type BulkResult as g, type URLIngestResult as h, type ThreadConfig as i, type MessageAttachment as j, type MessageData as k, type ChatRequest as l, type ChatResponse as m, type StreamCallbacks as n, type RAGPlugin as o, type ToolPlugin as p, type MiddlewarePlugin as q, type AnalyticsPlugin as r, type RAGContext as s, type RAGConfig as t, type BasePlugin as u, type URLSourceAuth as v, type IngestionSchedule as w, type Tool as x, type PerformanceTimings as y, type RAGMetrics as z };

package/dist/{index-CDsqnM8L.d.ts → index-m2vDW79n.d.ts}

@@ -5,6 +5,21 @@ interface BasePlugin {
     name: string;
     type: 'rag' | 'tool' | 'middleware' | 'analytics';
     priority?: number;
+    /**
+     * Optional: Return serializable configuration for persistence
+     * Used by PluginRegistry to store plugin config in database
+     * Should NOT include sensitive values - use env var references instead
+     *
+     * @example
+     * getConfig() {
+     *   return {
+     *     mongoUri: '${MONGO_URI}',  // Reference to env var
+     *     embeddingModel: 'voyage-3-lite',  // Safe to store
+     *     limit: 10,
+     *   };
+     * }
+     */
+    getConfig?(): Record<string, any>;
 }
 interface RAGContext {
     content: string;
@@ -342,6 +357,34 @@ interface AnalyticsPlugin extends BasePlugin {
     }): Promise<Record<string, any>>;
 }
 type Plugin = RAGPlugin | ToolPlugin | MiddlewarePlugin | AnalyticsPlugin;
+/**
+ * Serializable plugin configuration stored in database
+ * Used to reinstantiate plugins when loading agents
+ */
+interface StoredPluginConfig {
+    /**
+     * Plugin type (rag, middleware, analytics, tool)
+     */
+    type: Plugin['type'];
+    /**
+     * Unique plugin identifier (e.g., "@snap-agent/rag-ecommerce")
+     * Used to look up the factory function in the registry
+     */
+    name: string;
+    /**
+     * Serializable configuration for the plugin
+     * Use env var references for sensitive values: "${ENV_VAR_NAME}"
+     */
+    config: Record<string, any>;
+    /**
+     * Plugin priority (lower = executed first)
+     */
+    priority?: number;
+    /**
+     * Whether this plugin is enabled
+     */
+    enabled?: boolean;
+}
 
 type ProviderType = 'openai' | 'anthropic' | 'google';
 interface ProviderConfig {
@@ -395,6 +438,7 @@ interface AgentConfig {
     organizationId?: string;
     phone?: string;
     plugins?: Plugin[];
+    pluginConfigs?: StoredPluginConfig[];
     rag?: RAGConfig;
 }
 interface AgentData extends AgentConfig {
@@ -485,9 +529,23 @@ interface StorageAdapter {
         content: string;
     }>>;
 }
+/**
+ * Plugin registry for reinstantiating plugins from stored configs
+ * Import from '@snap-agent/core' or create your own instance
+ */
+interface PluginRegistryInterface {
+    instantiateAll(storedConfigs: StoredPluginConfig[]): Promise<Plugin[]>;
+    isRegistered(name: string): boolean;
+}
 interface ClientConfig {
     storage: StorageAdapter;
     providers: ProviderConfig;
+    /**
+     * Optional plugin registry for automatic plugin reinstantiation
+     * When provided, agents loaded with getAgent() will automatically
+     * reinstantiate their plugins from stored configurations
+     */
+    pluginRegistry?: PluginRegistryInterface;
 }
 declare class AgentSDKError extends Error {
     constructor(message: string);
@@ -677,4 +735,4 @@ declare class UpstashStorage implements StorageAdapter {
     }>;
 }
 
-export { type AgentData as A, type BulkOperation as B, type ClientConfig as C, AgentSDKError as D, type ErrorTrackingData as E, AgentNotFoundError as F, ThreadNotFoundError as G, ProviderNotFoundError as H, type IngestOptions as I, InvalidConfigError as J, MongoDBStorage as K, MemoryStorage as L, type MessageRole as M, UpstashStorage as N, type MongoDBStorageConfig as O, type ProviderConfig as P, type UpstashStorageConfig as Q, type RAGDocument as R, type StorageAdapter as S, type ThreadData as T, type URLSource as U, type ProviderType as a, type AgentConfig as b, type AgentFile as c, type Plugin as d, type IngestResult as e, type BulkResult as f, type URLIngestResult as g, type ThreadConfig as h, type MessageAttachment as i, type MessageData as j, type ChatRequest as k, type ChatResponse as l, type StreamCallbacks as m, type RAGPlugin as n, type ToolPlugin as o, type MiddlewarePlugin as p, type AnalyticsPlugin as q, type RAGContext as r, type RAGConfig as s, type BasePlugin as t, type Tool as u, type PerformanceTimings as v, type RAGMetrics as w, type TokenMetrics as x, type RequestTrackingData as y, type ResponseTrackingData as z };
+export { type AgentData as A, type BulkOperation as B, type ClientConfig as C, type DataTransform as D, type TokenMetrics as E, type RequestTrackingData as F, type ResponseTrackingData as G, type ErrorTrackingData as H, type IngestOptions as I, type PluginRegistryInterface as J, AgentSDKError as K, AgentNotFoundError as L, type MessageRole as M, ThreadNotFoundError as N, ProviderNotFoundError as O, type ProviderConfig as P, InvalidConfigError as Q, type RAGDocument as R, type StoredPluginConfig as S, type ThreadData as T, type URLSource as U, MongoDBStorage as V, MemoryStorage as W, UpstashStorage as X, type MongoDBStorageConfig as Y, type UpstashStorageConfig as Z, type ProviderType as a, type Plugin as b, type StorageAdapter as c, type AgentConfig as d, type AgentFile as e, type IngestResult as f, type BulkResult as g, type URLIngestResult as h, type ThreadConfig as i, type MessageAttachment as j, type MessageData as k, type ChatRequest as l, type ChatResponse as m, type StreamCallbacks as n, type RAGPlugin as o, type ToolPlugin as p, type MiddlewarePlugin as q, type AnalyticsPlugin as r, type RAGContext as s, type RAGConfig as t, type BasePlugin as u, type URLSourceAuth as v, type IngestionSchedule as w, type Tool as x, type PerformanceTimings as y, type RAGMetrics as z };