@koi-language/koi 1.0.0

package/src/runtime/action-registry.js

@@ -0,0 +1,172 @@
+/**
+ * Action Registry - Manages available actions for the LLM planner
+ *
+ * Actions are modules that define what the LLM can do in playbooks.
+ * Each action has a type, description, schema, and examples.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+class ActionRegistry {
+  constructor() {
+    this.actions = new Map(); // Map<type, actionDefinition>
+    this.actionsByIntent = new Map(); // NUEVO: Map<intent, actionDefinition>
+  }
+
+  /**
+   * Register an action
+   */
+  register(action) {
+    if (!action.type || !action.description) {
+      throw new Error('Action must have type and description');
+    }
+    this.actions.set(action.type, action);
+
+    // NUEVO: indexar también por intent
+    if (action.intent) {
+      this.actionsByIntent.set(action.intent, action);
+    }
+  }
+
+  /**
+   * Get an action by type or intent
+   */
+  get(typeOrIntent) {
+    // Intentar por intent primero (nuevo)
+    const byIntent = this.actionsByIntent.get(typeOrIntent);
+    if (byIntent) return byIntent;
+
+    // Fallback a type (legacy)
+    return this.actions.get(typeOrIntent);
+  }
+
+  /**
+   * Get all registered actions
+   */
+  getAll() {
+    return Array.from(this.actions.values());
+  }
+
+  /**
+   * Load all actions from a directory
+   */
+  async loadFromDirectory(dirPath) {
+    const files = fs.readdirSync(dirPath);
+
+    for (const file of files) {
+      if (file.endsWith('.js')) {
+        const filePath = path.join(dirPath, file);
+        try {
+          const module = await import(`file://${filePath}`);
+          const action = module.default;
+
+          if (action && action.type) {
+            this.register(action);
+          }
+        } catch (error) {
+          console.warn(`[ActionRegistry] Failed to load action from ${file}: ${error.message}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Generate LLM prompt documentation for actions
+   * @param {Agent} agent - Agent to filter actions by permissions (null = show all actions)
+   */
+  generatePromptDocumentation(agent = null) {
+    let actions = this.getAll();
+
+    // If agent is provided, filter by permissions
+    // If no agent, show all actions (for system-level operations like routing)
+    if (agent) {
+      actions = actions.filter(action => {
+        // Skip hidden actions (like call_skill which is handled via tool calling)
+        if (action.hidden) {
+          return false;
+        }
+
+        // If action has no permission requirement, it's always available
+        if (!action.permission) {
+          return true;
+        }
+
+        // Check if agent has the required permission
+        return agent.hasPermission(action.permission);
+      });
+    } else {
+      // Even without agent, filter out hidden actions
+      actions = actions.filter(action => !action.hidden);
+    }
+
+    if (actions.length === 0) {
+      return '';
+    }
+
+    let doc = '';
+
+    actions.forEach((action, index) => {
+      doc += `- { "actionType": "direct", "intent": "${action.intent || action.type}"`;
+
+      // Add required parameters
+      if (action.schema && action.schema.properties) {
+        const props = Object.keys(action.schema.properties);
+        if (props.length > 0) {
+          doc += `, ${props.map(p => `"${p}": ...`).join(', ')}`;
+        }
+      }
+
+      doc += ` } - ${action.description}\n`;
+    });
+
+    return doc;
+  }
+
+  /**
+   * Generate detailed examples for LLM prompt
+   */
+  generateExamples() {
+    const actions = this.getAll();
+    const actionsWithExamples = actions.filter(a => a.examples && a.examples.length > 0);
+
+    if (actionsWithExamples.length === 0) {
+      return '';
+    }
+
+    let examples = '\nAction Examples:\n';
+
+    actionsWithExamples.forEach(action => {
+      if (action.examples && action.examples.length > 0) {
+        examples += `\n${action.type}:\n`;
+        action.examples.forEach(example => {
+          examples += `  ${JSON.stringify(example)}\n`;
+        });
+      }
+    });
+
+    return examples;
+  }
+
+  /**
+   * Clear all registered actions
+   */
+  clear() {
+    this.actions.clear();
+  }
+}
+
+// Global singleton instance
+export const actionRegistry = new ActionRegistry();
+
+// Auto-load actions from the actions directory on module load (SYNCHRONOUSLY)
+const actionsDir = path.join(__dirname, 'actions');
+if (fs.existsSync(actionsDir)) {
+  await actionRegistry.loadFromDirectory(actionsDir).catch(err => {
+    console.warn('[ActionRegistry] Failed to auto-load actions:', err.message);
+  });
+}

package/src/runtime/actions/call-skill.js

@@ -0,0 +1,45 @@
+/**
+ * Call Skill Action - Invoke a skill
+ */
+
+export default {
+  type: 'call_skill',          // Mantener temporalmente
+  intent: 'call_skill',        // NUEVO: identificador semántico
+  description: 'Call a skill with parameters',
+  permission: 'execute', // Requires execute permission
+  hidden: true, // Don't show in LLM prompts - skills are handled via tool calling
+
+  schema: {
+    type: 'object',
+    properties: {
+      skill: {
+        type: 'string',
+        description: 'Name of the skill to call'
+      },
+      input: {
+        type: 'object',
+        description: 'Input parameters for the skill'
+      }
+    },
+    required: ['skill']
+  },
+
+  examples: [
+    { type: 'call_skill', skill: 'DataValidator', input: { data: 'user_input' } }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    const skillName = action.skill || action.name;
+    const input = action.input || action.data || {};
+
+    if (!agent.skills.includes(skillName)) {
+      throw new Error(`Agent ${agent.name} does not have skill: ${skillName}`);
+    }
+
+    // Call the skill
+    const result = await agent.callSkill(skillName, input);
+
+    return result;
+  }
+};

package/src/runtime/actions/format.js

@@ -0,0 +1,115 @@
+/**
+ * Format Action - Use LLM to transform/format data dynamically
+ */
+
+export default {
+  type: 'format',
+  intent: 'format',
+  description: 'Use LLM to format/transform data according to instructions → Returns: { formatted: "result text" }. Access with ${id.output.formatted}. IMPORTANT: format action MUST have an "id" to save the result!',
+  permission: 'execute',
+
+  schema: {
+    type: 'object',
+    properties: {
+      data: {
+        description: 'Data to format (any type: object, array, string, etc.)'
+      },
+      instruction: {
+        type: 'string',
+        description: 'Natural language instruction describing how to format the data'
+      }
+    },
+    required: ['data', 'instruction']
+  },
+
+  examples: [
+    {
+      type: 'format',
+      data: '${previousResult.users}',
+      instruction: 'Generate a markdown table with columns: Sr/Sra (deduce from name), Name, Age'
+    }
+  ],
+
+  async execute(action, agent) {
+    const { data, instruction } = action;
+
+    if (!instruction) {
+      throw new Error('Format action requires an instruction');
+    }
+
+    if (!agent.llmProvider) {
+      throw new Error('Agent does not have an LLM provider configured');
+    }
+
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`[Agent] 🎨 Formatting data with LLM (instruction: "${instruction.substring(0, 50)}...")`);
+      console.error(`[Agent] 📊 Data received:`, JSON.stringify(data, null, 2));
+    }
+
+    try {
+      // Call OpenAI directly for a simple formatting task
+      const completion = await agent.llmProvider.openai.chat.completions.create({
+        model: 'gpt-4o-mini',
+        temperature: 0.3,
+        max_tokens: 2000,
+        messages: [
+          {
+            role: 'system',
+            content: `You are a data formatter. Your job is to transform data according to user instructions.
+
+CRITICAL RULES:
+1. Return ONLY the formatted output - NO explanations, NO markdown wrapping, NO code blocks, NO JSON
+2. Follow the instruction exactly as specified
+3. NEVER generate template variables (\${...}) or placeholders ([name], {x}, [DD]) - use ACTUAL VALUES from data
+4. When calculations are needed (dates, time differences, derived values), perform them accurately
+5. Use the most authoritative data source available (e.g., birthdate over age field, timestamps over derived dates)
+6. Current date for any time-based calculations: ${new Date().toISOString().split('T')[0]}
+7. If instruction says "generate emails", "generate text", "format as", output formatted TEXT - NOT JSON or arrays
+8. Default output should be human-readable text unless instruction explicitly asks for JSON/table/specific format
+
+CALCULATION REQUIREMENTS:
+- Parse all date/time fields carefully, supporting multiple formats
+- For derived values (age, days remaining, time elapsed), calculate accurately from source data
+- When calculating age: current_year - birth_year, then subtract 1 if birthday hasn't occurred yet this year
+- Use birthdate field as authoritative source, ignore any "age" field as it may be stale
+- Verify results make logical sense (e.g., age should be positive and reasonable)
+
+EMAIL/TEXT GENERATION:
+- When generating emails or personalized text, create properly formatted text for each item
+- Include salutations, body text, and sign-offs as appropriate
+- Separate multiple emails/items with blank lines
+- Use natural, human-friendly language
+- Infer formatting details from context (e.g., "Estimado" vs "Estimada" based on names ending in 'a')`
+          },
+          {
+            role: 'user',
+            content: `IMPORTANT: Today's date is ${new Date().toISOString().split('T')[0]}. Use this for all date calculations.
+
+Data:
+${JSON.stringify(data, null, 2)}
+
+Instruction:
+${instruction}
+
+Output (formatted result only):`
+          }
+        ]
+      });
+
+      let formattedText = completion.choices[0].message.content.trim();
+
+      // Clean up any markdown code blocks that might have leaked through
+      formattedText = formattedText.replace(/^```[\w]*\n/gm, '').replace(/\n```$/gm, '');
+      formattedText = formattedText.trim();
+
+      if (process.env.KOI_DEBUG_LLM) {
+        console.error(`[Agent] ✅ Formatted ${formattedText.length} characters`);
+      }
+
+      return { formatted: formattedText };
+    } catch (error) {
+      console.error(`[Agent] ❌ Format action failed: ${error.message}`);
+      throw error;
+    }
+  }
+};

package/src/runtime/actions/print.js

@@ -0,0 +1,42 @@
+/**
+ * Print Action - Display text to console
+ */
+
+import { cliLogger } from '../cli-logger.js';
+
+export default {
+  type: 'print',          // Mantener temporalmente
+  intent: 'print',        // NUEVO: identificador semántico
+  description: 'Print directly to console (FAST - use this for all console output!)',
+  permission: 'execute', // Requires execute permission
+
+  schema: {
+    type: 'object',
+    properties: {
+      message: {
+        type: 'string',
+        description: 'Text to display on console'
+      }
+    },
+    required: ['message']
+  },
+
+  examples: [
+    { type: 'print', message: '╔══════════════════════════════════════╗' },
+    { type: 'print', message: '║  Processing...                       ║' },
+    { type: 'print', message: '╚══════════════════════════════════════╝' },
+    { type: 'print', message: '✅ Task completed successfully' },
+    { type: 'print', message: 'Found ${previousResult.count} items' }
+  ],
+
+  // Executor function - receives the action and agent context
+  async execute(action, agent) {
+    const message = action.message || action.text || action.data || '';
+
+    // Print directly to stdout (bypassing cliLogger interception)
+    cliLogger.clearProgress();
+    process.stdout.write(message + '\n');
+
+    return { printed: true, message };
+  }
+};

package/src/runtime/actions/registry-delete.js

@@ -0,0 +1,37 @@
+/**
+ * Registry Delete Action - Delete data from registry
+ */
+
+export default {
+  type: 'registry_delete',          // Mantener temporalmente
+  intent: 'registry_delete',        // NUEVO: identificador semántico
+  description: 'Delete data from the shared registry',
+  permission: 'registry:write', // Requires registry:write permission (or registry)
+
+  schema: {
+    type: 'object',
+    properties: {
+      key: {
+        type: 'string',
+        description: 'Registry key to delete (e.g., "user:123")'
+      }
+    },
+    required: ['key']
+  },
+
+  examples: [
+    { type: 'registry_delete', key: 'user:${args.id}' }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    const key = action.key;
+
+    if (!key) {
+      throw new Error('registry_delete action requires "key" field');
+    }
+
+    const deleted = await globalThis.registry.delete(key);
+    return { success: true, key, deleted };
+  }
+};

package/src/runtime/actions/registry-get.js

@@ -0,0 +1,37 @@
+/**
+ * Registry Get Action - Load data from registry
+ */
+
+export default {
+  type: 'registry_get',          // Mantener temporalmente
+  intent: 'registry_get',        // NUEVO: identificador semántico
+  description: 'Load data from the shared registry → Returns: { success, key, value, found }. Access the data with ${id.output.value} or ${id.output.value.field}',
+  permission: 'registry:read', // Requires registry:read permission (or registry)
+
+  schema: {
+    type: 'object',
+    properties: {
+      key: {
+        type: 'string',
+        description: 'Registry key to fetch (e.g., "user:123")'
+      }
+    },
+    required: ['key']
+  },
+
+  examples: [
+    { type: 'registry_get', key: 'user:${args.id}' }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    const key = action.key;
+
+    if (!key) {
+      throw new Error('registry_get action requires "key" field');
+    }
+
+    const value = await globalThis.registry.get(key);
+    return { success: true, key, value, found: value !== null };
+  }
+};

package/src/runtime/actions/registry-keys.js

@@ -0,0 +1,33 @@
+/**
+ * Registry Keys Action - List keys with prefix
+ */
+
+export default {
+  type: 'registry_keys',          // Mantener temporalmente
+  intent: 'registry_keys',        // NUEVO: identificador semántico
+  description: 'List all registry keys with optional prefix → Returns: { success, count, keys: [array of key strings] }. Access with ${id.output.keys[0]} or ${id.output.count}',
+  permission: 'registry:read', // Requires registry:read permission (or registry)
+
+  schema: {
+    type: 'object',
+    properties: {
+      prefix: {
+        type: 'string',
+        description: 'Optional prefix to filter keys (e.g., "user:")'
+      }
+    }
+  },
+
+  examples: [
+    { type: 'registry_keys', prefix: 'user:' },
+    { type: 'registry_keys', prefix: '' }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    const prefix = action.prefix || '';
+
+    const keys = await globalThis.registry.keys(prefix);
+    return { success: true, count: keys.length, keys };
+  }
+};

package/src/runtime/actions/registry-search.js

@@ -0,0 +1,34 @@
+/**
+ * Registry Search Action - Search registry with query
+ */
+
+export default {
+  type: 'registry_search',          // Mantener temporalmente
+  intent: 'registry_search',        // NUEVO: identificador semántico
+  description: 'Search registry with MongoDB-style query → Returns: { success, count, results: [array of {key, value} objects] }. Access with ${id.output.results[0].value} or ${id.output.count}',
+  permission: 'registry:read', // Requires registry:read permission (or registry)
+
+  schema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'object',
+        description: 'MongoDB-style query object (e.g., { age: { $gte: 18 } })'
+      }
+    },
+    required: ['query']
+  },
+
+  examples: [
+    { type: 'registry_search', query: { age: { $gte: 18 } } },
+    { type: 'registry_search', query: { status: 'active' } }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    const query = action.query || {};
+
+    const results = await globalThis.registry.search(query);
+    return { success: true, count: results.length, results };
+  }
+};

package/src/runtime/actions/registry-set.js

@@ -0,0 +1,50 @@
+/**
+ * Registry Set Action - Save data to registry
+ */
+
+export default {
+  type: 'registry_set',          // Mantener temporalmente
+  intent: 'registry_set',        // NUEVO: identificador semántico
+  description: 'Save data to the shared registry',
+  permission: 'registry:write', // Requires registry:write permission (or registry)
+
+  schema: {
+    type: 'object',
+    properties: {
+      key: {
+        type: 'string',
+        description: 'Registry key (e.g., "user:123")'
+      },
+      value: {
+        type: 'object',
+        description: 'Data to store'
+      }
+    },
+    required: ['key', 'value']
+  },
+
+  examples: [
+    {
+      type: 'registry_set',
+      key: 'user:${args.id}',
+      value: {
+        name: '${args.name}',
+        age: '${args.age}',
+        createdAt: '${Date.now()}'
+      }
+    }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    const key = action.key;
+    const value = action.value;
+
+    if (!key) {
+      throw new Error('registry_set action requires "key" field');
+    }
+
+    await globalThis.registry.set(key, value);
+    return { success: true, key, saved: true };
+  }
+};

package/src/runtime/actions/return.js

@@ -0,0 +1,31 @@
+/**
+ * Return Action - Return final result
+ */
+
+export default {
+  type: 'return',          // Mantener temporalmente
+  intent: 'return',        // NUEVO: identificador semántico
+  description: 'Return final result from action sequence. CRITICAL: Return RAW data structures (objects, arrays) NOT formatted strings or markdown tables. If playbook says "Return: { count, users: [array] }", return actual JSON array not a formatted table string.',
+  permission: 'execute', // Requires execute permission
+
+  schema: {
+    type: 'object',
+    properties: {
+      data: {
+        type: 'object',
+        description: 'Data to return as final result'
+      }
+    },
+    required: ['data']
+  },
+
+  examples: [
+    { type: 'return', data: { success: true, message: 'Completed' } },
+    { type: 'return', data: { user: '${previousResult.value}' } }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    return action.data || action.result || {};
+  }
+};

package/src/runtime/actions/send-message.js

@@ -0,0 +1,58 @@
+/**
+ * Send Message Action - Send message to team members
+ */
+
+export default {
+  type: 'send_message',          // Mantener temporalmente
+  intent: 'send_message',        // NUEVO: identificador semántico
+  description: 'Send message to team members (explicit team communication)',
+  permission: 'delegate', // Requires delegate permission - only orchestrators can send messages
+
+  schema: {
+    type: 'object',
+    properties: {
+      event: {
+        type: 'string',
+        description: 'Event name to trigger'
+      },
+      role: {
+        type: 'string',
+        description: 'Optional role name to filter recipients'
+      },
+      data: {
+        type: 'object',
+        description: 'Data payload to send'
+      }
+    },
+    required: ['event', 'data']
+  },
+
+  examples: [
+    { type: 'send_message', event: 'processData', role: 'Worker', data: { id: 123 } }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    if (process.env.KOI_DEBUG_LLM) {
+      const roleFilter = action.role ? ` (role: ${action.role})` : '';
+      console.error(`[Agent] 📨 ${agent.name} sending message: ${action.event}${roleFilter}`);
+    }
+
+    // Build query using peers API
+    let query = agent.peers.event(action.event);
+
+    // Add role filter if specified
+    if (action.role) {
+      query = query.role(action.role);
+    }
+
+    // Execute the query with any selector
+    const result = await query.any().execute(action.data);
+
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`[Agent] ✅ Message sent, result:`, result);
+    }
+
+    return result;
+  }
+};