dank-ai 1.0.42 → 1.0.45

package/README.md

@@ -241,6 +241,95 @@ agent
 
 **Event Flow**: `request_output:start` → LLM Processing → `request_output` → `request_output:end` → Response Sent
 
+#### Passing Custom Data to Handlers
+
+You can pass any custom data in the request body to the `/prompt` endpoint, and it will be available in your handlers via `data.metadata`. This enables powerful use cases like user authentication, conversation tracking, RAG (Retrieval-Augmented Generation), and custom lookups.
+
+**Client Request:**
+```javascript
+// POST /prompt
+{
+  "prompt": "What's the weather today?",
+  "userId": "user-12345",
+  "conversationId": "conv-abc-xyz",
+  "sessionId": "sess-789",
+  "userPreferences": {
+    "language": "en",
+    "timezone": "America/New_York"
+  }
+}
+```
+
+**Handler Access:**
+```javascript
+agent
+  .addHandler('request_output:start', async (data) => {
+    // Access custom data via data.metadata
+    const userId = data.metadata.userId;
+    const conversationId = data.metadata.conversationId;
+    
+    // Perform authentication
+    const user = await authenticateUser(userId);
+    if (!user) throw new Error('Unauthorized');
+    
+    // Load conversation history for context
+    const history = await getConversationHistory(conversationId);
+    
+    // Perform RAG lookup
+    const relevantDocs = await vectorSearch(data.prompt, userId);
+    
+    // Enhance prompt with context
+    return {
+      prompt: `Context: ${JSON.stringify(history)}\n\nRelevant Docs: ${relevantDocs}\n\nUser Question: ${data.prompt}`
+    };
+  })
+  
+  .addHandler('request_output', async (data) => {
+    // Log with user context
+    await logInteraction({
+      userId: data.metadata.userId,
+      conversationId: data.metadata.conversationId,
+      prompt: data.prompt,
+      response: data.response,
+      timestamp: data.timestamp
+    });
+    
+    // Update user preferences based on interaction
+    if (data.metadata.userPreferences) {
+      await updateUserPreferences(data.metadata.userId, data.metadata.userPreferences);
+    }
+  });
+```
+
+**Use Cases:**
+- **User Authentication**: Pass `userId` or `apiKey` to authenticate and authorize requests
+- **Conversation Tracking**: Pass `conversationId` to maintain context across multiple requests
+- **RAG (Retrieval-Augmented Generation)**: Pass user context to fetch relevant documents from vector databases
+- **Personalization**: Pass `userPreferences` to customize responses
+- **Analytics**: Pass tracking IDs to correlate requests with user sessions
+- **Multi-tenancy**: Pass `tenantId` or `organizationId` for isolated data access
+
+**Available Data Structure:**
+```javascript
+{
+  prompt: "User's prompt",
+  metadata: {
+    // All custom fields from request body
+    userId: "...",
+    conversationId: "...",
+    // ... any other fields you pass
+  },
+  // System fields (directly on data object)
+  protocol: "http",
+  clientIp: "127.0.0.1",
+  response: "LLM response",
+  usage: { total_tokens: 150 },
+  model: "gpt-3.5-turbo",
+  processingTime: 1234,
+  timestamp: "2024-01-01T00:00:00.000Z"
+}
+```
+
 #### Tool Events (`tool:*`)
 
 ```javascript

package/docker/entrypoint.js

@@ -494,10 +494,11 @@ class AgentRuntime {
   }
 
   /**
-   * Emit an event to all matching handlers
+   * Emit an event to all matching handlers (fire-and-forget)
+   * Supports both sync and async handlers
    * Supports pattern matching for tool events
    */
-  emitEvent(eventName, data = null) {
+  async emitEvent(eventName, data = null) {
     // Find all matching handlers (exact match and pattern match)
     const matchingHandlers = [];
 
@@ -507,19 +508,27 @@ class AgentRuntime {
       }
     }
 
-    // Execute all matching handlers
-    matchingHandlers.forEach((handler) => {
+    // Execute all matching handlers (in parallel for fire-and-forget)
+    const promises = matchingHandlers.map(async (handler) => {
       try {
+        let result;
         if (typeof handler === "function") {
-          handler(data);
+          result = handler(data);
         } else if (handler.handler && typeof handler.handler === "function") {
-          handler.handler(data);
+          result = handler.handler(data);
+        }
+        // Await if handler returns a promise
+        if (result && typeof result.then === "function") {
+          await result;
         }
       } catch (error) {
         logger.error(`Error in event handler for '${eventName}':`, error);
       }
     });
 
+    // Wait for all handlers to complete
+    await Promise.all(promises);
+
     if (matchingHandlers.length > 0) {
       logger.debug(
         `Emitted event '${eventName}' to ${matchingHandlers.length} handlers`
@@ -529,8 +538,10 @@ class AgentRuntime {
 
   /**
    * Emit an event and collect responses from handlers that return modified data
+   * Supports both sync and async handlers
+   * Handlers are executed sequentially to allow proper chaining of modifications
    */
-  emitEventWithResponse(eventName, data) {
+  async emitEventWithResponse(eventName, data) {
     // Find all matching handlers (exact match and pattern match)
     const matchingHandlers = [];
 
@@ -542,8 +553,8 @@ class AgentRuntime {
 
     let modifiedData = { ...data };
 
-    // Execute all matching handlers and collect responses
-    matchingHandlers.forEach((handler) => {
+    // Execute handlers sequentially to allow chaining of modifications
+    for (const handler of matchingHandlers) {
       try {
         let result;
         if (typeof handler === "function") {
@@ -552,6 +563,11 @@ class AgentRuntime {
           result = handler.handler(modifiedData);
         }
 
+        // Await if handler returns a promise
+        if (result && typeof result.then === "function") {
+          result = await result;
+        }
+
         // If handler returns an object, merge it with the current data
         if (result && typeof result === "object" && !Array.isArray(result)) {
           modifiedData = { ...modifiedData, ...result };
@@ -559,7 +575,7 @@ class AgentRuntime {
       } catch (error) {
         logger.error(`Handler error for event '${eventName}':`, error);
       }
-    });
+    }
 
     if (matchingHandlers.length > 0) {
       logger.debug(
@@ -1193,7 +1209,7 @@ class AgentRuntime {
     this.mainApp.post("/prompt", async (req, res) => {
       logger.info(`📥 Received POST /prompt request from ${req.ip || 'unknown'}`);
       try {
-        const { prompt, conversationId, metadata } = req.body;
+        const { prompt, ...requestBodyFields } = req.body;
 
         if (!prompt) {
           return res.status(400).json({
@@ -1202,16 +1218,18 @@ class AgentRuntime {
           });
         }
 
-        const response = await this.processDirectPrompt(prompt, {
-          conversationId,
-          metadata,
+        // Build metadata object with all user-provided fields from request body (except prompt)
+        const metadata = {
+          ...requestBodyFields,
+        };
+
+        const response = await this.processDirectPrompt(prompt, metadata, {
           protocol: "http",
           clientIp: req.ip,
         });
 
         res.json({
           response: response.content,
-          conversationId: conversationId || response.conversationId,
           metadata: response.metadata,
           timestamp: new Date().toISOString(),
         });
@@ -1233,24 +1251,23 @@ class AgentRuntime {
   /**
    * Process a direct prompt and emit events
    */
-  async processDirectPrompt(prompt, context = {}) {
+  async processDirectPrompt(prompt, metadata = {}, systemFields = {}) {
     const startTime = Date.now();
-    const conversationId = context.conversationId || require("uuid").v4();
+    let finalPrompt = prompt; // Declare outside try block so it's available in catch
 
     try {
       // Emit request start event and allow handlers to modify the prompt
       const startEventData = {
         prompt,
-        conversationId,
-        context,
+        metadata,
+        ...systemFields, // protocol, clientIp, etc.
         timestamp: new Date().toISOString(),
       };
       
-      const modifiedData = this.emitEventWithResponse("request_output:start", startEventData);
+      const modifiedData = await this.emitEventWithResponse("request_output:start", startEventData);
       
       // Use modified prompt if handlers returned one, otherwise use original
-      const finalPrompt = modifiedData?.prompt || prompt;
-
+      finalPrompt = modifiedData?.prompt || prompt;
       // Process with LLM
       let response;
       if (this.llmProvider === "openai") {
@@ -1281,12 +1298,12 @@ class AgentRuntime {
       const processingTime = Date.now() - startTime;
 
       // Emit request output event
-      this.emitEvent("request_output", {
+      await this.emitEvent("request_output", {
         prompt,
         finalPrompt, // Include the final prompt that was sent to LLM
         response: response.content,
-        conversationId,
-        context,
+        metadata,
+        ...systemFields, // protocol, clientIp, etc.
         usage: response.usage,
         model: response.model,
         processingTime,
@@ -1296,11 +1313,11 @@ class AgentRuntime {
 
       // Emit end event and allow handlers to modify the response before returning
       const endEventData = {
-        conversationId,
         prompt,
         finalPrompt,
         response: response.content,
-        context,
+        metadata,
+        ...systemFields, // protocol, clientIp, etc.
         usage: response.usage,
         model: response.model,
         processingTime,
@@ -1309,14 +1326,13 @@ class AgentRuntime {
         timestamp: new Date().toISOString(),
       };
 
-      const modifiedEndData = this.emitEventWithResponse("request_output:end", endEventData);
+      const modifiedEndData = await this.emitEventWithResponse("request_output:end", endEventData);
       
       // Use the final response (potentially modified by handlers)
       const finalResponse = modifiedEndData.response || response.content;
 
       return {
         content: finalResponse,
-        conversationId,
         metadata: {
           usage: response.usage,
           model: response.model,
@@ -1328,11 +1344,11 @@ class AgentRuntime {
       const processingTime = Date.now() - startTime;
 
       // Emit error event
-      this.emitEvent("request_output:error", {
+      await this.emitEvent("request_output:error", {
         prompt,
         finalPrompt,
-        conversationId,
-        context,
+        metadata,
+        ...systemFields, // protocol, clientIp, etc.
         error: error.message,
         processingTime,
         promptModified: finalPrompt !== prompt,

package/lib/docker/manager.js

@@ -1051,6 +1051,33 @@ class DockerManager {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
+  /**
+   * Escape special characters in environment variable values for Dockerfile ENV statements
+   * Handles newlines, quotes, backslashes, and Docker variable syntax
+   * 
+   * @param {string} value - The environment variable value to escape
+   * @returns {string} - Escaped value safe for Dockerfile ENV statements
+   */
+  escapeDockerfileEnvValue(value) {
+    if (value === null || value === undefined) {
+      return '';
+    }
+    
+    return String(value)
+      // Escape backslashes first (must be first to avoid double-escaping)
+      .replace(/\\/g, '\\\\')
+      // Escape dollar signs for Dockerfile variable syntax ($VAR becomes $$VAR)
+      .replace(/\$/g, '$$$$')
+      // Escape double quotes
+      .replace(/"/g, '\\"')
+      // Escape newlines as \n (will be interpreted as newline when container reads env var)
+      .replace(/\n/g, '\\n')
+      // Escape carriage returns as \r
+      .replace(/\r/g, '\\r')
+      // Escape tabs as \t
+      .replace(/\t/g, '\\t');
+  }
+
   /**
    * Pull the base Docker image
    */
@@ -1855,7 +1882,7 @@ class DockerManager {
       envStatements = Object.entries(env)
         .map(([key, value]) => {
           // Escape special characters in values for Dockerfile ENV
-          const escapedValue = String(value).replace(/\$/g, '$$$$').replace(/"/g, '\\"');
+          const escapedValue = this.escapeDockerfileEnvValue(String(value));
           return `ENV ${key}="${escapedValue}"`;
         })
         .join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dank-ai",
-  "version": "1.0.42",
+  "version": "1.0.45",
   "description": "Dank Agent Service - Docker-based AI agent orchestration platform",
   "main": "lib/index.js",
   "exports": {