@igniter-js/agents 0.1.12 → 0.1.14

package/AGENTS.md

@@ -293,7 +293,7 @@ All events include contextual attributes and error details when applicable.
 
 | Package                 | Purpose                                  | Version   |
 | ----------------------- | ---------------------------------------- | --------- |
-| `@igniter-js/core`      | Base error classes and logger interfaces | `^0.4.0`  |
+| `@igniter-js/common`    | Base error classes and logger interfaces | `^0.1.0`  |
 | `@igniter-js/telemetry` | Telemetry manager integration            | `^0.1.0`  |
 | `ai`                    | Vercel AI SDK for agent runtime          | `^6.0.0`  |
 | `zod`                   | Schema validation and type inference     | `^4.0.0` |
@@ -449,7 +449,10 @@ const agent = IgniterAgent.create("weather-assistant")
   .build();
 
 const response = await agent.generate({
-  messages: [{ role: 'user', content: 'What is the weather in New York?' }]
+  chatId: 'chat_123',
+  userId: 'user_123',
+  context: {},
+  message: { role: 'user', content: 'What is the weather in New York?' }
 });
 console.log(response);
 ```
@@ -552,7 +555,10 @@ const agent = IgniterAgent.create("my-agent")
 
 // Generate conversation (auto-saves to JSON files)
 await agent.generate({
-  messages: [{ role: 'user', content: 'Hello!' }]
+  chatId: 'chat_123',
+  userId: 'user_123',
+  context: {},
+  message: { role: 'user', content: 'Hello!' }
 });
 
 // Disconnect when done (syncs remaining data)
@@ -700,8 +706,10 @@ const supportAgent = IgniterAgent.create("customer-support")
 // Handle customer message
 async function handleCustomerMessage(message: string, customerId: string) {
   const response = await supportAgent.generate({
-    messages: [{ role: 'user', content: message }],
-    options: { userId: customerId }
+    chatId: `chat_${customerId}`,
+    userId: customerId,
+    context: {},
+    message: { role: 'user', content: message }
   });
   return response;
 }
@@ -812,12 +820,10 @@ async function reviewPR(repo: string, prNumber: number) {
   `;
 
   const review = await reviewAgent.generate({
-    messages: [{ role: 'user', content: prompt }],
-    options: {
-      repo,
-      prNumber,
-      context: { type: "pr_review" },
-    }
+    chatId: `pr_${prNumber}`,
+    userId: repo,
+    context: { repo, prNumber, type: "pr_review" },
+    message: { role: 'user', content: prompt }
   });
 
   return review;
@@ -967,10 +973,10 @@ async function analyzeSalesData(query: string) {
   `;
 
   const analysis = await analysisAgent.generate({
-      prompt, 
-      options: {
-         context: { type: "data_analysis", query },
-      }
+      chatId: 'analysis_1',
+      userId: 'user_123',
+      context: { type: "data_analysis", query },
+      message: { role: 'user', content: prompt }
   });
 
   return analysis;
@@ -1047,11 +1053,10 @@ async function handleIntegrationRequest(request: IntegrationRequest) {
   }
 
   const result = await agent.generate({
-   prompt: request.description, 
-   options: {
-      context: request.metadata,
-      userId: request.userId,
-   }
+   chatId: `integration_${request.id}`,
+   userId: request.userId,
+   context: request.metadata,
+   message: { role: 'user', content: request.description }
   });
 
   // Store integration result
@@ -1231,11 +1236,10 @@ async function conductTutoringSession(studentId: string, topic: string) {
   `;
 
   const session = await tutorAgent.generate({
-   prompt: sessionPrompt, 
-   options: {
-      userId: studentId,
-      context: { type: "tutoring_session", topic },
-   }
+   chatId: `tutor_${studentId}`,
+   userId: studentId,
+   context: { type: "tutoring_session", topic },
+   message: { role: 'user', content: sessionPrompt }
   });
 
   return session;
@@ -1418,7 +1422,7 @@ The `@igniter-js/agents` package provides a comprehensive error hierarchy for pr
 
 **`IgniterAgentError`**
 
-Base error class that extends `IgniterError` from `@igniter-js/core`. All agent-related errors inherit from this class.
+Base error class that extends `IgniterError` from `@igniter-js/common`. All agent-related errors inherit from this class.
 
 ```typescript
 import { IgniterAgentError, IgniterAgentErrorCode } from '@igniter-js/agents';
@@ -1549,7 +1553,12 @@ import {
 } from '@igniter-js/agents';
 
 try {
-  await agent.generate({ messages: [...] });
+  await agent.generate({
+    chatId: 'chat_123',
+    userId: 'user_123',
+    context: {},
+    message: { role: 'user', content: 'Hello' }
+  });
 } catch (error) {
   // Safe type narrowing
   if (isIgniterAgentMCPError(error)) {
@@ -1599,7 +1608,12 @@ All errors use standardized error codes from `IgniterAgentErrorCode` enum:
 - **Example:**
   ```typescript
   try {
-    await agent.generate({ messages: [] });
+    await agent.generate({
+      chatId: 'chat_123',
+      userId: 'user_123',
+      context: {},
+      messages: []
+    });
   } catch (error) {
     if (error.code === IgniterAgentErrorCode.UNKNOWN) {
       logger.error('Unexpected error:', error.cause);
@@ -1656,7 +1670,12 @@ All errors use standardized error codes from `IgniterAgentErrorCode` enum:
     .build();
   
   await agent.start();  // Required before generate()
-  const result = await agent.generate({ messages: [...] });
+  const result = await agent.generate({
+    chatId: 'chat_123',
+    userId: 'user_123',
+    context: {},
+    message: { role: 'user', content: 'Hello' }
+  });
   ```
 
 ##### `IGNITER_AGENT_MODEL_MISSING`
@@ -1708,14 +1727,18 @@ All errors use standardized error codes from `IgniterAgentErrorCode` enum:
   
   // ✅ WORKS
   await agent.generate({
-    messages: [...],
-    options: { userId: 'user_123', chatId: 'chat_456' }
+    chatId: 'chat_456',
+    userId: 'user_123',
+    context: { userId: 'user_123', chatId: 'chat_456' },
+    message: { role: 'user', content: 'Hello' }
   });
   
   // ❌ FAILS - Missing chatId
   await agent.generate({
-    messages: [...],
-    options: { userId: 'user_123' }
+    chatId: 'chat_456',
+    userId: 'user_123',
+    context: { userId: 'user_123' },
+    message: { role: 'user', content: 'Hello' }
   });
   ```
 
@@ -1779,10 +1802,13 @@ All errors use standardized error codes from `IgniterAgentErrorCode` enum:
 - **Example:**
   ```typescript
   const result = await agent.generate({
-    messages: [{ 
-      role: 'user', 
-      content: 'Use filesystem tool to read /invalid/path' 
-    }]
+    chatId: 'chat_123',
+    userId: 'user_123',
+    context: {},
+    message: {
+      role: 'user',
+      content: 'Use filesystem tool to read /invalid/path'
+    }
   });
   // May throw MCP_TOOL_ERROR if filesystem server fails
   ```
@@ -2033,7 +2059,12 @@ import {
 } from '@igniter-js/agents';
 
 try {
-  await agent.generate({ messages: [...] });
+  await agent.generate({
+    chatId: 'chat_123',
+    userId: 'user_123',
+    context: {},
+    message: { role: 'user', content: 'Hello' }
+  });
 } catch (error) {
   if (isIgniterAgentMCPError(error)) {
     console.error(`MCP error in ${error.mcpName}:`, error.message);
@@ -2146,7 +2177,12 @@ function logAgentError(error: unknown, context: Record<string, unknown>) {
 
 // Usage
 try {
-  await agent.generate({ messages: [...] });
+  await agent.generate({
+    chatId: 'chat_123',
+    userId: 'user_123',
+    context: {},
+    message: { role: 'user', content: 'Hello' }
+  });
 } catch (error) {
   logAgentError(error, { operation: 'generate', agentName: 'assistant' });
 }
@@ -2209,14 +2245,15 @@ const agent = IgniterAgent.create("advanced-agent")
 
 // Usage with typed context
 const result = await agent.generate({
-   prompt: "perform admin cleanup",
-   options: {
-      userId: "user123",
+   chatId: 'admin_cleanup',
+   userId: "user123",
+   context: {
       tenantId: "tenant456",
       permissions: ["admin", "write"],
       database: prismaClient,
       cache: redisClient,
-   }
+   },
+   message: { role: 'user', content: "perform admin cleanup" }
 });
 ```
 
@@ -2386,12 +2423,18 @@ const manager = IgniterAgentManager.create()
 
 // Agents can now communicate with each other
 await manager.get("agent-a").generate({
-  messages: [{ role: 'user', content: 'send message to Bob: hello!' }]
+  chatId: 'chat_a',
+  userId: 'agent-a',
+  context: {},
+  message: { role: 'user', content: 'send message to Bob: hello!' }
 });
 const response = await manager
   .get("agent-b")
   .generate({
-    messages: [{ role: 'user', content: 'check for new messages' }]
+    chatId: 'chat_b',
+    userId: 'agent-b',
+    context: {},
+    message: { role: 'user', content: 'check for new messages' }
   });
 ```
 
@@ -2480,8 +2523,10 @@ class AgentPool {
     this.currentIndex = (this.currentIndex + 1) % this.agents.length;
 
     return agent.generate({
-      messages: [{ role: 'user', content: input }],
-      options: context
+      chatId: `pool_${this.currentIndex}`,
+      userId: 'pool',
+      context: context ?? {},
+      message: { role: 'user', content: input }
     });
   }
 
@@ -2591,7 +2636,10 @@ const secureAgent = IgniterAgent.create("secure-agent")
     // Require authentication for all interactions
     if (!context.authenticated) {
       await context.agent.generate({
-        messages: [{ role: 'user', content: 'authenticate with provided token first' }]
+        chatId: 'auth_prompt',
+        userId: context.userId ?? 'unknown',
+        context: {},
+        message: { role: 'user', content: 'authenticate with provided token first' }
       });
       throw new Error("Authentication required");
     }
@@ -2858,12 +2906,22 @@ await agentManager.startAll();
 const customerQuery = "I want to check the status of my order #12345";
 const response = await agentManager
   .get("customer-service")
-  .generate({ prompt: customerQuery });
+  .generate({
+    chatId: 'chat_customer',
+    userId: 'user_123',
+    context: {},
+    message: { role: 'user', content: customerQuery }
+  });
 
 const inventoryQuery = "How many units of product ABC123 are in stock?";
 const inventoryResponse = await agentManager
   .get("inventory")
-  .generate({ prompt: customerQuery });
+  .generate({
+    chatId: 'chat_inventory',
+    userId: 'user_123',
+    context: {},
+    message: { role: 'user', content: inventoryQuery }
+  });
 ```
 
 #### Advanced MCP Integration
@@ -2897,10 +2955,13 @@ const mcpAgent = IgniterAgent.create("mcp-integrated")
 
 // The agent can now use MCP tools automatically
 const result = await mcpAgent.generate({
-  messages: [{ 
-    role: 'user', 
-    content: 'Check the current git status and show me any uncommitted changes' 
-  }]
+  chatId: 'chat_123',
+  userId: 'user_123',
+  context: {},
+  message: {
+    role: 'user',
+    content: 'Check the current git status and show me any uncommitted changes'
+  }
 });
 ```
 

package/README.md

@@ -217,12 +217,13 @@ await agent.start()
 
 // Generate a response (agent chooses to use tools as needed)
 const result = await agent.generate({
-  messages: [
-    {
-      role: 'user',
-      content: 'What is the weather like in London right now?',
-    },
-  ],
+  chatId: 'chat_123',
+  userId: 'user_123',
+  context: {},
+  message: {
+    role: 'user',
+    content: 'What is the weather like in London right now?',
+  },
 })
 
 console.log(result.content)
@@ -257,15 +258,19 @@ await agent.start()
 
 // First turn
 let response = await agent.generate({
-  messages: [
-    { role: 'user', content: 'My name is Alice and I live in Paris' },
-  ],
+  chatId: 'chat_123',
+  userId: 'user_123',
+  context: {},
+  message: { role: 'user', content: 'My name is Alice and I live in Paris' },
 })
 console.log(response.content)
 
 // Second turn - agent remembers context from first turn
 response = await agent.generate({
-  messages: [{ role: 'user', content: "What's my name and where do I live?" }],
+  chatId: 'chat_123',
+  userId: 'user_123',
+  context: {},
+  message: { role: 'user', content: "What's my name and where do I live?" },
 })
 console.log(response.content) // Will reference Alice and Paris
 ```
@@ -293,13 +298,13 @@ await agent.start()
 
 // Use template with dynamic values
 const response = await agent.generate({
-  messages: [
-    { role: 'user', content: 'I need help with my order' },
-  ],
-  options: {
+  chatId: 'chat_123',
+  userId: 'user_123',
+  context: {
     company: 'TechCorp',
     tone: 'friendly and professional',
   },
+  message: { role: 'user', content: 'I need help with my order' },
 })
 
 console.log(response.content)
@@ -427,12 +432,13 @@ await productivityAgent.start()
 
 // Step 5: Use the agent
 const response = await productivityAgent.generate({
-  messages: [
-    {
-      role: 'user',
-      content: 'What are my high-priority tasks today? And add a meeting reminder.',
-    },
-  ],
+  chatId: 'chat_123',
+  userId: 'user_123',
+  context: {},
+  message: {
+    role: 'user',
+    content: 'What are my high-priority tasks today? And add a meeting reminder.',
+  },
 })
 
 console.log(response.content)
@@ -675,7 +681,10 @@ await memory.disconnect() // Flush remaining data before exit
     .build()
 
   await agent.generate({
-    messages: [{ role: 'user', content: 'I like TypeScript' }],
+    chatId: 'chat_123',
+    userId: 'user_123',
+    context: {},
+    message: { role: 'user', content: 'I like TypeScript' },
   })
 
   await memory.disconnect()
@@ -694,7 +703,10 @@ await memory.disconnect() // Flush remaining data before exit
 
   // Agent remembers "user likes TypeScript"
   const response = await agent.generate({
-    messages: [{ role: 'user', content: 'Recommend a library for me' }],
+    chatId: 'chat_123',
+    userId: 'user_123',
+    context: {},
+    message: { role: 'user', content: 'Recommend a library for me' },
   })
 }
 ```
@@ -802,9 +814,10 @@ await agent.start()
 
 // Agent can now list files, read content, etc. via MCP
 const response = await agent.generate({
-  messages: [
-    { role: 'user', content: 'List all JSON files in /tmp' },
-  ],
+  chatId: 'chat_123',
+  userId: 'user_123',
+  context: {},
+  message: { role: 'user', content: 'List all JSON files in /tmp' },
 })
 
 console.log(response.content)
@@ -943,7 +956,10 @@ async function routeRequest(request: CustomerRequest) {
   const agent = manager.getAgent(agentId)
   
   return agent.generate({
-    messages: [{ role: 'user', content: request.message }],
+    chatId: `chat_${request.id}`,
+    userId: request.userId,
+    context: {},
+    message: { role: 'user', content: request.message },
   })
 }
 ```
@@ -980,12 +996,18 @@ await sharedMemory.updateWorkingMemory({
 
 // Support agent uses this context
 const supportResponse = await manager.getAgent('support').generate({
-  messages: [{ role: 'user', content: 'I have a problem' }],
+  chatId: 'chat_support',
+  userId: 'user-123',
+  context: {},
+  message: { role: 'user', content: 'I have a problem' },
 })
 
 // Sales agent also uses this context
 const salesResponse = await manager.getAgent('sales').generate({
-  messages: [{ role: 'user', content: 'Show me upgrades' }],
+  chatId: 'chat_sales',
+  userId: 'user-123',
+  context: {},
+  message: { role: 'user', content: 'Show me upgrades' },
 })
 ```
 
@@ -1089,12 +1111,13 @@ await supportAgent.start()
 
 // Use it
 const response = await supportAgent.generate({
-  messages: [
-    {
-      role: 'user',
-      content: 'I\\'ve been charged twice for my subscription!',
-    },
-  ],
+  chatId: 'chat_support_1',
+  userId: 'user_123',
+  context: {},
+  message: {
+    role: 'user',
+    content: 'I\\'ve been charged twice for my subscription!',
+  },
 })
 
 console.log(response.content)
@@ -1157,12 +1180,13 @@ const analyticsAgent = IgniterAgent
 await analyticsAgent.start()
 
 const response = await analyticsAgent.generate({
-  messages: [
-    {
-      role: 'user',
-      content: 'Show me revenue trends for the last 30 days with a chart',
-    },
-  ],
+  chatId: 'chat_analytics_1',
+  userId: 'user_123',
+  context: {},
+  message: {
+    role: 'user',
+    content: 'Show me revenue trends for the last 30 days with a chart',
+  },
 })
 
 console.log(response.content)
@@ -1225,7 +1249,10 @@ await memory.updateWorkingMemory({
 // ✅ Always handle agent generation errors
 try {
   const response = await agent.generate({
-    messages: [...],
+    chatId: 'chat_123',
+    userId: 'user_123',
+    context: {},
+    message: { role: 'user', content: 'Hello' },
   })
 } catch (error) {
   if (error instanceof IgniterAgentError) {
@@ -1567,7 +1594,10 @@ const analysisToolForSalesAgent = IgniterAgentTool
     // Delegate to analytics agent
     const analyticsAgent = manager.getAgent('analytics')
     const result = await analyticsAgent.generate({
-      messages: [{ role: 'user', content: query }],
+      chatId: 'chat_analytics_1',
+      userId: 'user_123',
+      context: {},
+      message: { role: 'user', content: query },
     })
     return { analysis: result.content }
   })

package/dist/adapters/index.d.mts

@@ -1,2 +1,2 @@
-export { j as IgniterAgentInMemoryAdapter, l as IgniterAgentJSONFileAdapter, k as IgniterAgentJSONFileAdapterOptions } from '../index-CX4IgrRt.mjs';
+export { j as IgniterAgentInMemoryAdapter, l as IgniterAgentJSONFileAdapter, k as IgniterAgentJSONFileAdapterOptions } from '../index-CqUbHeyY.mjs';
 import 'ai';

package/dist/adapters/index.d.ts

@@ -1,2 +1,2 @@
-export { j as IgniterAgentInMemoryAdapter, l as IgniterAgentJSONFileAdapter, k as IgniterAgentJSONFileAdapterOptions } from '../index-CX4IgrRt.js';
+export { j as IgniterAgentInMemoryAdapter, l as IgniterAgentJSONFileAdapter, k as IgniterAgentJSONFileAdapterOptions } from '../index-CqUbHeyY.js';
 import 'ai';

package/dist/{index-CX4IgrRt.d.mts → index-CqUbHeyY.d.mts}

@@ -485,7 +485,7 @@ interface IgniterAgentWorkingMemoryConfig {
  * ```typescript
  * const historyConfig: IgniterAgentHistoryConfig = {
  *   enabled: true,
- *   limit: 50  // Load last 50 messages for context
+ *   limit: 50,  // Load last 50 messages for context
  * };
  * ```
  *
@@ -605,6 +605,56 @@ interface IgniterAgentGetMessagesParams {
      */
     limit?: number;
 }
+/**
+ * Parameters for searching messages in history.
+ *
+ * @public
+ */
+interface IgniterAgentSearchParams {
+    /**
+     * The chat session ID to retrieve messages from.
+     */
+    chatId: string;
+    /**
+     * Optional user ID to filter messages.
+     */
+    userId?: string;
+    /**
+     * Maximum number of messages to retrieve.
+     */
+    limit?: number;
+    /**
+     * Optional search query to filter messages.
+     */
+    search?: string;
+    /**
+     * Optional date range to filter messages.
+     */
+    dateFrom?: Date;
+    /**
+     * Optional date range to filter messages.
+     */
+    dateTo?: Date;
+}
+/**
+ * Search result interface.
+ *
+ * @public
+ */
+interface IgniterAgentSearchResult {
+    /**
+     * The message ID.
+     */
+    id: string;
+    /**
+     * The message content.
+     */
+    content: any;
+    /**
+     * The message timestamp.
+     */
+    timestamp: Date;
+}
 /**
  * Parameters for retrieving chat sessions.
  *
@@ -908,6 +958,32 @@ interface IgniterAgentMemoryProvider<TScope extends string = string, TIdentifier
      * ```
      */
     deleteChat?(chatId: string): Promise<void>;
+    /**
+     * Searches for messages in the chat history.
+     *
+     * @description
+     * Retrieves a list of messages that match the search query.
+     *
+     * @remarks
+     * This method is optional. If not implemented, search functionality
+     * will be unavailable.
+     *
+     * @param params - Search parameters
+     * @returns List of search results
+     *
+     * @example
+     * ```typescript
+     * const results = await provider.search?.({
+     *   chatId: 'chat_123',
+     *   userId: 'user_456',
+     *   limit: 10,
+     *   search: 'deployment',
+     *   dateFrom: new Date('2023-01-01'),
+     *   dateTo: new Date('2023-12-31'),
+     * });
+     * ```
+     */
+    search?(params: IgniterAgentSearchParams): Promise<IgniterAgentSearchResult[]>;
 }
 /**
  * Complete memory configuration for an IgniterAgent.
@@ -2178,4 +2254,4 @@ declare class IgniterAgentJSONFileAdapter implements IgniterAgentMemoryAdapter<I
     getStats(): Promise<IgniterAgentAdapterStats>;
 }
 
-export { type IgniterAgentAdapterStats as A, type IgniterAgentMemoryConfig as I, type IgniterAgentMemoryRuntime as a, type IgniterAgentWorkingMemoryParams as b, type IgniterAgentWorkingMemory as c, type IgniterAgentUpdateWorkingMemoryParams as d, type IgniterAgentConversationMessage as e, type IgniterAgentUIMessage as f, type IgniterAgentGetMessagesParams as g, type IgniterAgentChatSession as h, type IgniterAgentGetChatsParams as i, IgniterAgentInMemoryAdapter as j, type IgniterAgentJSONFileAdapterOptions as k, IgniterAgentJSONFileAdapter as l, type IgniterAgentMessageRole as m, type IgniterAgentMemoryScope as n, type IgniterAgentGenerateTitleConfig as o, type IgniterAgentGenerateSuggestionsConfig as p, type IgniterAgentWorkingMemoryConfig as q, type IgniterAgentHistoryConfig as r, type IgniterAgentChatsConfig as s, type IgniterAgentMemoryProvider as t, type IgniterAgentAdapterOptions as u, type IgniterAgentInMemoryAdapterOptions as v, type IgniterAgentRedisAdapterOptions as w, type IgniterAgentMemoryAdapter as x, type IgniterAgentAdapterFactory as y, type IgniterAgentAdapterBatchResult as z };
+export { type IgniterAgentAdapterFactory as A, type IgniterAgentAdapterBatchResult as B, type IgniterAgentAdapterStats as C, type IgniterAgentMemoryConfig as I, type IgniterAgentMemoryRuntime as a, type IgniterAgentWorkingMemoryParams as b, type IgniterAgentWorkingMemory as c, type IgniterAgentUpdateWorkingMemoryParams as d, type IgniterAgentConversationMessage as e, type IgniterAgentUIMessage as f, type IgniterAgentGetMessagesParams as g, type IgniterAgentChatSession as h, type IgniterAgentGetChatsParams as i, IgniterAgentInMemoryAdapter as j, type IgniterAgentJSONFileAdapterOptions as k, IgniterAgentJSONFileAdapter as l, type IgniterAgentMessageRole as m, type IgniterAgentMemoryScope as n, type IgniterAgentGenerateTitleConfig as o, type IgniterAgentGenerateSuggestionsConfig as p, type IgniterAgentWorkingMemoryConfig as q, type IgniterAgentHistoryConfig as r, type IgniterAgentChatsConfig as s, type IgniterAgentSearchParams as t, type IgniterAgentSearchResult as u, type IgniterAgentMemoryProvider as v, type IgniterAgentAdapterOptions as w, type IgniterAgentInMemoryAdapterOptions as x, type IgniterAgentRedisAdapterOptions as y, type IgniterAgentMemoryAdapter as z };