dank-ai 1.0.36 → 1.0.38

package/lib/agent.js

@@ -6,6 +6,7 @@
  */
 
 const Joi = require('joi');
+const { validate: validateUUID } = require('uuid');
 const { DEFAULT_CONFIG, SUPPORTED_LLMS, DOCKER_CONFIG, INSTANCE_TYPES } = require('./constants');
 const { ToolRegistry, ToolExecutor } = require('./tools');
 const builtinTools = require('./tools/builtin');
@@ -15,7 +16,8 @@ class DankAgent {
     this.name = name;
     this.config = this._validateConfig(config);
     this.handlers = new Map();
-    this.id = this._generateId();
+    // id is optional during construction - must be set via setId() before use
+    this.id = this.config.id || null;
     this.status = 'defined'; // defined, building, running, stopped, error
     this.containerId = null;
     this.createdAt = new Date().toISOString();
@@ -51,6 +53,33 @@ class DankAgent {
     return this;
   }
 
+  /**
+   * Set the unique ID for this agent (required, must be UUIDv4)
+   * @param {string} id - UUIDv4 string that must be unique and never used before
+   */
+  setId(id) {
+    if (!id || typeof id !== 'string') {
+      throw new Error('Agent ID must be a non-empty string');
+    }
+    
+    const trimmedId = id.trim();
+    
+    // Validate UUIDv4 format
+    if (!validateUUID(trimmedId)) {
+      throw new Error(`Agent ID must be a valid UUIDv4. Received: ${trimmedId}`);
+    }
+    
+    // Check if it's actually v4 (UUIDv4 has '4' in the version position)
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    if (!uuidRegex.test(trimmedId)) {
+      throw new Error(`Agent ID must be a valid UUIDv4. Received: ${trimmedId}`);
+    }
+    
+    this.config.id = trimmedId;
+    this.id = trimmedId;
+    return this;
+  }
+
   /**
    * Set the system prompt for the agent
    */
@@ -535,11 +564,39 @@ class DankAgent {
     return this;
   }
 
+  /**
+   * Validate that agent ID is set (required for all operations)
+   * @private
+   */
+  _validateId() {
+    if (!this.id || !this.config.id) {
+      throw new Error(
+        `Agent ID is required for agent "${this.name}". ` +
+        `Use .setId(uuidv4) to set a unique UUIDv4 identifier. ` +
+        `Example: createAgent('${this.name}').setId(require('uuid').v4())`
+      );
+    }
+    
+    // Validate UUIDv4 format
+    const trimmedId = this.id.trim();
+    if (!validateUUID(trimmedId)) {
+      throw new Error(`Agent ID must be a valid UUIDv4 for agent "${this.name}". Received: ${trimmedId}`);
+    }
+    
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    if (!uuidRegex.test(trimmedId)) {
+      throw new Error(`Agent ID must be a valid UUIDv4 for agent "${this.name}". Received: ${trimmedId}`);
+    }
+  }
+
   /**
    * Finalize agent configuration by auto-detecting features
    * This should be called before the agent is deployed
    */
   finalize() {
+    // Validate that ID is set before finalization (REQUIRED)
+    this._validateId();
+    
     this._autoDetectFeatures();
     return this;
   }
@@ -578,6 +635,9 @@ class DankAgent {
    * Get the complete agent configuration for serialization
    */
   toConfig() {
+    // Validate ID before serialization
+    this._validateId();
+    
     return {
       name: this.name,
       id: this.id,
@@ -611,7 +671,28 @@ class DankAgent {
    * Validate agent configuration
    */
   _validateConfig(config) {
+    // ID is optional during construction - will be validated when setId() is called
+    // or when the agent is finalized/used
+    if (config.id) {
+      if (typeof config.id !== 'string') {
+        throw new Error('Agent ID must be a string');
+      }
+      
+      const trimmedId = config.id.trim();
+      if (!validateUUID(trimmedId)) {
+        throw new Error(`Agent ID must be a valid UUIDv4. Received: ${trimmedId}`);
+      }
+      
+      // Check if it's actually v4 (UUIDv4 has '4' in the version position)
+      const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+      if (!uuidRegex.test(trimmedId)) {
+        throw new Error(`Agent ID must be a valid UUIDv4. Received: ${trimmedId}`);
+      }
+    }
+    
     const schema = Joi.object({
+      id: Joi.string().optional(), // Optional during construction, required via setId()
+      
       llm: Joi.object({
         provider: Joi.string().valid(...SUPPORTED_LLMS).required(),
         apiKey: Joi.string().allow('').default(''),
@@ -686,12 +767,6 @@ class DankAgent {
     return value;
   }
 
-  /**
-   * Generate a unique ID
-   */
-  _generateId() {
-    return `agent_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-  }
 
   /**
    * Serialize handlers for storage (functions can't be serialized)

package/lib/cli/init.js

@@ -93,6 +93,11 @@ async function initCommand(projectName, options) {
     console.log(chalk.gray('  2. Run "npm install" to install dependencies'));
     console.log(chalk.gray('  3. Edit dank.config.js to configure your agents'));
     console.log(chalk.gray('  4. Run "dank run" to start your agents'));
+    console.log(chalk.yellow('\n📝 Note about Agent IDs:'));
+    console.log(chalk.gray('  - Unique UUIDv4 IDs have been generated for each agent'));
+    console.log(chalk.gray('  - These IDs are stored in dank.config.js as AGENT_IDS constants'));
+    console.log(chalk.gray('  - Once agents register with Dank Cloud, these IDs become locked to your account'));
+    console.log(chalk.gray('  - You can generate new UUIDs if needed: require(\'uuid\').v4()'));
     console.log(chalk.gray('\nFor more information, visit: https://github.com/your-org/dank'));
 
     process.exit(0);
@@ -334,6 +339,16 @@ Handle agent lifecycle and errors:
 })
 \`\`\`
 
+## Agent IDs (UUIDv4)
+
+Each agent in your project has a unique UUIDv4 identifier that is automatically generated when you initialize your project. These IDs are stored in \`dank.config.js\` as constants in the \`AGENT_IDS\` object.
+
+**Important Notes:**
+- Agent IDs are generated automatically during project initialization
+- These IDs uniquely identify your agents across deployments
+- Once agents register with Dank Cloud services, these IDs become locked to your account
+- You can generate new UUIDs if needed: \`require('uuid').v4()\`
+
 ## Configuration
 
 Edit \`dank.config.js\` to:
@@ -343,6 +358,7 @@ Edit \`dank.config.js\` to:
 - Configure event handlers
 - Set Docker and resource limits
 - Enable/disable communication features
+- Manage agent IDs (UUIDv4 identifiers)
 
 ## Documentation
 

package/lib/cli/production-build.js

@@ -12,6 +12,15 @@ const analytics = require('../analytics');
  * Extract deployment metadata from an agent configuration
  */
 function extractAgentMetadata(agent, buildOptions, imageName) {
+  // Validate that agent ID is set (required)
+  if (!agent.id || !agent.config?.id) {
+    throw new Error(
+      `Agent ID is required for agent "${agent.name}". ` +
+      `Use .setId(uuidv4) to set a unique UUIDv4 identifier. ` +
+      `Example: createAgent('${agent.name}').setId(require('uuid').v4())`
+    );
+  }
+  
   const config = agent.config || {};
   const dockerConfig = config.docker || {};
   const communication = config.communication || {};
@@ -91,6 +100,7 @@ function extractAgentMetadata(agent, buildOptions, imageName) {
   };
 
   return {
+    id: agent.id, // Agent UUIDv4 identifier from setId()
     name: agent.name,
     imageName: imageName,
     baseImage: {

package/lib/config.js

@@ -120,6 +120,15 @@ class AgentConfig {
    * Generate environment variables for agent container
    */
   static generateContainerEnv(agent) {
+    // Validate that agent ID is set (required)
+    if (!agent.id || !agent.config?.id) {
+      throw new Error(
+        `Agent ID is required for agent "${agent.name}". ` +
+        `Use .setId(uuidv4) to set a unique UUIDv4 identifier. ` +
+        `Example: createAgent('${agent.name}').setId(require('uuid').v4())`
+      );
+    }
+    
     const env = {
       AGENT_NAME: agent.name,
       AGENT_ID: agent.id,

package/lib/docker/manager.js

@@ -1399,9 +1399,20 @@ class DockerManager {
     });
 
     // Finalize agent configuration (auto-detect features)
+    // This will validate that agent.id is set (required)
     agent.finalize();
 
     const imageName = `dank-agent-${agent.name.toLowerCase()}`;
+    
+    // Ensure agent.id is set (should be validated by finalize(), but double-check for safety)
+    if (!agent.id) {
+      throw new Error(
+        `Agent ID is required for agent "${agent.name}". ` +
+        `Use .setId(uuidv4) to set a unique UUIDv4 identifier. ` +
+        `Example: createAgent('${agent.name}').setId(require('uuid').v4())`
+      );
+    }
+    
     const containerName = `dank-${agent.name.toLowerCase()}-${agent.id
       .split("_")
       .pop()}`;

package/lib/project.js

@@ -6,6 +6,7 @@
 
 const fs = require('fs-extra');
 const path = require('path');
+const { v4: uuidv4 } = require('uuid');
 
 class DankProject {
   constructor(name, options = {}) {
@@ -56,15 +57,33 @@ class DankProject {
     
     const requirePath = isDevelopment ? '../lib/index.js' : 'dank-ai';
     
+    // Generate UUIDv4 IDs for each agent in the template
+    const promptAgentId = uuidv4();
+    
     return `/**
  * Dank Agent Configuration
  * 
  * This file defines your AI agents and their configurations.
  * Run 'dank run' to start all defined agents.
+ * 
+ * IMPORTANT: Agent IDs (UUIDv4)
+ * ==============================
+ * Each agent has a unique UUIDv4 identifier that is generated when you initialize
+ * your project. These IDs are used to identify and track your agents.
+ * 
+ * - You can generate new UUIDv4s if needed (use: require('uuid').v4())
+ * - Once agents register with Dank Cloud services using these IDs, they become
+ *   locked in and owned by your account
  */
 
 const { createAgent } = require('${requirePath}');
 
+// Agent IDs - Generated UUIDv4 identifiers for each agent
+// These IDs are used to uniquely identify your agents across deployments
+const AGENT_IDS = {
+  PROMPT_AGENT: '${promptAgentId}'
+};
+
 module.exports = {
   // Project configuration
   name: '${this.name}',
@@ -74,6 +93,7 @@ module.exports = {
   agents: [
     // Example 1: Direct Prompting Agent with Event Handlers
     createAgent('prompt-agent')
+      .setId(AGENT_IDS.PROMPT_AGENT) // Required: Unique UUIDv4 identifier
       .setLLM('openai', {
         apiKey: process.env.OPENAI_API_KEY,
         model: 'gpt-3.5-turbo',

package/package.json

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