agentnet 0.1.2 → 0.1.3

package/README.md

@@ -267,7 +267,7 @@ const message = new Message({
 
 // Query the agent using the client
 console.log("Sending query to the entrypoint agent...");
-const response = await client.queryIo(natsIO, 'smartchat.entrypointAgent', message); // {namespace}.{name}
+const response = await client.queryIo(natsIO, 'smartchat', 'entrypointAgent', message);
 
 // Process the response
 console.log("Agent Response:", response.getContent());

package/docs/conversation.md

@@ -0,0 +1,92 @@
+# Conversation Class
+
+The `Conversation` class manages conversation history with additional metadata for each message. It provides an improved way to handle conversations compared to a plain array, allowing for more sophisticated conversation management, including proper trimming based on message types.
+
+## Features
+
+- Store messages with additional metadata (type, timestamp)
+- Proper conversation trimming (e.g., keeping at least one user message)
+- Support for different message types (user inputs, model responses, function calls)
+- Easy serialization/deserialization
+- Backward compatibility with existing code
+
+## Usage
+
+```javascript
+import { Conversation } from 'smartagent';
+
+// Create a new conversation
+const conversation = new Conversation();
+
+// Add messages
+conversation.addUserMessage({
+  role: 'user',
+  content: 'Hello, how can you help me?'
+});
+
+conversation.addModelResponse({
+  role: 'assistant',
+  content: 'I can help with many tasks. What do you need?'
+});
+
+// Get raw conversation for LLM APIs
+const rawConversation = conversation.getRawConversation();
+
+// Get all messages with metadata
+const allMessages = conversation.getMessages();
+
+// Trim conversation while ensuring it starts with a user message
+conversation.trim(10);
+
+// Import from existing array
+conversation.importFromArray(existingArray);
+
+// Serialize/deserialize
+const serialized = conversation.serialize();
+conversation.deserialize(serialized);
+```
+
+## Integration with SessionStore
+
+The `SessionStore` class has been updated to use the `Conversation` class internally:
+
+```javascript
+import { SessionStore } from 'smartagent';
+
+const sessionStore = new SessionStore('session-id');
+
+// Load the conversation
+await sessionStore.load(store);
+
+// Get the conversation manager
+const conversationManager = sessionStore.getConversationManager();
+
+// Add a message
+conversationManager.addUserMessage({ /* message */ });
+
+// Trim with proper handling
+sessionStore.trimConversation(10);
+
+// Save conversation
+await sessionStore.dump(store);
+```
+
+## Message Types
+
+The Conversation class tracks different message types:
+
+- `user_input`: Messages from the user
+- `model_response`: Responses from the LLM model
+- `function_call`: Function/tool calls from the model
+- `function_result`: Results of function/tool calls
+
+## Compatibility
+
+The implementation maintains backward compatibility with existing code that uses plain arrays for conversations. The LLM implementations (`GeminiLLM` and `OpenAILLM`) have been updated to properly handle both plain arrays and `Conversation` objects.
+
+## Benefits
+
+- **Better trimming**: Trimming maintains conversation context by ensuring at least one user message remains
+- **Type awareness**: Messages are tracked by type, making it easier to understand the conversation flow
+- **Metadata**: Additional information can be stored with each message
+- **Serialization**: Easy serialization and deserialization for storage 

package/examples/conversation-usage.js

@@ -0,0 +1,68 @@
+import { Conversation, SessionStore } from '../src/index.js';
+import { MemoryStore } from '../src/utils/store.js';
+
+// Example of using the Conversation class
+async function conversationExample() {
+  // Create a new conversation
+  const conversation = new Conversation();
+
+  // Add user and model messages
+  conversation.addUserMessage({
+    role: 'user',
+    content: 'Hello, I need help with my project.'
+  });
+
+  conversation.addModelResponse({
+    role: 'assistant',
+    content: 'I\'d be happy to help! What kind of project are you working on?'
+  });
+
+  // Get the raw conversation (format needed by LLMs)
+  const rawConversation = conversation.getRawConversation();
+  console.log('Raw conversation:', JSON.stringify(rawConversation, null, 2));
+
+  // Get full messages with metadata
+  const messages = conversation.getMessages();
+  console.log('Messages with metadata:', JSON.stringify(messages, null, 2));
+
+  // Trim the conversation
+  conversation.trim(5);
+  console.log('After trimming:', JSON.stringify(conversation.getMessages(), null, 2));
+
+  // Import from existing array
+  const existingConversation = [
+    { role: 'user', content: 'What is the weather today?' },
+    { role: 'assistant', content: 'I don\'t have access to real-time weather data.' },
+    { role: 'user', content: 'Can you help me with coding instead?' }
+  ];
+
+  conversation.importFromArray(existingConversation);
+  console.log('After importing:', JSON.stringify(conversation.getRawConversation(), null, 2));
+
+  // SessionStore example
+  const sessionStore = new SessionStore('example-session');
+  const store = new MemoryStore();
+
+  // Set conversation and state
+  sessionStore.setConversation(conversation);
+  sessionStore.setState({ userId: '12345', lastActivity: new Date().toISOString() });
+
+  // Trim conversation to keep only the latest 2 messages
+  sessionStore.trimConversation(2);
+  console.log('After trimming in SessionStore:', 
+    JSON.stringify(sessionStore.getConversation(), null, 2));
+
+  // Save to store
+  await sessionStore.dump(store);
+
+  // Load from store
+  const newSessionStore = new SessionStore('example-session');
+  await newSessionStore.load(store);
+
+  console.log('Loaded conversation:', 
+    JSON.stringify(newSessionStore.getConversation(), null, 2));
+  console.log('Loaded state:', 
+    JSON.stringify(newSessionStore.getState(), null, 2));
+}
+
+conversationExample().catch(console.error); 

package/examples/customer-support/index.js

@@ -349,7 +349,7 @@ async function main() {
   
   // Start with the triage agent
   const client = AgentClient();
-  const res = await client.queryIo(natsIO, 'customerSupport.triageAgent', new Message({
+  const res = await client.queryIo(natsIO, 'customerSupport', 'triageAgent', new Message({
     content: customerQuery,
     session: {
       id: caseId,
@@ -363,7 +363,7 @@ async function main() {
   
   // For demonstration purposes, let's simulate a complete flow through the technical agent
   console.log("\nRouting to Technical Agent...");
-  const res2 = await client.queryIo(natsIO, 'customerSupport.technicalAgent', new Message({
+  const res2 = await client.queryIo(natsIO, 'customerSupport', 'technicalAgent', new Message({
     content: customerQuery,
     session: {
         id: caseId,
@@ -388,7 +388,7 @@ async function main() {
   
   // Now follow up with the customer
   console.log("\nFollowing up with customer after resolution...");
-  const res3 = await client.queryIo(natsIO, 'customerSupport.followupAgent', new Message({
+  const res3 = await client.queryIo(natsIO, 'customerSupport', 'followupAgent', new Message({
     content: `Please follow up on case ${caseId}`,
       session: {
         id: caseId

package/examples/event-planner/index.js

@@ -479,7 +479,7 @@ async function main() {
   const createRequest = "I need to schedule a design review meeting next Monday at 2pm for 1 hour with the design team. Today is 11th May 2025.";
   
   console.log(`User request: "${createRequest}"`);
-  const createResponse = await client.queryIo(natsIO, 'eventPlanner.plannerAgent', new Message({
+  const createResponse = await client.queryIo(natsIO, 'eventPlanner', 'plannerAgent', new Message({
     content: createRequest,
     session: {
       id: uuidv4(),
@@ -495,7 +495,7 @@ async function main() {
   const searchRequest = "Show me all meetings with Bob next month. Today is october 2023.";
   
   console.log(`User request: "${searchRequest}"`);
-  const searchResponse = await client.queryIo(natsIO, 'eventPlanner.eventFinderAgent', new Message({
+  const searchResponse = await client.queryIo(natsIO, 'eventPlanner', 'eventFinderAgent', new Message({
     content: searchRequest,
     session: {
       id: uuidv4(),
@@ -511,7 +511,7 @@ async function main() {
   const updateRequest = "Change the Weekly Team Meeting to start at 9:30am instead of 10am.";
   
   console.log(`User request: "${updateRequest}"`);
-  const updateResponse = await client.queryIo(natsIO, 'eventPlanner.plannerAgent', new Message({
+  const updateResponse = await client.queryIo(natsIO, 'eventPlanner', 'plannerAgent', new Message({
     content: updateRequest,
     session: {
       id: uuidv4(),
@@ -527,7 +527,7 @@ async function main() {
   const conflictRequest = "Do I have any scheduling conflicts next week?";
   
   console.log(`User request: "${conflictRequest}"`);
-  const conflictResponse = await client.queryIo(natsIO, 'eventPlanner.eventFinderAgent', new Message({
+  const conflictResponse = await client.queryIo(natsIO, 'eventPlanner', 'eventFinderAgent', new Message({
     content: conflictRequest,
     session: {
       id: uuidv4(),

package/examples/smartness/index.js

@@ -62,7 +62,7 @@ const message = new Message({
         id: sessionId
     }
 })
-const res = await agentClient.queryIo(io, 'smartexample.entrypoint', message)
+const res = await agentClient.queryIo(io, 'smartexample', 'entrypoint', message)
 console.log("=======\n", res.getContent())
 console.log("=======\n", res.getSession())
 
@@ -72,6 +72,6 @@ const message2 = new Message({
         id: sessionId
     }
 })
-const res2 = await agentClient.queryIo(io, 'smartexample.entrypoint', message2)
+const res2 = await agentClient.queryIo(io, 'smartexample', 'entrypoint', message2)
 console.log("=======\n", res2.getContent())
 console.log("=======\n", res2.getSession())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentnet",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "Agent library used by Smartness",
   "main": "src/index.js",

package/src/agent/client.js

@@ -1,13 +1,17 @@
 import { Message, Response } from '../index.js'
-export function AgentClient() {
+
+export function AgentClient(config = {}) {
+    const requestTimeout = config.requestTimeout || 120000
+    
     return {
         queryAgent: async (agent, input) => {
             return await agent.query(input)
         },
 
-        queryIo: async (io, target, message) => {
+        queryIo: async (io, namespace, name, message) => {
             const transport = await io.connect()
-            const response = await transport.request(target, message.serialize(), { timeout: 60000 })
+            const target = namespace + '.' + name
+            const response = await transport.request(target, message.serialize(), { timeout: requestTimeout })
             return new Response(JSON.parse(response.string()))
         }
     }

package/src/agent/executor.js

@@ -7,8 +7,8 @@ import {
 	withRetry 
 } from '../errors/index.js';
 
-const DEFAULT_TOOL_TIMEOUT = 120000;
-const DEFAULT_LLM_TIMEOUT = 120000;
+const DEFAULT_TOOL_TIMEOUT = process.env.AGENT_DEFAULT_TOOL_TIMEOUT || 120000;
+const DEFAULT_LLM_TIMEOUT = process.env.AGENT_DEFAULT_LLM_TIMEOUT || 120000;
 
 /**
  * Emits an event to the hooks system if hooks are available

package/src/index.js

@@ -9,6 +9,7 @@ import {
     memoryStore,
     session 
 } from "./store/store.js";
+import { Conversation } from "./utils/conversation.js";
 
 export const AgentLoaderFile = _AgentLoader.AgentLoaderFile
 export const AgentLoaderJSON = _AgentLoader.AgentLoaderJSON
@@ -112,4 +113,6 @@ export class Response {
         this.#content = parsed.content
         this.#session = parsed.session
     }
-}
+}
+
+export { Conversation };

package/src/llm/base.js

@@ -1,5 +1,6 @@
 import { logger } from '../utils/logger.js'
 import { LLMError } from '../errors/index.js'
+import { Conversation } from '../utils/conversation.js'
 
 /**
  * Base class for LLM implementations
@@ -47,7 +48,7 @@ export class BaseLLM {
 
   /**
    * Add a user prompt to the conversation
-   * @param {Array} conversation - The conversation history
+   * @param {Array|Conversation} conversation - The conversation history
    * @param {string} formattedPrompt - The formatted user prompt
    * @returns {Promise<void>}
    */
@@ -56,6 +57,16 @@ export class BaseLLM {
       promptPreview: formattedPrompt.substring(0, 100)
     });
     
+    // Handle both raw array and Conversation object
+    if (conversation instanceof Conversation) {
+      // Subclasses should override this to add their specific format
+      // But we'll add a generic format by default
+      conversation.addUserMessage({
+        role: 'user',
+        content: formattedPrompt
+      });
+    }
+    // For array, we rely on subclass implementations
     // Subclasses must implement appropriate conversation format
   }
 
@@ -83,10 +94,7 @@ export class BaseLLM {
    * @returns {Promise<any>} Result of the tool execution
    */
   async executeToolCall(toolCall, name, args, state, toolsAndHandoffsMap) {
-    logger.info(`Executing tool from ${this.type}`, { 
-      toolName: name,
-      argsPreview: JSON.stringify(args).substring(0, 100)
-    });
+    logger.info(`Executing tool from ${this.type} - Tool: ${name} - Args: ${JSON.stringify(args).substring(0, 100)}`);
 
     try {
       if (!toolsAndHandoffsMap[name] || !toolsAndHandoffsMap[name].function) {
@@ -104,7 +112,6 @@ export class BaseLLM {
       
       logger.debug('Tool execution successful', { toolName: name });
       return result;
-      
     } catch (error) {
       logger.error(`Error executing tool "${name}"`, error.message);
       throw error;

package/src/llm/gemini.js

@@ -2,6 +2,7 @@ import { GoogleGenAI } from '@google/genai'
 import { logger } from '../utils/logger.js'
 import { LLMError } from '../errors/index.js'
 import { BaseLLM } from './base.js'
+import { Conversation } from '../utils/conversation.js'
 
 /**
  * Gemini LLM implementation
@@ -41,7 +42,13 @@ class GeminiLLM extends BaseLLM {
    */
   async callModel(llmClientConfig, context) {
     const { client, toolsAndHandoffsMap, conversation } = context;
-    const input = { ...llmClientConfig, contents: conversation };
+    
+    // Get raw conversation if it's a Conversation object
+    const conversationArray = conversation instanceof Conversation
+      ? conversation.getRawConversation()
+      : conversation;
+      
+    const input = { ...llmClientConfig, contents: conversationArray };
 
     // Configure tools if provided
     if (input.config !== undefined && input.tools !== undefined) {
@@ -53,7 +60,7 @@ class GeminiLLM extends BaseLLM {
 
     logger.debug('Calling Gemini model', { 
       model: input.model,
-      conversationLength: conversation.length,
+      conversationLength: conversationArray.length,
       toolsCount: toolsAndHandoffsMap.tools.length
     });
     
@@ -86,7 +93,7 @@ class GeminiLLM extends BaseLLM {
    * Handle a specific tool call from Gemini response
    * @param {Object} toolCall - The tool call to process
    * @param {Object} state - Current application state
-   * @param {Array} conversation - The conversation history
+   * @param {Array|Conversation} conversation - The conversation history
    * @param {Object} toolsAndHandoffsMap - Map of available tools
    */
   async handleToolCall(toolCall, state, conversation, toolsAndHandoffsMap) {
@@ -102,8 +109,16 @@ class GeminiLLM extends BaseLLM {
         response: typeof result === 'string' ? { answer: result } : result
       };
       
-      conversation.push({ role: 'model', parts: [{ functionCall: toolCall }] });
-      conversation.push({ role: 'user', parts: [{ functionResponse: function_response_part }] });
+      const functionCallMessage = { role: 'model', parts: [{ functionCall: toolCall }] };
+      const functionResponseMessage = { role: 'user', parts: [{ functionResponse: function_response_part }] };
+      
+      if (conversation instanceof Conversation) {
+        conversation.addFunctionCall(functionCallMessage);
+        conversation.addFunctionResult(functionResponseMessage);
+      } else {
+        conversation.push(functionCallMessage);
+        conversation.push(functionResponseMessage);
+      }
       
     } catch (error) {
       // Return error as function response in Gemini-specific format
@@ -112,15 +127,23 @@ class GeminiLLM extends BaseLLM {
         response: { error: error.message }
       };
       
-      conversation.push({ role: 'model', parts: [{ functionCall: toolCall }] });
-      conversation.push({ role: 'user', parts: [{ functionResponse: errorResponse }] });
+      const functionCallMessage = { role: 'model', parts: [{ functionCall: toolCall }] };
+      const functionResponseMessage = { role: 'user', parts: [{ functionResponse: errorResponse }] };
+      
+      if (conversation instanceof Conversation) {
+        conversation.addFunctionCall(functionCallMessage);
+        conversation.addFunctionResult(functionResponseMessage);
+      } else {
+        conversation.push(functionCallMessage);
+        conversation.push(functionResponseMessage);
+      }
     }
   }
 
   /**
    * Processes the model response, handling text responses and function calls
    * @param {Object} state - Current application state
-   * @param {Array} conversation - The conversation history
+   * @param {Array|Conversation} conversation - The conversation history
    * @param {Object} toolsAndHandoffsMap - Map of available tools
    * @param {Object} response - The model response to process
    * @returns {Promise<string|null>} Text response or null if processing tool calls
@@ -129,6 +152,15 @@ class GeminiLLM extends BaseLLM {
     // Handle simple text response
     if (response.text !== undefined) {
       logger.debug('Gemini response contains text, returning directly');
+      
+      if (conversation instanceof Conversation) {
+        const modelResponse = {
+          role: 'model',
+          parts: [{ text: response.text }]
+        };
+        conversation.addModelResponse(modelResponse);
+      }
+      
       return response.text;
     }
     
@@ -149,17 +181,23 @@ class GeminiLLM extends BaseLLM {
 
   /**
    * Adds a user prompt to the conversation
-   * @param {Array} conversation - The conversation history
+   * @param {Array|Conversation} conversation - The conversation history
    * @param {string} formattedPrompt - The formatted user prompt
    * @returns {Promise<void>}
    */
   async prompt(conversation, formattedPrompt) {
     await super.prompt(conversation, formattedPrompt);
     
-    conversation.push({
+    const userMessage = {
       role: 'user',
       parts: [{ text: formattedPrompt }]
-    });
+    };
+    
+    if (conversation instanceof Conversation) {
+      conversation.addUserMessage(userMessage);
+    } else {
+      conversation.push(userMessage);
+    }
   }
 }
 

package/src/llm/gpt.js

@@ -2,6 +2,7 @@ import OpenAI from 'openai'
 import { logger } from '../utils/logger.js'
 import { LLMError } from '../errors/index.js'
 import { BaseLLM } from './base.js'
+import { Conversation } from '../utils/conversation.js'
 
 /**
  * OpenAI LLM implementation
@@ -43,11 +44,15 @@ class OpenAILLM extends BaseLLM {
 		const { client, toolsAndHandoffsMap, conversation } = context;
 		const input = { ...llmClientConfig };
 		input.tools = toolsAndHandoffsMap.tools;
-		input.input = conversation;
+		
+		// Get raw conversation if it's a Conversation object
+		input.input = conversation instanceof Conversation
+			? conversation.getRawConversation()
+			: conversation;
 		
 		logger.debug('Calling OpenAI model', { 
 			model: input.model,
-			conversationLength: conversation.length,
+			conversationLength: input.input.length,
 			toolsCount: toolsAndHandoffsMap.tools.length
 		});
 		//console.log(JSON.stringify(input, null, 2))
@@ -76,7 +81,7 @@ class OpenAILLM extends BaseLLM {
 	 * Handle a specific tool call from OpenAI response
 	 * @param {Object} toolCall - The tool call to process
 	 * @param {Object} state - Current application state
-	 * @param {Array} conversation - The conversation history
+	 * @param {Array|Conversation} conversation - The conversation history
 	 * @param {Object} toolsAndHandoffsMap - Map of available tools
 	 */
 	async handleToolCall(toolCall, state, conversation, toolsAndHandoffsMap) {
@@ -91,7 +96,13 @@ class OpenAILLM extends BaseLLM {
 			});
 			
 			const result = await super.executeToolCall(toolCall, name, args, state, toolsAndHandoffsMap);
-			conversation.push(toolCall);
+			
+			// Add function call to conversation
+			if (conversation instanceof Conversation) {
+				conversation.addFunctionCall(toolCall);
+			} else {
+				conversation.push(toolCall);
+			}
 			
 			const resultString = typeof result === 'string' ? result : JSON.stringify(result);
 			
@@ -100,28 +111,47 @@ class OpenAILLM extends BaseLLM {
 				resultPreview: resultString.substring(0, 100)
 			});
 			
-			conversation.push({        
+			const functionOutput = {        
 				type: "function_call_output",
 				call_id: toolCall.call_id,
 				output: resultString
-			});
+			};
+			
+			// Add function result to conversation
+			if (conversation instanceof Conversation) {
+				conversation.addFunctionResult(functionOutput);
+			} else {
+				conversation.push(functionOutput);
+			}
 		} catch (error) {
 			logger.error(`Error executing tool "${toolCall.name}"`, { error });
 			
 			// Add error as function output
-			conversation.push(toolCall);
-			conversation.push({
-				type: "function_call_output",
-				call_id: toolCall.call_id,
-				output: JSON.stringify({ error: error.message })
-			});
+			if (conversation instanceof Conversation) {
+				conversation.addFunctionCall(toolCall);
+				
+				const errorOutput = {
+					type: "function_call_output",
+					call_id: toolCall.call_id,
+					output: JSON.stringify({ error: error.message })
+				};
+				
+				conversation.addFunctionResult(errorOutput);
+			} else {
+				conversation.push(toolCall);
+				conversation.push({
+					type: "function_call_output",
+					call_id: toolCall.call_id,
+					output: JSON.stringify({ error: error.message })
+				});
+			}
 		}
 	}
 
 	/**
 	 * Processes the model response, handling text responses and function calls
 	 * @param {Object} state - Current application state
-	 * @param {Array} conversation - The conversation history
+	 * @param {Array|Conversation} conversation - The conversation history
 	 * @param {Object} toolsAndHandoffsMap - Map of available tools
 	 * @param {Object} response - The model response to process
 	 * @returns {Promise<string|null>} Text response or null if processing tool calls
@@ -129,6 +159,15 @@ class OpenAILLM extends BaseLLM {
 	async onResponse(state, conversation, toolsAndHandoffsMap, response) {
 		if (response.output_text !== undefined && response.output_text.length > 0) {
 			logger.debug('OpenAI response contains text, returning directly');
+			
+			// Add model response to conversation if using Conversation object
+			if (conversation instanceof Conversation) {
+				conversation.addModelResponse({
+					role: 'assistant',
+					content: response.output_text
+				});
+			}
+			
 			return response.output_text;
 		}
 
@@ -142,7 +181,11 @@ class OpenAILLM extends BaseLLM {
 		
 		// Add reasoning to conversation
 		for (const res of reasoning) {
-			conversation.push(res);
+			if (conversation instanceof Conversation) {
+				conversation.addModelResponse(res);
+			} else {
+				conversation.push(res);
+			}
 		}
 
 		// Process all tool calls sequentially
@@ -155,17 +198,23 @@ class OpenAILLM extends BaseLLM {
 
 	/**
 	 * Adds a user prompt to the conversation
-	 * @param {Array} conversation - The conversation history
+	 * @param {Array|Conversation} conversation - The conversation history
 	 * @param {string} formattedPrompt - The formatted user prompt
 	 * @returns {Promise<void>}
 	 */
 	async prompt(conversation, formattedPrompt) {
 		await super.prompt(conversation, formattedPrompt);
 		
-		conversation.push({
+		const userMessage = {
 			role: 'user',
 			content: formattedPrompt
-		});
+		};
+		
+		if (conversation instanceof Conversation) {
+			conversation.addUserMessage(userMessage);
+		} else {
+			conversation.push(userMessage);
+		}
 	}
 }
 

package/src/store/store.js

@@ -1,14 +1,15 @@
 import { v4 as uuid } from 'uuid'
 import { createClient } from 'redis'
 import pgp from 'pg-promise'
+import { Conversation } from '../utils/conversation.js'
 
 export function session (id) {
 	let state = {}
-	let conversation = []
+	let conversationManager = new Conversation()
 
 	return {
 		query: async function (agentInstance, input) {
-			return await agentInstance.query(state, conversation, input)
+			return await agentInstance.query(state, conversationManager.getRawConversation(), input)
 		},
 		setState: function (_state) {
 			state = _state
@@ -22,33 +23,39 @@ export function session (id) {
 			return state
 		},
 		trimConversation: function (elementsToKeep) {
-			conversation = conversation.slice(-elementsToKeep)
-			let additionalElementsToRemove = 0
-			for (const chatIndex in conversation) {
-				if (conversation[chatIndex].role !== 'user' || conversation[chatIndex].role == undefined || (conversation[chatIndex].role === 'user' && conversation[chatIndex]?.parts?.[0]?.functionResponse != null)) {
-					additionalElementsToRemove += 1
-				} else {
-					break
-				}
-			}
-			if (additionalElementsToRemove > 0) {
-				conversation = conversation.slice(additionalElementsToRemove)
-			}
+			conversationManager.trim(elementsToKeep)
 		},
 		setConversation: function (_conversation) {
-			conversation = _conversation
+			// Support both array and Conversation objects
+			if (_conversation instanceof Conversation) {
+				conversationManager = _conversation;
+			} else if (Array.isArray(_conversation)) {
+				conversationManager.importFromArray(_conversation);
+			}
 		},	
 		getConversation: function () {
-			return conversation
+			// Return raw conversation for backward compatibility
+			return conversationManager.getRawConversation()
+		},
+		getConversationManager: function() {
+			return conversationManager
 		},
 		load: async function (stateStore) {
 			const _state = await stateStore.get(id)
 			if (_state !== null) {
 				const parsedState = JSON.parse(_state)
-				conversation = parsedState.conversation || []
+				
+				// Handle both old-style conversation array and new-style serialized Conversation
+				if (parsedState.conversationData) {
+					conversationManager.deserialize(parsedState.conversationData)
+				} else if (Array.isArray(parsedState.conversation)) {
+					conversationManager.importFromArray(parsedState.conversation)
+				}
+				
 				state = parsedState.state || {}
 				return {
-					conversation: conversation,
+					// Return raw conversation for backward compatibility
+					conversation: conversationManager.getRawConversation(),
 					state: state
 				}
 			}
@@ -59,8 +66,11 @@ export function session (id) {
 		},
 		dump: async function (stateStore) {
 			return await stateStore.set(id, JSON.stringify({
-				conversation: conversation,
-				state: state				
+				// Keep conversation array for backward compatibility
+				conversation: conversationManager.getRawConversation(),
+				// Add serialized conversation data with metadata
+				conversationData: conversationManager.serialize(),
+				state: state
 			}))
 		},		
 	}

package/src/transport/nats.js

@@ -13,8 +13,8 @@ import {
 } from '../errors/index.js';
 
 // Constants
-const HEARTBEAT_INTERVAL = 1000;
-const TIMEOUT_TASK_REQUEST = 120000;
+const HEARTBEAT_INTERVAL = process.env.AGENTNET_NATS_HEARTBEAT_INTERVAL || 1000;
+const TIMEOUT_TASK_REQUEST = process.env.AGENTNET_NATS_TIMEOUT_TASK_REQUEST || 120000;
 
 /**
  * NATS implementation of the Transport interface

package/src/utils/conversation.js

@@ -0,0 +1,178 @@
+import { logger } from './logger.js';
+
+/**
+ * Class representing a conversation with additional metadata for each message
+ */
+export class Conversation {
+  /**
+   * Create a new Conversation instance
+   */
+  constructor() {
+    // The internal conversation array with metadata
+    this.messages = [];
+  }
+
+  /**
+   * Add a message to the conversation
+   * @param {Object} message - The message to add
+   * @param {Object} metadata - Additional metadata
+   * @param {string} metadata.type - Message type ('user_input', 'model_response', 'function_call', 'function_result')
+   */
+  addMessage(message, metadata = {}) {
+    this.messages.push({
+      content: message,
+      metadata: {
+        ...metadata,
+        timestamp: new Date().toISOString()
+      }
+    });
+  }
+
+  /**
+   * Add a user message to the conversation
+   * @param {Object} message - The user message
+   */
+  addUserMessage(message) {
+    this.addMessage(message, { type: 'user_input' });
+  }
+
+  /**
+   * Add a model response to the conversation
+   * @param {Object} message - The model response
+   */
+  addModelResponse(message) {
+    this.addMessage(message, { type: 'model_response' });
+  }
+
+  /**
+   * Add a function call to the conversation
+   * @param {Object} message - The function call
+   */
+  addFunctionCall(message) {
+    this.addMessage(message, { type: 'function_call' });
+  }
+
+  /**
+   * Add a function result to the conversation
+   * @param {Object} message - The function result
+   */
+  addFunctionResult(message) {
+    this.addMessage(message, { type: 'function_result' });
+  }
+
+  /**
+   * Get the conversation messages
+   * @returns {Array} The messages in the conversation
+   */
+  getMessages() {
+    return this.messages;
+  }
+
+  /**
+   * Get the raw conversation history compatible with LLM providers
+   * This strips out the metadata and returns just the message content
+   * @returns {Array} The raw conversation history
+   */
+  getRawConversation() {
+    return this.messages.map(message => message.content);
+  }
+
+  /**
+   * Set the conversation from an existing array
+   * @param {Array} conversation - Existing conversation array
+   * @param {Object} options - Import options
+   * @param {boolean} options.detectTypes - Try to automatically detect message types
+   */
+  importFromArray(conversation, options = { detectTypes: true }) {
+    this.messages = [];
+    
+    if (!Array.isArray(conversation)) {
+      logger.warn('Attempted to import non-array conversation');
+      return;
+    }
+
+    for (const message of conversation) {
+      let type = 'unknown';
+      
+      // Try to automatically detect message types if enabled
+      if (options.detectTypes) {
+        if (message.role === 'user') {
+          // Check if it's a function response (from function result)
+          if (message.parts && message.parts[0] && message.parts[0].functionResponse) {
+            type = 'function_result';
+          } else {
+            type = 'user_input';
+          }
+        } else if (message.role === 'model' || message.role === 'assistant') {
+          // Check if it's a function call
+          if ((message.parts && message.parts[0] && message.parts[0].functionCall) || 
+              message.type === 'function_call') {
+            type = 'function_call';
+          } else {
+            type = 'model_response';
+          }
+        } else if (message.type === 'function_call') {
+          type = 'function_call';
+        } else if (message.type === 'function_call_output') {
+          type = 'function_result';
+        }
+      }
+      
+      this.addMessage(message, { type });
+    }
+  }
+
+  /**
+   * Trim the conversation to a maximum number of elements
+   * This will keep at least one user message at the start
+   * @param {number} maxElements - Maximum number of elements to keep
+   */
+  trim(maxElements) {
+    if (this.messages.length <= maxElements) {
+      return;
+    }
+
+    // First, keep only the latest maxElements
+    this.messages = this.messages.slice(-maxElements);
+    
+    // Then, ensure we have a user message at the start
+    // Find the first user message
+    let firstUserMessageIndex = -1;
+    for (let i = 0; i < this.messages.length; i++) {
+      if (this.messages[i].metadata.type === 'user_input') {
+        firstUserMessageIndex = i;
+        break;
+      }
+    }
+    
+    // If we didn't find a user message, or it's already at the start, nothing to do
+    if (firstUserMessageIndex === -1 || firstUserMessageIndex === 0) {
+      return;
+    }
+    
+    // Otherwise, trim all messages before the first user message
+    this.messages = this.messages.slice(firstUserMessageIndex);
+  }
+
+  /**
+   * Serialize the conversation to an object
+   * @returns {Object} The serialized conversation
+   */
+  serialize() {
+    return {
+      messages: this.messages
+    };
+  }
+
+  /**
+   * Deserialize the conversation from an object
+   * @param {Object} data - The serialized conversation
+   * @returns {Conversation} The deserialized conversation
+   */
+  deserialize(data) {
+    if (data && data.messages) {
+      this.messages = data.messages;
+    }
+    return this;
+  }
+}