@koi-language/koi 1.0.5 → 1.1.0

package/src/runtime/actions/{format.js → call-llm.js}

@@ -1,22 +1,22 @@
 /**
- * Format Action - Use LLM to transform/format data dynamically
+ * Call LLM Action - Call an LLM to process data dynamically at runtime
  */
 
 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!',
+  type: 'call_llm',
+  intent: 'call_llm',
+  description: 'Call an LLM to process data based on instructions → Returns: { result: "processed text" }. Access with ${id.output.result}. IMPORTANT: call_llm 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.)'
+        description: 'Data to process (any type: object, array, string, etc.)'
       },
       instruction: {
         type: 'string',
-        description: 'Natural language instruction describing how to format the data'
+        description: 'Natural language instruction describing what to do with the data'
       }
     },
     required: ['data', 'instruction']
@@ -24,7 +24,7 @@ export default {
 
   examples: [
     {
-      type: 'format',
+      type: 'call_llm',
       data: '${previousResult.users}',
       instruction: 'Generate a markdown table with columns: Sr/Sra (deduce from name), Name, Age'
     }
@@ -34,37 +34,23 @@ export default {
     const { data, instruction } = action;
 
     if (!instruction) {
-      throw new Error('Format action requires an instruction');
+      throw new Error('call_llm 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.
+    const systemPrompt = `You are a data processor. Your job is to process data according to user instructions.
 
 CRITICAL RULES:
-1. Return ONLY the formatted output - NO explanations, NO markdown wrapping, NO code blocks, NO JSON
+1. Return ONLY the processed result - NO explanations, NO markdown wrapping, NO code blocks, NO JSON wrapper
 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
+7. If instruction says "generate", "format as", output the result as TEXT - NOT JSON or arrays
 8. Default output should be human-readable text unless instruction explicitly asks for JSON/table/specific format
 
 CALCULATION REQUIREMENTS:
@@ -74,16 +60,15 @@ CALCULATION REQUIREMENTS:
 - 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:
+CONTENT 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.
+- Infer formatting details from context (e.g., "Estimado" vs "Estimada" based on names ending in 'a')
+- Generate DIFFERENT content each time based on the data - don't reuse the same text for different values`;
+
+    const userPrompt = `IMPORTANT: Today's date is ${new Date().toISOString().split('T')[0]}. Use this for all date calculations.
 
 Data:
 ${JSON.stringify(data, null, 2)}
@@ -91,24 +76,32 @@ ${JSON.stringify(data, null, 2)}
 Instruction:
 ${instruction}
 
-Output (formatted result only):`
-          }
-        ]
-      });
+Output (result only):`;
 
-      let formattedText = completion.choices[0].message.content.trim();
+    try {
+      // Call OpenAI with centralized logging
+      const completion = await agent.llmProvider.callOpenAI(
+        {
+          model: 'gpt-4o-mini',
+          temperature: 0.3,
+          max_tokens: 2000,
+          messages: [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userPrompt }
+          ]
+        },
+        'call_llm action'
+      );
+
+      let resultText = 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`);
-      }
+      resultText = resultText.replace(/^```[\w]*\n/gm, '').replace(/\n```$/gm, '');
+      resultText = resultText.trim();
 
-      return { formatted: formattedText };
+      return { result: resultText };
     } catch (error) {
-      console.error(`[Agent] ❌ Format action failed: ${error.message}`);
+      agent.llmProvider.logError('call_llm action failed', error);
       throw error;
     }
   }

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

@@ -0,0 +1,97 @@
+/**
+ * call_mcp action - Call a tool on an MCP (Model Context Protocol) server.
+ *
+ * Used by the LLM to invoke external tools exposed via MCP stdio servers.
+ */
+export default {
+  type: 'call_mcp',
+  intent: 'call_mcp',
+  description: 'Call a tool on an MCP server. Requires: mcp (server name), tool (tool name), input (parameters object)',
+  permission: 'execute',
+  hidden: false,
+
+  schema: {
+    type: 'object',
+    properties: {
+      mcp: { type: 'string', description: 'MCP server name' },
+      tool: { type: 'string', description: 'Tool name to invoke' },
+      input: { type: 'object', description: 'Tool input parameters' }
+    },
+    required: ['mcp', 'tool']
+  },
+
+  examples: [
+    {
+      actionType: 'direct',
+      intent: 'call_mcp',
+      mcp: 'mobileMCP',
+      tool: 'tap',
+      input: { x: 100, y: 200 }
+    },
+    {
+      actionType: 'direct',
+      intent: 'call_mcp',
+      mcp: 'mobileMCP',
+      tool: 'screenshot',
+      input: {}
+    }
+  ],
+
+  async execute(action, agent) {
+    const { mcp, tool, input = {} } = action;
+
+    if (!mcp) {
+      throw new Error('call_mcp: "mcp" field is required (MCP server name)');
+    }
+    if (!tool) {
+      throw new Error('call_mcp: "tool" field is required (tool name)');
+    }
+
+    // Verify agent has access to this MCP
+    if (agent.usesMCPNames && agent.usesMCPNames.length > 0 && !agent.usesMCPNames.includes(mcp)) {
+      throw new Error(`Agent ${agent.name} does not have access to MCP: ${mcp}. Available: ${agent.usesMCPNames.join(', ')}`);
+    }
+
+    // Get the global mcpRegistry
+    const mcpRegistry = globalThis.mcpRegistry;
+    if (!mcpRegistry) {
+      throw new Error('call_mcp: MCP registry not available. Make sure MCP servers are declared in your .koi file.');
+    }
+
+    // Check MCP server status — auto-reconnect if it crashed
+    const client = mcpRegistry.get(mcp);
+    if (!client) {
+      throw new Error(`MCP server "${mcp}" is not registered. Check your .koi file.`);
+    }
+    if (!client.initialized) {
+      if (process.env.KOI_DEBUG_LLM) {
+        console.error(`[call_mcp] MCP "${mcp}" is down, reconnecting...`);
+      }
+      await client.connect();
+    }
+
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`[call_mcp] ${mcp}.${tool}(${JSON.stringify(input).substring(0, 200)})`);
+    }
+
+    const result = await mcpRegistry.callTool(mcp, tool, input);
+
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`[call_mcp] Result: ${JSON.stringify(result).substring(0, 200)}`);
+    }
+
+    // When the MCP tool returns an error, attach recent stderr output
+    // so the LLM can see actual error details (e.g. installation commands).
+    // MCP servers often print detailed instructions to stderr but only return
+    // a summary message in the result payload.
+    if (result && result.success === false && client._stderrLines?.length > 0) {
+      const stderrContext = client._stderrLines.join('\n');
+      result.serverOutput = stderrContext;
+      if (process.env.KOI_DEBUG_LLM) {
+        console.error(`[call_mcp] Attached ${client._stderrLines.length} stderr lines to error result`);
+      }
+    }
+
+    return result;
+  }
+};

package/src/runtime/actions/if.js

@@ -0,0 +1,179 @@
+/**
+ * If Action - Conditional execution
+ */
+import { buildActionDisplay } from '../cli-display.js';
+
+export default {
+  type: 'if',
+  intent: 'if',
+  description: 'Execute actions conditionally. CONDITION: Use string "${a1.output} === \'yes\'" for exact match, OR object with llm_eval for semantic: { "llm_eval": true, "instruction": "Return true if user agrees", "data": "${a1.output.answer}" } → Returns: { executed: "then"|"else", result: ... }',
+  permission: 'execute',
+
+  schema: {
+    type: 'object',
+    properties: {
+      condition: {
+        type: 'string',
+        description: 'Condition to evaluate (e.g., "${a1.output.answer} === \'Yes\'")'
+      },
+      then: {
+        type: 'array',
+        description: 'Actions to execute if condition is true'
+      },
+      else: {
+        type: 'array',
+        description: 'Actions to execute if condition is false (optional)'
+      }
+    },
+    required: ['condition', 'then']
+  },
+
+  examples: [
+    {
+      id: 'a1',
+      intent: 'prompt_user',
+      question: 'Do you want to continue?',
+      options: ['Yes', 'No']
+    },
+    {
+      intent: 'if',
+      condition: "${a1.output.answer} === 'Yes'",
+      then: [
+        { id: 'a2', intent: 'prompt_user', question: 'What is your age?' },
+        { intent: 'print', message: 'Your age is: ${a2.output.answer}' }
+      ],
+      else: [
+        { intent: 'print', message: 'Goodbye!' }
+      ]
+    }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    const condition = action.condition || action.data?.condition || '';
+    const thenActions = action.then || action.data?.then || [];
+    const elseActions = action.else || action.data?.else || [];
+
+    if (!condition) {
+      throw new Error('if action requires a "condition" field');
+    }
+
+    // Get the current action context from the agent
+    const context = agent._currentActionContext || {
+      state: agent.state,
+      results: []
+    };
+
+    // Evaluate condition
+    let conditionResult = false;
+    try {
+      // Check if condition is LLM-evaluated (object with llm_eval: true)
+      if (typeof condition === 'object' && condition.llm_eval === true) {
+        // Show progress while evaluating condition
+        const displayText = condition.desc ? condition.desc.replace(/\.\.\.$/, '') : 'Evaluating condition';
+        cliLogger.planning(`[🤖 ${agent.name}] ${displayText}`);
+
+        // Use call_llm action to evaluate condition with LLM
+        const callLlmAction = (await import('./call-llm.js')).default;
+
+        // Resolve data references
+        const resolvedData = agent.resolveObjectReferences(condition.data || {}, context);
+
+        // Create call_llm action to evaluate condition
+        const callLlmRequest = {
+          data: resolvedData,
+          instruction: condition.instruction + "\n\nRESPOND WITH ONLY 'true' or 'false' (lowercase, no quotes, no explanation)."
+        };
+
+        const llmResult = await callLlmAction.execute(callLlmRequest, agent);
+        const resultText = llmResult.result.trim().toLowerCase();
+
+        // Clear progress
+        cliLogger.clear();
+
+        // Parse boolean result
+        conditionResult = resultText === 'true';
+      } else {
+        // Simple string condition - evaluate with JavaScript
+        conditionResult = agent.evaluateCondition(condition, context);
+      }
+    } catch (error) {
+      throw new Error(`Failed to evaluate condition: ${error.message}`);
+    }
+
+    // Execute appropriate branch
+    const actionsToExecute = conditionResult ? thenActions : elseActions;
+
+    if (!actionsToExecute || actionsToExecute.length === 0) {
+      return { executed: conditionResult ? 'then' : 'else', result: null };
+    }
+
+    // Execute actions with inherited context (so nested actions can access a1, a2, etc.)
+    // We need to execute them manually to preserve the parent context
+    const actionRegistry = (await import('../action-registry.js')).actionRegistry;
+    const cliLogger = (await import('../cli-logger.js')).cliLogger;
+
+    let result = null;
+    for (const nestedAction of actionsToExecute) {
+      // Resolve references using the parent context
+      const resolvedAction = agent.resolveActionReferences(nestedAction, context);
+
+      // Show progress
+      cliLogger.planning(buildActionDisplay(agent.name, resolvedAction));
+
+      // Check if this is a delegation action
+      if (resolvedAction.actionType === 'delegate') {
+        // Delegation: route to appropriate team member
+        result = await agent.resolveAction(resolvedAction, context);
+      } else {
+        // Direct action: Get action definition from registry
+        const actionDef = actionRegistry.get(nestedAction.intent || nestedAction.type);
+
+        if (actionDef && actionDef.execute) {
+          // Update agent's current context for nested action
+          const previousContext = agent._currentActionContext;
+          agent._currentActionContext = context;
+
+          // Execute with agent
+          result = await actionDef.execute(resolvedAction, agent);
+
+          // Restore previous context
+          agent._currentActionContext = previousContext;
+        } else {
+          cliLogger.clear();
+          throw new Error(`Action ${nestedAction.intent || nestedAction.type} not found`);
+        }
+      }
+
+      cliLogger.clear();
+
+      // Update parent context with result
+      if (result && typeof result === 'object') {
+        // Unwrap double-encoded results (LLM sometimes returns { "result": "{...json...}" })
+        if (result.result && typeof result.result === 'string' && Object.keys(result).length === 1) {
+          try {
+            const parsed = JSON.parse(result.result);
+            if (typeof parsed === 'object') {
+              result = parsed;
+            }
+          } catch (e) {
+            // Not JSON, keep as-is
+          }
+        }
+
+        const resultForContext = JSON.parse(JSON.stringify(result));
+        context.results.push(resultForContext);
+
+        // Store with action ID if provided
+        if (nestedAction.id) {
+          context[nestedAction.id] = { output: resultForContext };
+        }
+      }
+    }
+
+    return {
+      executed: conditionResult ? 'then' : 'else',
+      result: result
+    };
+  }
+};

package/src/runtime/actions/print.js

@@ -3,6 +3,7 @@
  */
 
 import { cliLogger } from '../cli-logger.js';
+import { renderMarkdown } from '../cli-markdown.js';
 
 export default {
   type: 'print',          // Mantener temporalmente
@@ -34,8 +35,9 @@ export default {
     const message = action.message || action.text || action.data || '';
 
     // Print directly to stdout (bypassing cliLogger interception)
+    // Reset any leaked ANSI styles, then print plain white (no bold)
     cliLogger.clearProgress();
-    process.stdout.write(message + '\n');
+    process.stdout.write(`\x1b[0m${renderMarkdown(message)}\n`);
 
     return { printed: true, message };
   }

package/src/runtime/actions/prompt-user.js

@@ -0,0 +1,75 @@
+/**
+ * Prompt User Action - Ask user for input via command line
+ */
+
+import { cliLogger } from '../cli-logger.js';
+import { cliSelect } from '../cli-select.js';
+import { cliInput } from '../cli-input.js';
+
+export default {
+  type: 'prompt_user',
+  intent: 'prompt_user',
+  description: 'Ask the user a question via command line. Can include "options" array for interactive menu when user must choose from a limited set (e.g., ["Sí", "No"], ["Opción A", "Opción B", "Opción C"]) - useful for Yes/No, multiple choice, etc. CRITICAL: "question" field ONLY accepts 100% static text OR ${variable} reference to call_llm result. If question needs generation/adaptation (keywords: random, relacionado, based on, adapted), you MUST use call_llm FIRST to generate it, then use ${result} here → Returns: { answer }. Access with ${id.output.answer}',
+  permission: 'execute', // Requires execute permission
+
+  schema: {
+    type: 'object',
+    properties: {
+      question: {
+        type: 'string',
+        description: 'The question to ask the user'
+      },
+      options: {
+        type: 'array',
+        description: 'Optional array of choices for interactive menu (e.g., ["Yes", "No"]). User navigates with arrows and selects with Enter.'
+      },
+      prompt: {
+        type: 'string',
+        description: 'Optional custom prompt for text input mode (defaults to "> ")'
+      }
+    },
+    required: ['question']
+  },
+
+  examples: [
+    { id: 'a1', intent: 'prompt_user', question: 'What is your name?' },
+    { intent: 'print', message: 'Hello ${a1.output.answer}!' },
+    { id: 'a2', intent: 'prompt_user', question: 'Do you want to proceed?', options: ['Yes', 'No'] },
+    { intent: 'print', message: 'You selected: ${a2.output.answer}' }
+  ],
+
+  // Executor function - receives the action and agent context
+  async execute(action, agent) {
+    const question = action.question || action.data?.question || '';
+    const options = action.options || action.data?.options || null;
+    const promptText = action.prompt || action.data?.prompt || '> ';
+
+    if (!question) {
+      throw new Error('prompt_user action requires a "question" field');
+    }
+
+    // Clear any progress indicators
+    cliLogger.clearProgress();
+
+    // If options are provided, show interactive menu
+    if (options && Array.isArray(options) && options.length > 0) {
+      const value = await cliSelect(question, options.map((opt) => ({
+        title: opt,
+        value: opt
+      })));
+
+      // Return the selected option
+      return { answer: value || options[0] };
+    }
+
+    // Text input mode with rich line editor
+    // Print the question in plain white (agent talking)
+    process.stdout.write(`\n\x1b[0m${question}\n`);
+
+    // Show rich input with block cursor
+    const answer = await cliInput(promptText);
+
+    // Return the user's answer
+    return { answer };
+  }
+};

package/src/runtime/actions/repeat.js

@@ -0,0 +1,147 @@
+/**
+ * Repeat Action - Execute actions N times
+ */
+import { buildActionDisplay } from '../cli-display.js';
+
+export default {
+  type: 'repeat',
+  intent: 'repeat',
+  description: 'Execute actions a fixed number of times. Use for "ask 3 times", "do X times" → Returns: { iterations: N, results: [array of results] }',
+  permission: 'execute',
+
+  schema: {
+    type: 'object',
+    properties: {
+      count: {
+        type: 'number',
+        description: 'Number of times to repeat (e.g., 3)'
+      },
+      actions: {
+        type: 'array',
+        description: 'Actions to execute in each iteration'
+      }
+    },
+    required: ['count', 'actions']
+  },
+
+  examples: [
+    {
+      intent: 'repeat',
+      count: 3,
+      actions: [
+        { id: 'a1', intent: 'prompt_user', question: '¿Cuántos años tienes?' },
+        { intent: 'print', message: 'Respuesta ${iteration}: ${a1.output.answer}' }
+      ]
+    }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    const count = action.count || action.data?.count || 1;
+    const actions = action.actions || action.data?.actions || [];
+
+    if (!actions || actions.length === 0) {
+      throw new Error('repeat action requires an "actions" array');
+    }
+
+    if (typeof count !== 'number' || count < 1) {
+      throw new Error('repeat action requires a positive number for "count"');
+    }
+
+    // Get the current action context from the agent
+    const context = agent._currentActionContext || {
+      state: agent.state,
+      results: []
+    };
+
+    // Execute actions with inherited context
+    const actionRegistry = (await import('../action-registry.js')).actionRegistry;
+    const cliLogger = (await import('../cli-logger.js')).cliLogger;
+
+    const allResults = [];
+
+    for (let i = 0; i < count; i++) {
+      // Create iteration context with current iteration number
+      const iterationContext = {
+        ...context,
+        iteration: i + 1,  // 1-based for user-friendly display
+        iterationIndex: i  // 0-based for array access
+      };
+
+      for (const nestedAction of actions) {
+        // Resolve references using the iteration context
+        const resolvedAction = agent.resolveActionReferences(nestedAction, iterationContext);
+
+        // Show progress
+        cliLogger.planning(buildActionDisplay(agent.name, resolvedAction));
+
+        let result;
+
+        // Check if this is a delegation action
+        if (resolvedAction.actionType === 'delegate') {
+          // Delegation: route to appropriate team member
+          result = await agent.resolveAction(resolvedAction, iterationContext);
+        } else {
+          // Direct action: Get action definition from registry
+          const actionDef = actionRegistry.get(nestedAction.intent || nestedAction.type);
+
+          if (actionDef && actionDef.execute) {
+            // Update agent's current context for nested action
+            const previousContext = agent._currentActionContext;
+            agent._currentActionContext = iterationContext;
+
+            // Execute with agent
+            result = await actionDef.execute(resolvedAction, agent);
+
+            // Restore previous context
+            agent._currentActionContext = previousContext;
+          } else {
+            cliLogger.clear();
+            throw new Error(`Action ${nestedAction.intent || nestedAction.type} not found`);
+          }
+        }
+
+        cliLogger.clear();
+
+        // Update iteration context with result
+        if (result && typeof result === 'object') {
+          // Unwrap double-encoded results (LLM sometimes returns { "result": "{...json...}" })
+          if (result.result && typeof result.result === 'string' && Object.keys(result).length === 1) {
+            try {
+              const parsed = JSON.parse(result.result);
+              if (typeof parsed === 'object') {
+                result = parsed;
+              }
+            } catch (e) {
+              // Not JSON, keep as-is
+            }
+          }
+
+          const resultForContext = JSON.parse(JSON.stringify(result));
+          iterationContext.results.push(resultForContext);
+
+          // Store with action ID if provided
+          if (nestedAction.id) {
+            iterationContext[nestedAction.id] = { output: resultForContext };
+
+            // CRITICAL: Propagate action ID results back to parent context
+            // so template variables like ${right_turn.output.answer} work outside the repeat
+            context[nestedAction.id] = { output: resultForContext };
+
+            if (process.env.KOI_DEBUG_LLM) {
+              console.error(`[repeat] Stored result for ID "${nestedAction.id}":`, JSON.stringify(resultForContext));
+            }
+          }
+
+          // Track all results
+          allResults.push(resultForContext);
+        }
+      }
+    }
+
+    return {
+      iterations: count,
+      results: allResults
+    };
+  }
+};