@koi-language/koi 1.0.5 → 1.1.0

package/src/runtime/llm-provider.js

@@ -22,7 +22,7 @@ function formatPromptForDebug(text) {
 export class LLMProvider {
   constructor(config = {}) {
     this.provider = config.provider || 'openai';
-    this.model = config.model || 'gpt-4o-mini';
+    this.model = config.model;
     this.temperature = config.temperature ?? 0.1; // Low temperature for deterministic results
     this.maxTokens = config.max_tokens || 8000; // Increased to avoid truncation of long responses
 
@@ -43,18 +43,182 @@ export class LLMProvider {
         throw new Error('ANTHROPIC_API_KEY is required for Anthropic provider');
       }
       this.anthropic = new Anthropic({ apiKey });
+    } else if (this.provider === 'gemini') {
+      const apiKey = process.env.GEMINI_API_KEY;
+      if (!apiKey) {
+        console.error('\n⚠️  GEMINI_API_KEY not found!');
+        console.error('   Set it as environment variable or create a .env file\n');
+        throw new Error('GEMINI_API_KEY is required for Gemini provider');
+      }
+      // Gemini exposes an OpenAI-compatible endpoint — reuse the OpenAI SDK
+      this.openai = new OpenAI({
+        apiKey,
+        baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/'
+      });
+    }
+  }
+
+  /**
+   * Format text for debug output with gray color
+   */
+  formatDebugText(text) {
+    const lines = text.split('\n');
+    return lines.map(line => `> \x1b[90m${line}\x1b[0m`).join('\n');
+  }
+
+  /**
+   * Log LLM request (system + user prompts)
+   */
+  logRequest(model, systemPrompt, userPrompt, context = '') {
+    if (process.env.KOI_DEBUG_LLM !== '1') return;
+
+    console.error('─'.repeat(80));
+    console.error(`[LLM Debug] Request - Model: ${model}${context ? ' | ' + context : ''}`);
+    console.error('System Prompt:');
+    console.error(this.formatDebugText(systemPrompt));
+    console.error('============');
+    console.error('User Prompt:');
+    console.error('============');
+    console.error(this.formatDebugText(userPrompt));
+    console.error('─'.repeat(80));
+  }
+
+  /**
+   * Log LLM response
+   */
+  logResponse(content, context = '') {
+    if (process.env.KOI_DEBUG_LLM !== '1') return;
+
+    console.error(`\n[LLM Debug] Response${context ? ' - ' + context : ''} (${content.length} chars)`);
+    console.error('─'.repeat(80));
+
+    // Try to format JSON for better readability
+    let formattedContent = content;
+    try {
+      const parsed = JSON.parse(content);
+      formattedContent = JSON.stringify(parsed, null, 2);
+    } catch (e) {
+      // Not JSON, use as is
+    }
+
+    const lines = formattedContent.split('\n');
+    for (const line of lines) {
+      console.error(`< \x1b[90m${line}\x1b[0m`);
+    }
+    console.error('─'.repeat(80));
+  }
+
+  /**
+   * Log simple message
+   */
+  logDebug(message) {
+    if (process.env.KOI_DEBUG_LLM !== '1') return;
+    console.error(`[LLM Debug] ${message}`);
+  }
+
+  /**
+   * Log error
+   */
+  logError(message, error) {
+    if (process.env.KOI_DEBUG_LLM !== '1') return;
+    console.error(`[LLM Debug] ERROR: ${message}`);
+    if (error) {
+      console.error(error.stack || error.message);
     }
   }
 
+  /**
+   * Simple chat completion for build-time tasks (descriptions, summaries).
+   * No system prompt injection, no JSON mode, with timeout.
+   */
+  async simpleChat(prompt, { timeoutMs = 15000 } = {}) {
+    const messages = [{ role: 'user', content: prompt }];
+
+    if (this.provider === 'openai' || this.provider === 'gemini') {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const completion = await this.openai.chat.completions.create(
+          this.buildApiParams({
+            model: this.model,
+            messages,
+            temperature: 0.1,
+            max_tokens: this.maxTokens || 150
+          }),
+          { signal: controller.signal }
+        );
+        return completion.choices[0].message.content?.trim() || '';
+      } finally {
+        clearTimeout(timer);
+      }
+    } else if (this.provider === 'anthropic') {
+      const message = await this.anthropic.messages.create({
+        model: this.model,
+        max_tokens: this.maxTokens || 150,
+        temperature: 0.1,
+        messages
+      });
+      return message.content[0].text.trim();
+    }
+    return '';
+  }
+
+  /**
+   * Call OpenAI with logging
+   * @param {Object} options - { model, messages, temperature, max_tokens, stream, response_format }
+   * @param {string} context - Context description for logging
+   * @returns {Promise} - OpenAI completion response
+   */
+  async callOpenAI(options, context = '') {
+    const { model, messages, temperature = 0, max_tokens = 4000, stream = false, response_format } = options;
+
+    // Extract prompts for logging
+    const systemPrompt = messages.find(m => m.role === 'system')?.content || '';
+    const userPrompt = messages.find(m => m.role === 'user')?.content || '';
+
+    // Log request
+    this.logRequest(model, systemPrompt, userPrompt, context);
+
+    // Make API call with buildApiParams to handle gpt-5.2
+    const completion = await this.openai.chat.completions.create(
+      this.buildApiParams({
+        model,
+        messages,
+        temperature,
+        max_tokens,
+        stream,
+        ...(response_format && { response_format })
+      })
+    );
+
+    // If not streaming, log response immediately
+    if (!stream) {
+      const content = completion.choices[0].message.content;
+      this.logResponse(content, context);
+    }
+
+    return completion;
+  }
+
+  /**
+   * Build API parameters, excluding max_tokens for gpt-5.2
+   */
+  buildApiParams(baseParams) {
+    // gpt-5.2 doesn't accept max_tokens parameter
+    if (baseParams.model === 'gpt-5.2') {
+      const { max_tokens, ...paramsWithoutMaxTokens } = baseParams;
+      return paramsWithoutMaxTokens;
+    }
+    return baseParams;
+  }
+
   async executePlanning(prompt) {
-    // Simple, fast planning call without all the overhead
-    // ALWAYS use the fastest model for planning
     try {
       let response;
 
       if (this.provider === 'openai') {
         const completion = await this.openai.chat.completions.create({
-          model: 'gpt-4o-mini',  // Force fastest model for planning
+          model: 'gpt-5.2',  // Force best model for planning
           messages: [
             {
               role: 'system',
@@ -62,8 +226,7 @@ export class LLMProvider {
             },
             { role: 'user', content: prompt }
           ],
-          temperature: 0,  // Use 0 for maximum determinism
-          max_tokens: 800
+          temperature: 0
         });
         response = completion.choices[0].message.content.trim();
       } else if (this.provider === 'anthropic') {
@@ -86,7 +249,7 @@ export class LLMProvider {
     }
   }
 
-  async executePlaybook(playbook, context = {}, agentName = null, tools = [], agent = null, fromDelegation = false, onAction = null) {
+  async executePlaybook(playbook, context = {}, agentName = null, tools = [], agent = null, fromDelegation = false, onAction = null, memory = []) {
     // Show planning animation while LLM is thinking
     // Format: [🤖 AgentName] Thinking...
     const planningPrefix = agentName ? `[🤖 ${agentName}]` : '';
@@ -112,15 +275,22 @@ Respond with ONLY valid JSON.`;
         if (useStreaming) {
           // hasTeams should only be true if agent can delegate to others
           const hasTeams = agent && agent.usesTeams && agent.usesTeams.length > 0;
-          response = await this.executeOpenAIStreaming(prompt, fromDelegation, hasTeams, playbook.length, agent, onAction);
+          response = await this.executeOpenAIStreaming(prompt, fromDelegation, hasTeams, playbook.length, agent, onAction, memory);
         } else {
-          response = await this.executeOpenAIWithTools(prompt, tools, agent, fromDelegation, playbook.length);
+          response = await this.executeOpenAIWithTools(prompt, tools, agent, fromDelegation, playbook.length, memory);
+        }
+      } else if (this.provider === 'gemini') {
+        if (useStreaming) {
+          const hasTeams = agent && agent.usesTeams && agent.usesTeams.length > 0;
+          response = await this.executeGeminiStreaming(prompt, hasTeams, agent, onAction, memory);
+        } else {
+          response = await this.executeGemini(prompt, agent, memory);
         }
       } else if (this.provider === 'anthropic') {
         if (useStreaming) {
-          response = await this.executeAnthropicStreaming(prompt, agent, onAction);
+          response = await this.executeAnthropicStreaming(prompt, agent, onAction, memory);
         } else {
-          response = await this.executeAnthropic(prompt, agent);
+          response = await this.executeAnthropic(prompt, agent, memory);
         }
       } else {
         throw new Error(`Unknown provider: ${this.provider}`);
@@ -184,7 +354,30 @@ Respond with ONLY valid JSON.`;
     }
   }
 
-  async executeOpenAI(prompt, fromDelegation = false, hasTeams = false, promptLength = 0, agent = null) {
+  /**
+   * Generate MCP tools documentation for plan-then-execute system prompts.
+   * @param {Agent} agent
+   * @returns {string}
+   */
+  _getMCPToolsDoc(agent) {
+    if (!agent?.usesMCPNames?.length) return '';
+
+    const mcpSummaries = agent.getMCPToolsSummary?.() || [];
+    if (mcpSummaries.length === 0) return '';
+
+    let doc = '\n\nMCP Server tools (use call_mcp action):\n';
+    for (const mcp of mcpSummaries) {
+      for (const tool of mcp.tools) {
+        const inputDesc = tool.inputSchema?.properties
+          ? Object.keys(tool.inputSchema.properties).map(k => `"${k}": ...`).join(', ')
+          : '...';
+        doc += `- { "actionType": "direct", "intent": "call_mcp", "mcp": "${mcp.name}", "tool": "${tool.name}", "input": { ${inputDesc} } } - ${tool.description || tool.name}\n`;
+      }
+    }
+    return doc;
+  }
+
+  async executeOpenAI(prompt, fromDelegation = false, hasTeams = false, promptLength = 0, agent = null, memory = []) {
     if (!process.env.OPENAI_API_KEY) {
       throw new Error('OPENAI_API_KEY not set in environment');
     }
@@ -205,170 +398,45 @@ CRITICAL: When delegating work that involves MULTIPLE items (e.g., "create these
 - NEVER group multiple items into one action unless the handler explicitly expects an array`
       : '';
 
-    const systemPrompt = `You are a Koi agent executor. Your job is to convert user instructions into a precise sequence of executable actions.
-
-CRITICAL RULES:
-1. Execute EVERY instruction in the user's request - do not skip any steps
-2. Return ONLY raw JSON - NO markdown, NO wrapping, NO "result" field
-3. Follow the EXACT order of instructions given by the user
-4. NEVER hardcode dynamic data - ALWAYS use template variables:
-   - ❌ WRONG: "✅ 6 users created" (hardcoded count)
-   - ✅ RIGHT: "✅ \${a1.output.count + a2.output.count + ...} users created" (dynamic)
-   - ❌ WRONG: "| Sr | Alice | 30 |" (hardcoded name/age)
-   - ✅ RIGHT: "| \${a8.output.users[0].name.endsWith('a') ? 'Sra' : 'Sr'} | \${a8.output.users[0].name} | \${a8.output.users[0].age} |"
-   - If you see "X users created" where X is dynamic, replace X with a template expression ONLY for simple arithmetic
-   - If you see "{el nombre del usuario}" in instructions, use \${actionId.output.name}, NOT a hardcoded value
-   - CRITICAL RULE - COMPLEX CALCULATIONS: If text has placeholders like {x}, {age}, {días}, {dd/mm/yyyy} that need:
-     * Age calculations from birthdates
-     * Date formatting
-     * Time differences
-     * Any arithmetic involving dates
-     → MANDATORY: Use format action, NEVER generate template expressions with Date/time calculations
-     → ❌ ABSOLUTELY WRONG: \${new Date(...).getFullYear() - ...} or any Date arithmetic in templates
-     → ✅ ALWAYS RIGHT: { "id": "formatted", "intent": "format", "data": "\${usersArray}", "instruction": "For each user calculate age from birthdate and generate email..." }, then print \${formatted.output.formatted}
-5. NEVER use .map() or arrow functions with nested template literals in template variables:
-   - ❌ WRONG: \${array.map(item => \`text \${item.field}\`).join('\\n')} (nested templates cannot be evaluated)
-   - ✅ RIGHT: Use format action to transform array data into display text
-   - When displaying tables/lists from array data: { "id": "aX", "intent": "format", "data": "\${arrayActionId.output.users}", "instruction": "Format as markdown table with columns: Sr/Sra, Name, Age. Deduce gender from name ending in 'a'" }
-   - Then print the formatted result: { "intent": "print", "message": "\${aX.output.formatted}" }
-6. When iterating over arrays, generate actions for ALL elements dynamically
-   - NEVER hardcode a fixed number of rows/items when the actual array size might differ
-7. EXTRACT ALL DATA FROM NATURAL LANGUAGE - Parse specifications carefully to get EVERY field:
-   - "Alice: id=001, age=30, email=alice@example.com" → { "name": "Alice", "id": "001", "age": 30, "email": "alice@example.com" }
-   - "Bob: id=002, de 17 años, bob@example.com" → { "name": "Bob", "id": "002", "age": 17, "email": "bob@example.com" }
-   - Pattern: "NAME: property1, property2..." means text before colon is the name
-   - Convert natural language ages: "de 17 años" → age: 17, "age is 35" → age: 35
-   - NEVER omit fields! If you see a name in the spec, include it in the data object
-8. Use "print" actions to display ALL requested output to the user
-9. ALWAYS use valid JSON - all values must be proper JSON types (strings, numbers, objects, arrays, booleans, null)
-10. EFFICIENCY: Group consecutive print actions into a single print using \\n for line breaks
-   - WRONG: Three separate prints for header lines
-   - RIGHT: One print with "Line1\\nLine2\\nLine3"
-11. EFFICIENCY - Batch Operations: When performing the same operation on multiple items, check if a batch/plural version exists:
-   - Look for plural intent names in available delegation actions: createAllUser/createAllUsers (batch) vs createUser (single)
-   - ❌ WRONG: Six separate createUser calls for 6 users
-   - ✅ RIGHT: One createAllUser call with array of all 6 users: { "actionType": "delegate", "intent": "createAllUser", "data": { "users": [{name: "Alice", id: "001", ...}, {name: "Bob", id: "002", ...}, ...] } }
-   - Apply this principle to ANY repeated operation where a batch version exists
-   - Benefits: Fewer network calls, better performance, cleaner action sequences
-12. ACTION IDs - CRITICAL: Add "id" field ONLY to actions that return DATA you need later
-   - ✅ PUT IDs ON: delegate actions, registry_get, registry_keys, registry_search (they return data)
-   - ❌ NEVER PUT IDs ON: print, log, format, update_state, registry_set, registry_delete (no useful output)
-   - Sequential IDs: a1, a2, a3, ... starting fresh for each playbook execution
-   - The "id" field goes on THE ACTION THAT PRODUCES THE DATA, not on the action that uses it!
-
-   EXAMPLES:
-   ❌ WRONG - ID on print action:
-   { "id": "a1", "actionType": "direct", "intent": "print", "message": "Creating user" },
-   { "actionType": "delegate", "intent": "createUser", "data": {...} },
-   { "actionType": "direct", "intent": "print", "message": "Name: \${a1.output.name}" } ← a1 is print, has no name field!
-
-   ✅ RIGHT - ID on data-producing action:
-   { "actionType": "direct", "intent": "print", "message": "Fetching user..." },
-   { "id": "a1", "actionType": "delegate", "intent": "getUser", "data": {"id": "001"} },
-   { "actionType": "direct", "intent": "print", "message": "Name: \${a1.output.name}" } ← a1 is getUser, has name field!
-
-13. RETURN vs FORMAT ACTIONS - CRITICAL: Know when to return raw data vs formatted output:
-   - If playbook says "Return: { count, users: [array] }" → MUST return actual JSON array, NOT a formatted string
-   - "Transform results to extract user data" from registry_search means reference the .results array directly
-   - NEVER use format action before return when the playbook asks for an array
-   - Use format action ONLY for final display output to users, NEVER for returning data structures
-
-   When playbook says "Transform results to extract user data" + "Return: { count, users: [array] }":
-   ❌ WRONG:
-   { "id": "a1", "intent": "registry_search", "query": {} },
-   { "id": "a2", "intent": "format", "data": "\${a1.output.results}", "instruction": "..." },
-   { "intent": "return", "data": { "users": "\${a2.output.formatted}" } }  ← Returns STRING!
-
-   ✅ RIGHT:
-   { "id": "a1", "intent": "registry_search", "query": {} },
-   { "intent": "return", "data": { "count": "\${a1.output.count}", "users": "\${a1.output.results}" } }  ← Returns actual array!
-
-   - registry_search already returns { results: [{key, value}, ...] }, just use that array directly
-   - The caller can access individual users with \${actionId.output.users[0].value.name}
-   - Only use format when explicitly asked to display/print formatted output
-
-${delegationNote}${teamDelegationNote}
-
-RESPONSE FORMAT (ALWAYS use this):
-{
-  "actions": [
-    { "actionType": "direct", "intent": "print", "message": "Display this to user" },
-    { "actionType": "direct", "intent": "return", "data": {...} }
-  ]
-}
-
-CORRECT EXAMPLES:
-
-Example 1 - NEVER hardcode dynamic values (CRITICAL - Follow Rule #4):
-User prompt: "Create 2 users, then show 'X users created' where X is the count"
-❌ WRONG - Hardcoded count:
-{ "actionType": "direct", "intent": "print", "message": "✅ 2 users created" }
-
-✅ RIGHT - Dynamic count:
-{ "id": "a1", "actionType": "delegate", "intent": "createUser", "data": {...} },
-{ "id": "a2", "actionType": "delegate", "intent": "createUser", "data": {...} },
-{ "actionType": "direct", "intent": "print", "message": "✅ \${a1.output.success && a2.output.success ? 2 : (a1.output.success || a2.output.success ? 1 : 0)} users created" }
-
-Example 2 - Extracting names from natural language (CRITICAL - Follow Rule #6):
-User prompt: "Create Alice: id=001, age=30, email=alice@example.com"
-❌ WRONG - Missing name: { "data": { "id": "001", "age": 30, "email": "alice@example.com" } }
-✅ RIGHT - Include name: { "data": { "name": "Alice", "id": "001", "age": 30, "email": "alice@example.com" } }
-
-Example 3 - Delegate with ID:
-{
-  "actions": [
-    { "id": "a1", "actionType": "delegate", "intent": "getUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "User: \${a1.output.name}, age \${a1.output.age}" }
-  ]
-}
+    const mcpToolsDoc = this._getMCPToolsDoc(agent);
 
-Example 4 - Multiple actions with IDs:
-{
-  "actions": [
-    { "id": "a1", "actionType": "delegate", "intent": "listUsers" },
-    { "actionType": "direct", "intent": "print", "message": "Found \${a1.output.count} users" },
-    { "id": "a2", "actionType": "delegate", "intent": "getUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "First user: \${a2.output.name}" }
-  ]
-}
+    const systemPrompt = `Convert the following instructions into executable JSON actions.
 
-Example 5 - Registry operations with IDs:
-{
-  "actions": [
-    { "id": "a1", "actionType": "direct", "intent": "registry_get", "key": "user:001" },
-    { "actionType": "direct", "intent": "print", "message": "Name: \${a1.output.value.name}" }
-  ]
-}
+OUTPUT: { "actions": [...] }
 
-Example 6 - Without IDs (when results aren't needed):
-{
+CRITICAL RULES:
+1. call_llm: ONLY when playbook says "random", "relacionado", "based on", "adapted", "generate question". If playbook can generate content directly, do NOT use call_llm.
+2. Loops: "hasta que se despida" → while with llm_eval condition
+3. IDs: Actions MUST have "id" if output will be referenced via \${id.output}
+4. Template variables ONLY in strings: "text \${var}" not \${var}
+5. Group consecutive prints with \\n
+
+WHILE LOOP EXAMPLE:
+{ "id": "name", "intent": "prompt_user", "question": "¿Cuál es tu nombre?" },
+{ "intent": "registry_set", "key": "last", "value": "\${name.output.answer}" },
+{ "intent": "while",
+  "condition": { "llm_eval": true, "instruction": "¿Continuar?", "data": "\${response.output.answer}" },
   "actions": [
-    { "actionType": "direct", "intent": "print", "message": "Hello" },
-    { "actionType": "delegate", "intent": "deleteUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "User deleted" }
+    { "id": "prev", "intent": "registry_get", "key": "last" },
+    { "id": "question", "intent": "call_llm", "data": {"answer":"\${prev.output.value}"}, "instruction": "Generate related question" },
+    { "id": "response", "intent": "prompt_user", "question": "\${question.output.result}" },
+    { "intent": "registry_set", "key": "last", "value": "\${response.output.answer}" }
   ]
 }
-
-CRITICAL: ALWAYS include "actionType" field in EVERY action (either "direct" or "delegate")
+CRITICAL: condition.data uses ID from prompt_user INSIDE loop ("response"), NOT from outside ("name")
 
 Available actions:
 ${actionRegistry.generatePromptDocumentation(agent)}
-${hasTeams && agent ? agent.getPeerCapabilitiesAsActions() : ''}
+${hasTeams && agent ? await agent.getPeerCapabilitiesAsActions() : ''}
+${mcpToolsDoc}
 
 ${hasTeams ? `\nIMPORTANT: Do NOT nest "intent" inside "data". The "intent" field must be at the top level.` : ''}
 
-Data chaining with action outputs:
-- Use \${a1.output.field} to reference the output of action a1
-- Template variables can ONLY be used INSIDE strings
-- NEVER use template variables as direct values: { "count": \${a1.output.length} } ❌ WRONG
-- ALWAYS quote them: { "count": "\${a1.output.length}" } ✅ CORRECT
-- NEVER use the word "undefined" in JSON - use null or a string instead
-
-Examples:
-- \${a1.output.count} - Access count field from action a1
-- \${a2.output.users} - Access users array from action a2
-- \${a3.output.users[0].name} - Access nested field
-- After action a5 executes, you can reference \${a5.output} in subsequent actions
+Data chaining:
+- Reference action outputs: \${actionId.output.field}
+- Template variables ONLY in strings: { "count": "\${user.output.length}" } ✅ NOT { "count": \${user.output.length} } ❌
+- Use descriptive IDs: "user", "question", "response", NOT "a1", "a2", "a3"
+- Examples: \${user.output.name}, \${question.output.result}, \${response.output.answer}
 
 CRITICAL: When instructions say "Do NOT add print actions", follow that EXACTLY - only generate the actions listed in the steps.
 When using "return" actions with data containing template variables, do NOT add intermediate print actions - they will break the data chain.
@@ -376,8 +444,8 @@ When using "return" actions with data containing template variables, do NOT add
 REMEMBER: Include print actions for ALL output the user should see, UNLESS the instructions explicitly say not to. Return valid, parseable JSON only.`;
 
 
-    // Use fastest model for delegated work or short playbooks
-    const model = fromDelegation || promptLength < 500 ? 'gpt-4o-mini' : this.model;
+    // Use agent's configured model
+    const model = this.model;
 
     if (process.env.KOI_DEBUG_LLM) {
       const agentInfo = agent ? ` | Agent: ${agent.name}` : '';
@@ -392,22 +460,25 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
       console.error('─'.repeat(80));
     }
 
-    const completion = await this.openai.chat.completions.create({
-      model,
-      messages: [
-        {
-          role: 'system',
-          content: systemPrompt
-        },
-        {
-          role: 'user',
-          content: prompt
-        }
-      ],
-      temperature: 0, // Always use 0 for maximum determinism
-      max_tokens: this.maxTokens,
-      response_format: { type: "json_object" } // Force valid JSON responses
-    });
+    const completion = await this.openai.chat.completions.create(
+      this.buildApiParams({
+        model,
+        messages: [
+          {
+            role: 'system',
+            content: systemPrompt
+          },
+          ...memory,
+          {
+            role: 'user',
+            content: prompt
+          }
+        ],
+        temperature: 0, // Always use 0 for maximum determinism
+        max_tokens: this.maxTokens,
+        response_format: { type: "json_object" } // Force valid JSON responses
+      })
+    );
 
     const content = completion.choices[0].message.content?.trim() || '';
 
@@ -424,7 +495,7 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
     return content;
   }
 
-  async executeOpenAIWithTools(prompt, tools = [], agent = null, fromDelegation = false, promptLength = 0) {
+  async executeOpenAIWithTools(prompt, tools = [], agent = null, fromDelegation = false, promptLength = 0, memory = []) {
     if (!process.env.OPENAI_API_KEY) {
       throw new Error('OPENAI_API_KEY not set in environment');
     }
@@ -434,7 +505,7 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
       // hasTeams should only be true if agent can delegate to others (uses teams as a client)
       // NOT if agent is just a member of a team (has peers)
       const hasTeams = agent && agent.usesTeams && agent.usesTeams.length > 0;
-      return await this.executeOpenAI(prompt, fromDelegation, hasTeams, promptLength, agent);
+      return await this.executeOpenAI(prompt, fromDelegation, hasTeams, promptLength, agent, memory);
     }
 
     // Convert tools to OpenAI format
@@ -546,11 +617,12 @@ You respond with valid JSON only. No markdown, no code blocks, no explanations.`
 
     const messages = [
       { role: 'system', content: systemPrompt },
+      ...memory,
       { role: 'user', content: prompt }
     ];
 
-    // Use fastest model for delegated work or short prompts
-    const model = fromDelegation || promptLength < 500 ? 'gpt-4o-mini' : this.model;
+    // Use agent's configured model
+    const model = this.model;
 
     if (process.env.KOI_DEBUG_LLM) {
       const agentInfo = agent ? ` | Agent: ${agent.name}` : '';
@@ -566,15 +638,17 @@ You respond with valid JSON only. No markdown, no code blocks, no explanations.`
     }
 
     // Call OpenAI with tools
-    let completion = await this.openai.chat.completions.create({
-      model,
-      messages,
-      tools: openAITools,
-      tool_choice: 'auto',
-      temperature: 0, // Always use 0 for maximum determinism
-      max_tokens: this.maxTokens,
-      response_format: { type: "json_object" } // Force valid JSON responses
-    });
+    let completion = await this.openai.chat.completions.create(
+      this.buildApiParams({
+        model,
+        messages,
+        tools: openAITools,
+        tool_choice: 'auto',
+        temperature: 0, // Always use 0 for maximum determinism
+        max_tokens: this.maxTokens,
+        response_format: { type: "json_object" } // Force valid JSON responses
+      })
+    );
 
     let message = completion.choices[0].message;
 
@@ -629,13 +703,15 @@ You respond with valid JSON only. No markdown, no code blocks, no explanations.`
       }
 
       // Call OpenAI again with tool results
-      completion = await this.openai.chat.completions.create({
-        model,  // Use same model as initial call
-        messages,
-        temperature: 0, // Always use 0 for maximum determinism
-        max_tokens: this.maxTokens,
-        response_format: { type: "json_object" } // Force valid JSON responses
-      });
+      completion = await this.openai.chat.completions.create(
+        this.buildApiParams({
+          model,  // Use same model as initial call
+          messages,
+          temperature: 0, // Always use 0 for maximum determinism
+          max_tokens: this.maxTokens,
+          response_format: { type: "json_object" } // Force valid JSON responses
+        })
+      );
 
       message = completion.choices[0].message;
     }
@@ -655,135 +731,52 @@ You respond with valid JSON only. No markdown, no code blocks, no explanations.`
     return finalContent;
   }
 
-  async executeAnthropic(prompt, agent = null) {
+  async executeAnthropic(prompt, agent = null, memory = []) {
     if (!process.env.ANTHROPIC_API_KEY) {
       throw new Error('ANTHROPIC_API_KEY not set in environment');
     }
 
     // Check if agent has teams for delegation
     const hasTeams = agent && agent.usesTeams && agent.usesTeams.length > 0;
+    const mcpToolsDoc = this._getMCPToolsDoc(agent);
 
-    const systemPrompt = `You are a Koi agent executor. Your job is to convert user instructions into a precise sequence of executable actions.
+    const systemPrompt = `Convert the following instructions into executable JSON actions.
 
-CRITICAL RULES:
-1. Execute EVERY instruction in the user's request - do not skip any steps
-2. Return ONLY raw JSON - NO markdown, NO wrapping, NO "result" field
-3. Follow the EXACT order of instructions given by the user
-4. Use "print" actions to display ALL requested output to the user
-5. ALWAYS use valid JSON - all values must be proper JSON types (strings, numbers, objects, arrays, booleans, null)
-6. EFFICIENCY: Group consecutive print actions into a single print using \\n for line breaks
-   - WRONG: Three separate prints for header lines
-   - RIGHT: One print with "Line1\\nLine2\\nLine3"
-6b. EFFICIENCY - Batch Operations: When performing the same operation on multiple items, check if a batch/plural version exists:
-   - Look for plural intent names in available delegation actions: createAllUser/createAllUsers (batch) vs createUser (single)
-   - ❌ WRONG: Six separate createUser calls for 6 users
-   - ✅ RIGHT: One createAllUser call with array of all 6 users: { "actionType": "delegate", "intent": "createAllUser", "data": { "users": [{name: "Alice", id: "001", ...}, {name: "Bob", id: "002", ...}, ...] } }
-   - Apply this principle to ANY repeated operation where a batch version exists
-   - Benefits: Fewer network calls, better performance, cleaner action sequences
-7. ACTION IDs (OPTIONAL): Use "id" field ONLY when you need to reference the result later
-   - Add "id": "a1" only if you'll use \${a1.output} in a future action
-   - Actions without "id" won't save their output (use for print, one-time actions)
-   - Sequential IDs: a1, a2, a3, ... (only for actions that need saving)
-   - Example: { "id": "a1", "intent": "getUser" } → later use \${a1.output.name}
-8. CRITICAL - DATE/AGE CALCULATIONS & TEXT GENERATION: If playbook contains text templates with {x}, {age}, {días}, {dd/mm/yyyy} or any placeholder:
-   - NEVER generate template expressions with Date arithmetic
-   - MANDATORY: Use format action with the data array
-   - CRITICAL: Copy the COMPLETE template from playbook to format action's "instruction" - preserve ALL details:
-     * Keep ALL conditional logic (e.g., "Estimado o Estimada si es chica, deducelo por el nombre")
-     * Preserve ALL line breaks/spacing (use \n in instruction string for each line break in template)
-     * Keep original language and exact wording
-     * Don't simplify, paraphrase, or omit any part of the template
-   - ❌ ABSOLUTELY WRONG: print with "\${2023 - new Date(birthdate).getFullYear()}" or any Date calculations
-   - ❌ WRONG: Simplifying template from "Estimado (o Estimada si es chica) <nombre>,\n\nComo sabemos..." to "Estimado {name}, Como sabemos..."
-   - ✅ RIGHT: { "id": "formatted", "intent": "format", "data": "\${usersArray}", "instruction": "For each user write:\n\nEstimado (o Estimada si es chica, deducelo por el nombre) {name},\n\nComo sabemos que usted tiene {age} años, le queremos dar la enhorabuena!\n\nAtentamente,\nLa empresa!!\n\nSeparate emails with blank line" }, then print "\${formatted.output.formatted}"
-9. NEVER use .map() or arrow functions with nested template literals in template variables:
-   - ❌ ABSOLUTELY WRONG: \${array.map(item => \`text \${item.field}\`).join('\\n')} (nested templates CANNOT be evaluated)
-   - ❌ WRONG: print with "\${users.map(u => \`| \${u.name} | \${u.age} |\`).join('\\n')}" (will print literal template string)
-   - ✅ MANDATORY: Use format action for ANY iteration over arrays
-   - For markdown tables: { "id": "aX", "intent": "format", "data": "\${arrayId.output.users}", "instruction": "Generate markdown table with columns: Sr/Sra (deduce from name), Name, Age. Include header row with | Sr/Sra | Name | Age | and separator |--------|------|-----|" }
-   - For lists: { "id": "aX", "intent": "format", "data": "\${arrayId.output.items}", "instruction": "Format each item as: - {name}: {description}" }
-   - Then print: { "intent": "print", "message": "\${aX.output.formatted}" }
-
-RESPONSE FORMAT (ALWAYS use this):
-{
-  "actions": [
-    { "actionType": "direct", "intent": "print", "message": "Display this to user" },
-    { "actionType": "direct", "intent": "return", "data": {...} }
-  ]
-}
-
-CORRECT EXAMPLES:
-
-Example 1 - NEVER hardcode dynamic values (CRITICAL - Follow Rule #4):
-User prompt: "Create 2 users, then show 'X users created' where X is the count"
-❌ WRONG - Hardcoded count:
-{ "actionType": "direct", "intent": "print", "message": "✅ 2 users created" }
+OUTPUT: { "actions": [...] }
 
-✅ RIGHT - Dynamic count:
-{ "id": "a1", "actionType": "delegate", "intent": "createUser", "data": {...} },
-{ "id": "a2", "actionType": "delegate", "intent": "createUser", "data": {...} },
-{ "actionType": "direct", "intent": "print", "message": "✅ \${a1.output.success && a2.output.success ? 2 : (a1.output.success || a2.output.success ? 1 : 0)} users created" }
-
-Example 2 - Extracting names from natural language (CRITICAL - Follow Rule #6):
-User prompt: "Create Alice: id=001, age=30, email=alice@example.com"
-❌ WRONG - Missing name: { "data": { "id": "001", "age": 30, "email": "alice@example.com" } }
-✅ RIGHT - Include name: { "data": { "name": "Alice", "id": "001", "age": 30, "email": "alice@example.com" } }
-
-Example 3 - Delegate with ID:
-{
-  "actions": [
-    { "id": "a1", "actionType": "delegate", "intent": "getUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "User: \${a1.output.name}, age \${a1.output.age}" }
-  ]
-}
-
-Example 4 - Multiple actions with IDs:
-{
-  "actions": [
-    { "id": "a1", "actionType": "delegate", "intent": "listUsers" },
-    { "actionType": "direct", "intent": "print", "message": "Found \${a1.output.count} users" },
-    { "id": "a2", "actionType": "delegate", "intent": "getUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "First user: \${a2.output.name}" }
-  ]
-}
-
-Example 5 - Registry operations with IDs:
-{
-  "actions": [
-    { "id": "a1", "actionType": "direct", "intent": "registry_get", "key": "user:001" },
-    { "actionType": "direct", "intent": "print", "message": "Name: \${a1.output.value.name}" }
-  ]
-}
-
-Example 6 - Without IDs (when results aren't needed):
-{
+CRITICAL RULES:
+1. call_llm: ONLY when playbook says "random", "relacionado", "based on", "adapted", "generate question". If playbook can generate content directly, do NOT use call_llm.
+2. Loops: "hasta que se despida" → while with llm_eval condition
+3. IDs: Actions MUST have "id" if output will be referenced via \${id.output}
+4. Template variables ONLY in strings: "text \${var}" not \${var}
+5. Group consecutive prints with \\n
+
+WHILE LOOP EXAMPLE:
+{ "id": "name", "intent": "prompt_user", "question": "¿Cuál es tu nombre?" },
+{ "intent": "registry_set", "key": "last", "value": "\${name.output.answer}" },
+{ "intent": "while",
+  "condition": { "llm_eval": true, "instruction": "¿Continuar?", "data": "\${response.output.answer}" },
   "actions": [
-    { "actionType": "direct", "intent": "print", "message": "Hello" },
-    { "actionType": "delegate", "intent": "deleteUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "User deleted" }
+    { "id": "prev", "intent": "registry_get", "key": "last" },
+    { "id": "question", "intent": "call_llm", "data": {"answer":"\${prev.output.value}"}, "instruction": "Generate related question" },
+    { "id": "response", "intent": "prompt_user", "question": "\${question.output.result}" },
+    { "intent": "registry_set", "key": "last", "value": "\${response.output.answer}" }
   ]
 }
-
-CRITICAL: ALWAYS include "actionType" field in EVERY action (either "direct" or "delegate")
+CRITICAL: condition.data uses ID from prompt_user INSIDE loop ("response"), NOT from outside ("name")
 
 Available actions:
 ${actionRegistry.generatePromptDocumentation(agent)}
-${hasTeams && agent ? agent.getPeerCapabilitiesAsActions() : ''}
+${hasTeams && agent ? await agent.getPeerCapabilitiesAsActions() : ''}
+${mcpToolsDoc}
 
 ${hasTeams ? `\nIMPORTANT: Do NOT nest "intent" inside "data". The "intent" field must be at the top level.` : ''}
 
-Data chaining with action outputs:
-- Use \${a1.output.field} to reference the output of action a1
-- Template variables can ONLY be used INSIDE strings
-- NEVER use template variables as direct values: { "count": \${a1.output.length} } ❌ WRONG
-- ALWAYS quote them: { "count": "\${a1.output.length}" } ✅ CORRECT
-- NEVER use the word "undefined" in JSON - use null or a string instead
-
-Examples:
-- \${a1.output.count} - Access count field from action a1
-- \${a2.output.users} - Access users array from action a2
-- \${a3.output.users[0].name} - Access nested field
-- After action a5 executes, you can reference \${a5.output} in subsequent actions
+Data chaining:
+- Reference action outputs: \${actionId.output.field}
+- Template variables ONLY in strings: { "count": "\${user.output.length}" } ✅ NOT { "count": \${user.output.length} } ❌
+- Use descriptive IDs: "user", "question", "response", NOT "a1", "a2", "a3"
+- Examples: \${user.output.name}, \${question.output.result}, \${response.output.answer}
 
 CRITICAL: When instructions say "Do NOT add print actions", follow that EXACTLY - only generate the actions listed in the steps.
 When using "return" actions with data containing template variables, do NOT add intermediate print actions - they will break the data chain.
@@ -796,6 +789,7 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
       temperature: 0, // Always use 0 for maximum determinism
       system: systemPrompt,
       messages: [
+        ...memory,
         {
           role: 'user',
           content: prompt
@@ -816,141 +810,59 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
    * @param {Function} onAction - Callback called for each complete action: (action) => void
    * @returns {Promise<Object>} - Final parsed response
    */
-  async executeOpenAIStreaming(prompt, fromDelegation = false, hasTeams = false, promptLength = 0, agent = null, onAction = null) {
+  async executeOpenAIStreaming(prompt, fromDelegation = false, hasTeams = false, promptLength = 0, agent = null, onAction = null, memory = []) {
     if (!process.env.OPENAI_API_KEY) {
       throw new Error('OPENAI_API_KEY not set in environment');
     }
 
-    // Build system prompt
-    const systemPrompt = `You are a Koi agent executor. Your job is to convert user instructions into a precise sequence of executable actions.
-
-CRITICAL RULES:
-1. Execute EVERY instruction in the user's request - do not skip any steps
-2. Return ONLY raw JSON - NO markdown, NO wrapping, NO "result" field
-3. Follow the EXACT order of instructions given by the user
-4. Use "print" actions to display ALL requested output to the user
-5. ALWAYS use valid JSON - all values must be proper JSON types (strings, numbers, objects, arrays, booleans, null)
-6. EFFICIENCY: Group consecutive print actions into a single print using \\n for line breaks
-   - WRONG: Three separate prints for header lines
-   - RIGHT: One print with "Line1\\nLine2\\nLine3"
-6b. EFFICIENCY - Batch Operations: When performing the same operation on multiple items, check if a batch/plural version exists:
-   - Look for plural intent names in available delegation actions: createAllUser/createAllUsers (batch) vs createUser (single)
-   - ❌ WRONG: Six separate createUser calls for 6 users
-   - ✅ RIGHT: One createAllUser call with array of all 6 users: { "actionType": "delegate", "intent": "createAllUser", "data": { "users": [{name: "Alice", id: "001", ...}, {name: "Bob", id: "002", ...}, ...] } }
-   - Apply this principle to ANY repeated operation where a batch version exists
-   - Benefits: Fewer network calls, better performance, cleaner action sequences
-7. ACTION IDs (OPTIONAL): Use "id" field ONLY when you need to reference the result later
-   - Add "id": "a1" only if you'll use \${a1.output} in a future action
-   - Actions without "id" won't save their output (use for print, one-time actions)
-   - Sequential IDs: a1, a2, a3, ... (only for actions that need saving)
-   - Example: { "id": "a1", "intent": "getUser" } → later use \${a1.output.name}
-8. CRITICAL - DATE/AGE CALCULATIONS & TEXT GENERATION: If playbook contains text templates with {x}, {age}, {días}, {dd/mm/yyyy} or any placeholder:
-   - NEVER generate template expressions with Date arithmetic
-   - MANDATORY: Use format action with the data array
-   - CRITICAL: Copy the COMPLETE template from playbook to format action's "instruction" - preserve ALL details:
-     * Keep ALL conditional logic (e.g., "Estimado o Estimada si es chica, deducelo por el nombre")
-     * Preserve ALL line breaks/spacing (use \n in instruction string for each line break in template)
-     * Keep original language and exact wording
-     * Don't simplify, paraphrase, or omit any part of the template
-   - ❌ ABSOLUTELY WRONG: print with "\${2023 - new Date(birthdate).getFullYear()}" or any Date calculations
-   - ❌ WRONG: Simplifying template from "Estimado (o Estimada si es chica) <nombre>,\n\nComo sabemos..." to "Estimado {name}, Como sabemos..."
-   - ✅ RIGHT: { "id": "formatted", "intent": "format", "data": "\${usersArray}", "instruction": "For each user write:\n\nEstimado (o Estimada si es chica, deducelo por el nombre) {name},\n\nComo sabemos que usted tiene {age} años, le queremos dar la enhorabuena!\n\nAtentamente,\nLa empresa!!\n\nSeparate emails with blank line" }, then print "\${formatted.output.formatted}"
-9. NEVER use .map() or arrow functions with nested template literals in template variables:
-   - ❌ ABSOLUTELY WRONG: \${array.map(item => \`text \${item.field}\`).join('\\n')} (nested templates CANNOT be evaluated)
-   - ❌ WRONG: print with "\${users.map(u => \`| \${u.name} | \${u.age} |\`).join('\\n')}" (will print literal template string)
-   - ✅ MANDATORY: Use format action for ANY iteration over arrays
-   - For markdown tables: { "id": "aX", "intent": "format", "data": "\${arrayId.output.users}", "instruction": "Generate markdown table with columns: Sr/Sra (deduce from name), Name, Age. Include header row with | Sr/Sra | Name | Age | and separator |--------|------|-----|" }
-   - For lists: { "id": "aX", "intent": "format", "data": "\${arrayId.output.items}", "instruction": "Format each item as: - {name}: {description}" }
-   - Then print: { "intent": "print", "message": "\${aX.output.formatted}" }
-
-RESPONSE FORMAT (ALWAYS use this):
-{
-  "actions": [
-    { "actionType": "direct", "intent": "print", "message": "Display this to user" },
-    { "actionType": "direct", "intent": "return", "data": {...} }
-  ]
-}
-
-CORRECT EXAMPLES:
-
-Example 1 - NEVER hardcode dynamic values (CRITICAL - Follow Rule #4):
-User prompt: "Create 2 users, then show 'X users created' where X is the count"
-❌ WRONG - Hardcoded count:
-{ "actionType": "direct", "intent": "print", "message": "✅ 2 users created" }
+    const mcpToolsDoc = this._getMCPToolsDoc(agent);
 
-✅ RIGHT - Dynamic count:
-{ "id": "a1", "actionType": "delegate", "intent": "createUser", "data": {...} },
-{ "id": "a2", "actionType": "delegate", "intent": "createUser", "data": {...} },
-{ "actionType": "direct", "intent": "print", "message": "✅ \${a1.output.success && a2.output.success ? 2 : (a1.output.success || a2.output.success ? 1 : 0)} users created" }
-
-Example 2 - Extracting names from natural language (CRITICAL - Follow Rule #6):
-User prompt: "Create Alice: id=001, age=30, email=alice@example.com"
-❌ WRONG - Missing name: { "data": { "id": "001", "age": 30, "email": "alice@example.com" } }
-✅ RIGHT - Include name: { "data": { "name": "Alice", "id": "001", "age": 30, "email": "alice@example.com" } }
-
-Example 3 - Delegate with ID:
-{
-  "actions": [
-    { "id": "a1", "actionType": "delegate", "intent": "getUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "User: \${a1.output.name}, age \${a1.output.age}" }
-  ]
-}
-
-Example 4 - Multiple actions with IDs:
-{
-  "actions": [
-    { "id": "a1", "actionType": "delegate", "intent": "listUsers" },
-    { "actionType": "direct", "intent": "print", "message": "Found \${a1.output.count} users" },
-    { "id": "a2", "actionType": "delegate", "intent": "getUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "First user: \${a2.output.name}" }
-  ]
-}
+    // Build system prompt
+    const systemPrompt = `Convert the following instructions into executable JSON actions.
 
-Example 5 - Registry operations with IDs:
-{
-  "actions": [
-    { "id": "a1", "actionType": "direct", "intent": "registry_get", "key": "user:001" },
-    { "actionType": "direct", "intent": "print", "message": "Name: \${a1.output.value.name}" }
-  ]
-}
+OUTPUT: { "actions": [...] }
 
-Example 6 - Without IDs (when results aren't needed):
-{
+CRITICAL RULES:
+1. call_llm: ONLY when playbook says "random", "relacionado", "based on", "adapted", "generate question". If playbook can generate content directly, do NOT use call_llm.
+2. Loops: "hasta que se despida" → while with llm_eval condition
+3. IDs: Actions MUST have "id" if output will be referenced via \${id.output}
+4. Template variables ONLY in strings: "text \${var}" not \${var}
+5. Group consecutive prints with \\n
+
+WHILE LOOP EXAMPLE:
+{ "id": "name", "intent": "prompt_user", "question": "¿Cuál es tu nombre?" },
+{ "intent": "registry_set", "key": "last", "value": "\${name.output.answer}" },
+{ "intent": "while",
+  "condition": { "llm_eval": true, "instruction": "¿Continuar?", "data": "\${response.output.answer}" },
   "actions": [
-    { "actionType": "direct", "intent": "print", "message": "Hello" },
-    { "actionType": "delegate", "intent": "deleteUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "User deleted" }
+    { "id": "prev", "intent": "registry_get", "key": "last" },
+    { "id": "question", "intent": "call_llm", "data": {"answer":"\${prev.output.value}"}, "instruction": "Generate related question" },
+    { "id": "response", "intent": "prompt_user", "question": "\${question.output.result}" },
+    { "intent": "registry_set", "key": "last", "value": "\${response.output.answer}" }
   ]
 }
-
-CRITICAL: ALWAYS include "actionType" field in EVERY action (either "direct" or "delegate")
+CRITICAL: condition.data uses ID from prompt_user INSIDE loop ("response"), NOT from outside ("name")
 
 Available actions:
 ${actionRegistry.generatePromptDocumentation(agent)}
-${hasTeams && agent ? agent.getPeerCapabilitiesAsActions() : ''}
+${hasTeams && agent ? await agent.getPeerCapabilitiesAsActions() : ''}
+${mcpToolsDoc}
 
 ${hasTeams ? `\nIMPORTANT: Do NOT nest "intent" inside "data". The "intent" field must be at the top level.` : ''}
 
-Data chaining with action outputs:
-- Use \${a1.output.field} to reference the output of action a1
-- Template variables can ONLY be used INSIDE strings
-- NEVER use template variables as direct values: { "count": \${a1.output.length} } ❌ WRONG
-- ALWAYS quote them: { "count": "\${a1.output.length}" } ✅ CORRECT
-- NEVER use the word "undefined" in JSON - use null or a string instead
-
-Examples:
-- \${a1.output.count} - Access count field from action a1
-- \${a2.output.users} - Access users array from action a2
-- \${a3.output.users[0].name} - Access nested field
-- After action a5 executes, you can reference \${a5.output} in subsequent actions
+Data chaining:
+- Reference action outputs: \${actionId.output.field}
+- Template variables ONLY in strings: { "count": "\${user.output.length}" } ✅ NOT { "count": \${user.output.length} } ❌
+- Use descriptive IDs: "user", "question", "response", NOT "a1", "a2", "a3"
+- Examples: \${user.output.name}, \${question.output.result}, \${response.output.answer}
 
 CRITICAL: When instructions say "Do NOT add print actions", follow that EXACTLY - only generate the actions listed in the steps.
 When using "return" actions with data containing template variables, do NOT add intermediate print actions - they will break the data chain.
 
 REMEMBER: Include print actions for ALL output the user should see, UNLESS the instructions explicitly say not to. Return valid, parseable JSON only.`;
 
-    // Use fastest model for delegated work or short playbooks
-    const model = fromDelegation || promptLength < 500 ? 'gpt-4o-mini' : this.model;
+    // Use agent's configured model
+    const model = this.model;
 
     if (process.env.KOI_DEBUG_LLM) {
       const agentInfo = agent ? ` | Agent: ${agent.name}` : '';
@@ -965,18 +877,30 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
       console.error('─'.repeat(80));
     }
 
+    // Log memory if present
+    if (process.env.KOI_DEBUG_LLM && memory.length > 0) {
+      console.error(`[LLM Debug] 🧠 Sending ${memory.length} memory messages:`);
+      for (const m of memory) {
+        const preview = m.content.substring(0, 150);
+        console.error(`  [${m.role}] ${preview}...`);
+      }
+    }
+
     // Create streaming completion
-    const stream = await this.openai.chat.completions.create({
-      model,
-      messages: [
-        { role: 'system', content: systemPrompt },
-        { role: 'user', content: prompt }
-      ],
-      temperature: 0,
-      max_tokens: this.maxTokens,
-      stream: true,  // Enable streaming
-      response_format: { type: "json_object" }
-    });
+    const stream = await this.openai.chat.completions.create(
+      this.buildApiParams({
+        model,
+        messages: [
+          { role: 'system', content: systemPrompt },
+          ...memory,
+          { role: 'user', content: prompt }
+        ],
+        temperature: 0,
+        max_tokens: this.maxTokens,
+        stream: true,  // Enable streaming
+        response_format: { type: "json_object" }
+      })
+    );
 
     // Use incremental parser
     const parser = new IncrementalJSONParser();
@@ -1078,6 +1002,19 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
       actionQueue.push(...finalActions);
     }
 
+    // Print response immediately after receiving it
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`\n[LLM Debug] executeOpenAIStreaming Complete (${fullContent.length} chars)`);
+      console.error('─'.repeat(80));
+      console.error('[LLM Debug] Response:');
+      // Format each line with < prefix and gray color
+      const lines = fullContent.split('\n');
+      for (const line of lines) {
+        console.error(`< \x1b[90m${line}\x1b[0m`);
+      }
+      console.error('─'.repeat(80));
+    }
+
     // Esperar a que se procesen todas las acciones en la cola
     if (processingPromise) {
       await processingPromise;
@@ -1093,18 +1030,6 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
       throw processingError;
     }
 
-    if (process.env.KOI_DEBUG_LLM) {
-      console.error(`[LLM Debug] executeOpenAIStreaming Complete (${fullContent.length} chars)`);
-      console.error('─'.repeat(80));
-      console.error('[LLM Debug] Response:');
-      // Format each line with < prefix and gray color
-      const lines = fullContent.split('\n');
-      for (const line of lines) {
-        console.error(`< \x1b[90m${line}\x1b[0m`);
-      }
-      console.error('─'.repeat(80));
-    }
-
     return fullContent;
   }
 
@@ -1115,135 +1040,52 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
    * @param {Function} onAction - Callback called for each complete action: (action) => void
    * @returns {Promise<string>} - Final response content
    */
-  async executeAnthropicStreaming(prompt, agent = null, onAction = null) {
+  async executeAnthropicStreaming(prompt, agent = null, onAction = null, memory = []) {
     if (!process.env.ANTHROPIC_API_KEY) {
       throw new Error('ANTHROPIC_API_KEY not set in environment');
     }
 
     // Check if agent has teams for delegation
     const hasTeams = agent && agent.usesTeams && agent.usesTeams.length > 0;
+    const mcpToolsDoc = this._getMCPToolsDoc(agent);
 
-    const systemPrompt = `You are a Koi agent executor. Your job is to convert user instructions into a precise sequence of executable actions.
-
-CRITICAL RULES:
-1. Execute EVERY instruction in the user's request - do not skip any steps
-2. Return ONLY raw JSON - NO markdown, NO wrapping, NO "result" field
-3. Follow the EXACT order of instructions given by the user
-4. Use "print" actions to display ALL requested output to the user
-5. ALWAYS use valid JSON - all values must be proper JSON types (strings, numbers, objects, arrays, booleans, null)
-6. EFFICIENCY: Group consecutive print actions into a single print using \\n for line breaks
-   - WRONG: Three separate prints for header lines
-   - RIGHT: One print with "Line1\\nLine2\\nLine3"
-6b. EFFICIENCY - Batch Operations: When performing the same operation on multiple items, check if a batch/plural version exists:
-   - Look for plural intent names in available delegation actions: createAllUser/createAllUsers (batch) vs createUser (single)
-   - ❌ WRONG: Six separate createUser calls for 6 users
-   - ✅ RIGHT: One createAllUser call with array of all 6 users: { "actionType": "delegate", "intent": "createAllUser", "data": { "users": [{name: "Alice", id: "001", ...}, {name: "Bob", id: "002", ...}, ...] } }
-   - Apply this principle to ANY repeated operation where a batch version exists
-   - Benefits: Fewer network calls, better performance, cleaner action sequences
-7. ACTION IDs (OPTIONAL): Use "id" field ONLY when you need to reference the result later
-   - Add "id": "a1" only if you'll use \${a1.output} in a future action
-   - Actions without "id" won't save their output (use for print, one-time actions)
-   - Sequential IDs: a1, a2, a3, ... (only for actions that need saving)
-   - Example: { "id": "a1", "intent": "getUser" } → later use \${a1.output.name}
-8. CRITICAL - DATE/AGE CALCULATIONS & TEXT GENERATION: If playbook contains text templates with {x}, {age}, {días}, {dd/mm/yyyy} or any placeholder:
-   - NEVER generate template expressions with Date arithmetic
-   - MANDATORY: Use format action with the data array
-   - CRITICAL: Copy the COMPLETE template from playbook to format action's "instruction" - preserve ALL details:
-     * Keep ALL conditional logic (e.g., "Estimado o Estimada si es chica, deducelo por el nombre")
-     * Preserve ALL line breaks/spacing (use \n in instruction string for each line break in template)
-     * Keep original language and exact wording
-     * Don't simplify, paraphrase, or omit any part of the template
-   - ❌ ABSOLUTELY WRONG: print with "\${2023 - new Date(birthdate).getFullYear()}" or any Date calculations
-   - ❌ WRONG: Simplifying template from "Estimado (o Estimada si es chica) <nombre>,\n\nComo sabemos..." to "Estimado {name}, Como sabemos..."
-   - ✅ RIGHT: { "id": "formatted", "intent": "format", "data": "\${usersArray}", "instruction": "For each user write:\n\nEstimado (o Estimada si es chica, deducelo por el nombre) {name},\n\nComo sabemos que usted tiene {age} años, le queremos dar la enhorabuena!\n\nAtentamente,\nLa empresa!!\n\nSeparate emails with blank line" }, then print "\${formatted.output.formatted}"
-9. NEVER use .map() or arrow functions with nested template literals in template variables:
-   - ❌ ABSOLUTELY WRONG: \${array.map(item => \`text \${item.field}\`).join('\\n')} (nested templates CANNOT be evaluated)
-   - ❌ WRONG: print with "\${users.map(u => \`| \${u.name} | \${u.age} |\`).join('\\n')}" (will print literal template string)
-   - ✅ MANDATORY: Use format action for ANY iteration over arrays
-   - For markdown tables: { "id": "aX", "intent": "format", "data": "\${arrayId.output.users}", "instruction": "Generate markdown table with columns: Sr/Sra (deduce from name), Name, Age. Include header row with | Sr/Sra | Name | Age | and separator |--------|------|-----|" }
-   - For lists: { "id": "aX", "intent": "format", "data": "\${arrayId.output.items}", "instruction": "Format each item as: - {name}: {description}" }
-   - Then print: { "intent": "print", "message": "\${aX.output.formatted}" }
-
-RESPONSE FORMAT (ALWAYS use this):
-{
-  "actions": [
-    { "actionType": "direct", "intent": "print", "message": "Display this to user" },
-    { "actionType": "direct", "intent": "return", "data": {...} }
-  ]
-}
-
-CORRECT EXAMPLES:
-
-Example 1 - NEVER hardcode dynamic values (CRITICAL - Follow Rule #4):
-User prompt: "Create 2 users, then show 'X users created' where X is the count"
-❌ WRONG - Hardcoded count:
-{ "actionType": "direct", "intent": "print", "message": "✅ 2 users created" }
+    const systemPrompt = `Convert the following instructions into executable JSON actions.
 
-✅ RIGHT - Dynamic count:
-{ "id": "a1", "actionType": "delegate", "intent": "createUser", "data": {...} },
-{ "id": "a2", "actionType": "delegate", "intent": "createUser", "data": {...} },
-{ "actionType": "direct", "intent": "print", "message": "✅ \${a1.output.success && a2.output.success ? 2 : (a1.output.success || a2.output.success ? 1 : 0)} users created" }
+OUTPUT: { "actions": [...] }
 
-Example 2 - Extracting names from natural language (CRITICAL - Follow Rule #6):
-User prompt: "Create Alice: id=001, age=30, email=alice@example.com"
-❌ WRONG - Missing name: { "data": { "id": "001", "age": 30, "email": "alice@example.com" } }
-✅ RIGHT - Include name: { "data": { "name": "Alice", "id": "001", "age": 30, "email": "alice@example.com" } }
-
-Example 3 - Delegate with ID:
-{
-  "actions": [
-    { "id": "a1", "actionType": "delegate", "intent": "getUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "User: \${a1.output.name}, age \${a1.output.age}" }
-  ]
-}
-
-Example 4 - Multiple actions with IDs:
-{
-  "actions": [
-    { "id": "a1", "actionType": "delegate", "intent": "listUsers" },
-    { "actionType": "direct", "intent": "print", "message": "Found \${a1.output.count} users" },
-    { "id": "a2", "actionType": "delegate", "intent": "getUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "First user: \${a2.output.name}" }
-  ]
-}
-
-Example 5 - Registry operations with IDs:
-{
-  "actions": [
-    { "id": "a1", "actionType": "direct", "intent": "registry_get", "key": "user:001" },
-    { "actionType": "direct", "intent": "print", "message": "Name: \${a1.output.value.name}" }
-  ]
-}
-
-Example 6 - Without IDs (when results aren't needed):
-{
+CRITICAL RULES:
+1. call_llm: ONLY when playbook says "random", "relacionado", "based on", "adapted", "generate question". If playbook can generate content directly, do NOT use call_llm.
+2. Loops: "hasta que se despida" → while with llm_eval condition
+3. IDs: Actions MUST have "id" if output will be referenced via \${id.output}
+4. Template variables ONLY in strings: "text \${var}" not \${var}
+5. Group consecutive prints with \\n
+
+WHILE LOOP EXAMPLE:
+{ "id": "name", "intent": "prompt_user", "question": "¿Cuál es tu nombre?" },
+{ "intent": "registry_set", "key": "last", "value": "\${name.output.answer}" },
+{ "intent": "while",
+  "condition": { "llm_eval": true, "instruction": "¿Continuar?", "data": "\${response.output.answer}" },
   "actions": [
-    { "actionType": "direct", "intent": "print", "message": "Hello" },
-    { "actionType": "delegate", "intent": "deleteUser", "data": { "id": "001" } },
-    { "actionType": "direct", "intent": "print", "message": "User deleted" }
+    { "id": "prev", "intent": "registry_get", "key": "last" },
+    { "id": "question", "intent": "call_llm", "data": {"answer":"\${prev.output.value}"}, "instruction": "Generate related question" },
+    { "id": "response", "intent": "prompt_user", "question": "\${question.output.result}" },
+    { "intent": "registry_set", "key": "last", "value": "\${response.output.answer}" }
   ]
 }
-
-CRITICAL: ALWAYS include "actionType" field in EVERY action (either "direct" or "delegate")
+CRITICAL: condition.data uses ID from prompt_user INSIDE loop ("response"), NOT from outside ("name")
 
 Available actions:
 ${actionRegistry.generatePromptDocumentation(agent)}
-${hasTeams && agent ? agent.getPeerCapabilitiesAsActions() : ''}
+${hasTeams && agent ? await agent.getPeerCapabilitiesAsActions() : ''}
+${mcpToolsDoc}
 
 ${hasTeams ? `\nIMPORTANT: Do NOT nest "intent" inside "data". The "intent" field must be at the top level.` : ''}
 
-Data chaining with action outputs:
-- Use \${a1.output.field} to reference the output of action a1
-- Template variables can ONLY be used INSIDE strings
-- NEVER use template variables as direct values: { "count": \${a1.output.length} } ❌ WRONG
-- ALWAYS quote them: { "count": "\${a1.output.length}" } ✅ CORRECT
-- NEVER use the word "undefined" in JSON - use null or a string instead
-
-Examples:
-- \${a1.output.count} - Access count field from action a1
-- \${a2.output.users} - Access users array from action a2
-- \${a3.output.users[0].name} - Access nested field
-- After action a5 executes, you can reference \${a5.output} in subsequent actions
+Data chaining:
+- Reference action outputs: \${actionId.output.field}
+- Template variables ONLY in strings: { "count": "\${user.output.length}" } ✅ NOT { "count": \${user.output.length} } ❌
+- Use descriptive IDs: "user", "question", "response", NOT "a1", "a2", "a3"
+- Examples: \${user.output.name}, \${question.output.result}, \${response.output.answer}
 
 CRITICAL: When instructions say "Do NOT add print actions", follow that EXACTLY - only generate the actions listed in the steps.
 When using "return" actions with data containing template variables, do NOT add intermediate print actions - they will break the data chain.
@@ -1269,7 +1111,7 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
       max_tokens: this.maxTokens,
       temperature: 0,
       system: systemPrompt,
-      messages: [{ role: 'user', content: prompt }]
+      messages: [...memory, { role: 'user', content: prompt }]
     });
 
     // Use incremental parser
@@ -1313,14 +1155,10 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
 
     // Finalize parser to catch any remaining actions
     const finalActions = parser.finalize();
-    if (onAction && finalActions.length > 0) {
-      for (const action of finalActions) {
-        await onAction(action);
-      }
-    }
 
+    // Print response immediately after receiving it
     if (process.env.KOI_DEBUG_LLM) {
-      console.error(`[LLM Debug] executeAnthropicStreaming Complete (${fullContent.length} chars)`);
+      console.error(`\n[LLM Debug] executeAnthropicStreaming Complete (${fullContent.length} chars)`);
       console.error('─'.repeat(80));
       console.error('[LLM Debug] Response:');
       // Format each line with < prefix and gray color
@@ -1331,9 +1169,681 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
       console.error('─'.repeat(80));
     }
 
+    if (onAction && finalActions.length > 0) {
+      for (const action of finalActions) {
+        await onAction(action);
+      }
+    }
+
     return fullContent;
   }
 
+  // =========================================================================
+  // GEMINI METHODS (uses OpenAI-compatible endpoint)
+  // =========================================================================
+
+  /**
+   * Execute Gemini call (non-streaming, plan-then-execute).
+   * Uses the OpenAI SDK pointed at Gemini's OpenAI-compatible API.
+   */
+  async executeGemini(prompt, agent = null, memory = []) {
+    const hasTeams = agent && agent.usesTeams && agent.usesTeams.length > 0;
+
+    const systemPrompt = `Convert the following instructions into executable JSON actions.
+
+OUTPUT: { "actions": [...] }
+
+CRITICAL RULES:
+1. call_llm: ONLY when playbook says "random", "relacionado", "based on", "adapted", "generate question". If playbook can generate content directly, do NOT use call_llm.
+2. Loops: "hasta que se despida" → while with llm_eval condition
+3. IDs: Actions MUST have "id" if output will be referenced via \${id.output}
+4. Template variables ONLY in strings: "text \${var}" not \${var}
+5. Group consecutive prints with \\n
+
+Available actions:
+${actionRegistry.generatePromptDocumentation(agent)}
+${hasTeams && agent ? await agent.getPeerCapabilitiesAsActions() : ''}
+
+${hasTeams ? `\nIMPORTANT: Do NOT nest "intent" inside "data". The "intent" field must be at the top level.` : ''}
+
+Data chaining:
+- Reference action outputs: \${actionId.output.field}
+- Template variables ONLY in strings: { "count": "\${user.output.length}" } ✅ NOT { "count": \${user.output.length} } ❌
+- Use descriptive IDs: "user", "question", "response", NOT "a1", "a2", "a3"
+
+REMEMBER: Include print actions for ALL output the user should see, UNLESS the instructions explicitly say not to. Return valid, parseable JSON only.`;
+
+    const model = this.model;
+
+    this.logRequest(model, systemPrompt, prompt, `Gemini | Agent: ${agent?.name || 'unknown'}`);
+
+    const completion = await this.openai.chat.completions.create(
+      this.buildApiParams({
+        model,
+        messages: [
+          { role: 'system', content: systemPrompt },
+          ...memory,
+          { role: 'user', content: prompt }
+        ],
+        temperature: 0,
+        max_tokens: this.maxTokens,
+        response_format: { type: 'json_object' }
+      })
+    );
+
+    const content = completion.choices[0].message.content?.trim() || '';
+    this.logResponse(content, `Gemini | Agent: ${agent?.name || 'unknown'}`);
+
+    return content;
+  }
+
+  /**
+   * Execute Gemini call with streaming and incremental action execution.
+   * Uses the OpenAI SDK pointed at Gemini's OpenAI-compatible API.
+   */
+  async executeGeminiStreaming(prompt, hasTeams = false, agent = null, onAction = null, memory = []) {
+    const systemPrompt = `Convert the following instructions into executable JSON actions.
+
+OUTPUT: { "actions": [...] }
+
+CRITICAL RULES:
+1. call_llm: ONLY when playbook says "random", "relacionado", "based on", "adapted", "generate question". If playbook can generate content directly, do NOT use call_llm.
+2. Loops: "hasta que se despida" → while with llm_eval condition
+3. IDs: Actions MUST have "id" if output will be referenced via \${id.output}
+4. Template variables ONLY in strings: "text \${var}" not \${var}
+5. Group consecutive prints with \\n
+
+Available actions:
+${actionRegistry.generatePromptDocumentation(agent)}
+${hasTeams && agent ? await agent.getPeerCapabilitiesAsActions() : ''}
+
+${hasTeams ? `\nIMPORTANT: Do NOT nest "intent" inside "data". The "intent" field must be at the top level.` : ''}
+
+Data chaining:
+- Reference action outputs: \${actionId.output.field}
+- Template variables ONLY in strings: { "count": "\${user.output.length}" } ✅ NOT { "count": \${user.output.length} } ❌
+- Use descriptive IDs: "user", "question", "response", NOT "a1", "a2", "a3"
+
+REMEMBER: Include print actions for ALL output the user should see, UNLESS the instructions explicitly say not to. Return valid, parseable JSON only.`;
+
+    const model = this.model;
+
+    this.logRequest(model, systemPrompt, prompt, `GeminiStreaming | Agent: ${agent?.name || 'unknown'}`);
+
+    // Create streaming completion (same SDK as OpenAI)
+    const stream = await this.openai.chat.completions.create(
+      this.buildApiParams({
+        model,
+        messages: [
+          { role: 'system', content: systemPrompt },
+          ...memory,
+          { role: 'user', content: prompt }
+        ],
+        temperature: 0,
+        max_tokens: this.maxTokens,
+        stream: true,
+        response_format: { type: 'json_object' }
+      })
+    );
+
+    // Use incremental parser (same logic as OpenAI streaming)
+    const parser = new IncrementalJSONParser();
+    let fullContent = '';
+
+    const actionQueue = [];
+    let streamFinished = false;
+    let processingError = null;
+    let isExecuting = false;
+
+    const processQueue = async () => {
+      while (!streamFinished || actionQueue.length > 0) {
+        if (actionQueue.length === 0) {
+          await new Promise(resolve => setTimeout(resolve, 10));
+          continue;
+        }
+        const action = actionQueue.shift();
+        if (!action) continue;
+        try {
+          isExecuting = true;
+          await onAction(action);
+        } catch (error) {
+          processingError = error;
+          break;
+        } finally {
+          isExecuting = false;
+        }
+      }
+    };
+
+    const processingPromise = onAction ? processQueue() : null;
+
+    try {
+      for await (const chunk of stream) {
+        const delta = chunk.choices[0]?.delta?.content || '';
+        if (delta) {
+          fullContent += delta;
+          const actions = parser.feed(delta);
+          if (onAction && actions.length > 0) {
+            actionQueue.push(...actions);
+          }
+          if (processingError) throw processingError;
+        }
+      }
+      streamFinished = true;
+    } catch (error) {
+      streamFinished = true;
+      throw error;
+    }
+
+    const finalActions = parser.finalize();
+    if (onAction && finalActions.length > 0) {
+      actionQueue.push(...finalActions);
+    }
+
+    this.logResponse(fullContent, `GeminiStreaming | Agent: ${agent?.name || 'unknown'}`);
+
+    if (processingPromise) await processingPromise;
+    while (isExecuting) await new Promise(resolve => setTimeout(resolve, 10));
+    if (processingError) throw processingError;
+
+    return fullContent;
+  }
+
+  // =========================================================================
+  // REACTIVE AGENTIC LOOP METHODS
+  // =========================================================================
+
+  /**
+   * Execute one iteration of the reactive playbook loop.
+   * The LLM returns ONE action per call, receives feedback, and adapts.
+   *
+   * @param {Object} params
+   * @param {string} params.playbook - The playbook text
+   * @param {Object} params.context - Context with args and state
+   * @param {string} params.agentName - Agent name for logging
+   * @param {PlaybookSession} params.session - Session tracking state
+   * @param {Object} params.agent - Agent instance
+   * @param {Array} params.conversationHistory - Mutable array of messages
+   * @returns {Object} A single action object
+   */
+  async executePlaybookReactive({ playbook, context, agentName, session, agent, conversationHistory, isFirstCall = false }) {
+    const planningPrefix = agentName ? `[🤖 ${agentName}]` : '';
+    cliLogger.planning(`${planningPrefix} Thinking`);
+
+    if (isFirstCall || conversationHistory.length === 0) {
+      // First call in this handler invocation: build system prompt + send playbook
+      // This fires both when there's no memory (length === 0) AND when memory was
+      // loaded (length > 0) but this is a new handler call (isFirstCall).
+      if (!conversationHistory.some(m => m._system !== undefined)) {
+        const systemPrompt = await this._buildReactiveSystemPrompt(agent);
+        conversationHistory.push({ _system: systemPrompt });
+      }
+
+      const contextStr = Object.keys(context).length > 0
+        ? `\nContext: ${JSON.stringify(context)}`
+        : '';
+
+      // Include MCP connection errors so the LLM can diagnose and inform the user
+      let mcpErrorStr = '';
+      if (session.mcpErrors && Object.keys(session.mcpErrors).length > 0) {
+        const errors = Object.entries(session.mcpErrors)
+          .map(([name, cause]) => `- MCP "${name}" server output:\n${cause}`)
+          .join('\n');
+        mcpErrorStr = `\n\n⚠️ MCP SERVER ERRORS — The following MCP servers crashed on startup. Do NOT call them.\nAnalyze the server output below, identify the root cause, and use "print" to tell the user:\n1. What went wrong (the specific error, not the raw output)\n2. How to fix it (e.g. "run npm install in /path/to/project")\nThen "return" with an error.\n\n${errors}`;
+      }
+
+      conversationHistory.push({
+        role: 'user',
+        content: `PLAYBOOK:\n${playbook}${contextStr}${mcpErrorStr}\n\nReturn your FIRST action.`
+      });
+    } else {
+      // Subsequent iterations: minimal feedback — the LLM has the full
+      // conversation history and can look back at the playbook in message 1.
+      const feedback = session.buildFeedbackContext();
+      conversationHistory.push({
+        role: 'user',
+        content: `${feedback}\nContinue.`
+      });
+    }
+
+    // Call the appropriate provider
+    let responseText;
+    if (this.provider === 'openai') {
+      responseText = await this._callOpenAIReactive(conversationHistory, agent);
+    } else if (this.provider === 'gemini') {
+      responseText = await this._callGeminiReactive(conversationHistory, agent);
+    } else if (this.provider === 'anthropic') {
+      responseText = await this._callAnthropicReactive(conversationHistory, agent);
+    } else {
+      throw new Error(`Unknown provider: ${this.provider}`);
+    }
+
+    cliLogger.clear();
+
+    // Parse the response into a single action
+    const action = this._parseReactiveResponse(responseText);
+
+    // Add assistant message to conversation history
+    conversationHistory.push({
+      role: 'assistant',
+      content: responseText
+    });
+
+    return action;
+  }
+
+  /**
+   * Build system prompt for reactive mode.
+   * Delegates to the unified _buildSystemPrompt.
+   */
+  async _buildReactiveSystemPrompt(agent) {
+    return await this._buildSystemPrompt(agent);
+  }
+
+  /**
+   * Call OpenAI for a reactive loop iteration.
+   * Uses the full conversation history for multi-turn context.
+   */
+  async _callOpenAIReactive(conversationHistory, agent) {
+    if (!process.env.OPENAI_API_KEY) {
+      throw new Error('OPENAI_API_KEY not set in environment');
+    }
+
+    // Build messages array: extract system prompt + filter valid messages
+    const systemPrompt = conversationHistory[0]?._system || '';
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      ...conversationHistory.filter(m => m.role === 'user' || m.role === 'assistant')
+    ];
+
+    const agentInfo = agent ? `Agent: ${agent.name}` : '';
+    this.logRequest(this.model, systemPrompt, messages.filter(m => m.role === 'user').pop()?.content || '', `Reactive ${agentInfo}`);
+
+    const completion = await this.openai.chat.completions.create(
+      this.buildApiParams({
+        model: this.model,
+        messages,
+        temperature: 0,
+        response_format: { type: 'json_object' }
+      })
+    );
+
+    const content = completion.choices[0].message.content?.trim() || '';
+    this.logResponse(content, `Reactive ${agentInfo}`);
+
+    return content;
+  }
+
+  /**
+   * Call Anthropic for a reactive loop iteration.
+   * Extracts system prompt from sentinel and uses multi-turn messages.
+   */
+  async _callAnthropicReactive(conversationHistory, agent) {
+    if (!process.env.ANTHROPIC_API_KEY) {
+      throw new Error('ANTHROPIC_API_KEY not set in environment');
+    }
+
+    // Extract system prompt from sentinel
+    const systemPrompt = conversationHistory[0]?._system || '';
+
+    // Filter to only user/assistant messages
+    const messages = conversationHistory.filter(m => m.role === 'user' || m.role === 'assistant');
+
+    const agentInfo = agent ? `Agent: ${agent.name}` : '';
+    this.logRequest(this.model, systemPrompt, messages.filter(m => m.role === 'user').pop()?.content || '', `Reactive ${agentInfo}`);
+
+    const message = await this.anthropic.messages.create({
+      model: this.model,
+      max_tokens: 8192,
+      temperature: 0,
+      system: systemPrompt,
+      messages
+    });
+
+    const content = message.content[0].text.trim();
+    this.logResponse(content, `Reactive ${agentInfo}`);
+
+    return content;
+  }
+
+  /**
+   * Call Gemini for a reactive loop iteration.
+   * Uses the OpenAI SDK pointed at Gemini's OpenAI-compatible API.
+   */
+  async _callGeminiReactive(conversationHistory, agent) {
+    // Build messages array: extract system prompt + filter valid messages
+    const systemPrompt = conversationHistory[0]?._system || '';
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      ...conversationHistory.filter(m => m.role === 'user' || m.role === 'assistant')
+    ];
+
+    const agentInfo = agent ? `Agent: ${agent.name}` : '';
+    this.logRequest(this.model, systemPrompt, messages.filter(m => m.role === 'user').pop()?.content || '', `GeminiReactive ${agentInfo}`);
+
+    const completion = await this.openai.chat.completions.create(
+      this.buildApiParams({
+        model: this.model,
+        messages,
+        temperature: 0,
+        response_format: { type: 'json_object' }
+      })
+    );
+
+    const content = completion.choices[0].message.content?.trim() || '';
+    this.logResponse(content, `GeminiReactive ${agentInfo}`);
+
+    return content;
+  }
+
+  /**
+   * Parse the LLM response from reactive mode into a single action object.
+   * Handles edge cases like markdown wrapping or legacy array format.
+   */
+  _parseReactiveResponse(responseText) {
+    // Clean markdown code blocks
+    let cleaned = responseText.trim();
+    if (cleaned.startsWith('```')) {
+      cleaned = cleaned.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '').trim();
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(cleaned);
+    } catch (e) {
+      throw new Error(`Failed to parse reactive LLM response as JSON: ${e.message}\nResponse: ${cleaned.substring(0, 200)}`);
+    }
+
+    // Handle batched actions: { "batch": [action1, action2, ...] }
+    if (parsed.batch && Array.isArray(parsed.batch) && parsed.batch.length > 0) {
+      this.logDebug(`Reactive response batched ${parsed.batch.length} actions`);
+      const actions = parsed.batch.map(a => this._normalizeReactiveAction(a));
+      return actions.length === 1 ? actions[0] : actions;
+    }
+
+    // Handle raw array (in case json_object mode is not used)
+    if (Array.isArray(parsed)) {
+      if (parsed.length === 0) {
+        throw new Error('Reactive response was an empty array');
+      }
+      const actions = parsed.map(a => this._normalizeReactiveAction(a));
+      return actions.length === 1 ? actions[0] : actions;
+    }
+
+    // If LLM returned legacy format { "actions": [...] }, extract as batch
+    if (parsed.actions && Array.isArray(parsed.actions) && parsed.actions.length > 0) {
+      this.logDebug('Reactive response used legacy {actions:[...]} format, extracting as batch');
+      const actions = parsed.actions.map(a => this._normalizeReactiveAction(a));
+      return actions.length === 1 ? actions[0] : actions;
+    }
+
+    return this._normalizeReactiveAction(parsed);
+  }
+
+  /**
+   * Normalize a single action object from a reactive response.
+   */
+  _normalizeReactiveAction(parsed) {
+    // Safety net: if actionType is not "direct"/"delegate", the LLM put the intent there
+    if (parsed.actionType && parsed.actionType !== 'direct' && parsed.actionType !== 'delegate') {
+      if (!parsed.intent) {
+        parsed.intent = parsed.actionType;
+      }
+      parsed.actionType = 'direct';
+    }
+
+    // Validate minimal structure — if no action fields, treat as raw return data
+    if (!parsed.intent && !parsed.actionType && !parsed.type) {
+      if (Object.keys(parsed).length > 0) {
+        this.logDebug('Reactive response was raw data, wrapping as return action');
+        return { actionType: 'direct', intent: 'return', data: parsed };
+      }
+      throw new Error(`Invalid reactive action: missing "intent" or "actionType". Got: ${JSON.stringify(parsed).substring(0, 200)}`);
+    }
+
+    return parsed;
+  }
+
+  // =========================================================================
+  // UNIFIED SYSTEM PROMPT - shared rules for all execution modes
+  // =========================================================================
+
+  /**
+   * Build the system prompt for all agents.
+   * Single unified prompt — only the available intents change per agent.
+   * @param {Agent} agent - The agent
+   * @returns {string} Complete system prompt
+   */
+  async _buildSystemPrompt(agent) {
+    const hasTeams = agent && agent.usesTeams && agent.usesTeams.length > 0;
+    const resourceSection = await this._buildSmartResourceSection(agent);
+    const intentNesting = hasTeams ? '\nIMPORTANT: Do NOT nest "intent" inside "data". The "intent" field must be at the top level.' : '';
+
+    return `Convert the following instructions into executable JSON actions, STEP BY STEP.
+
+Return ONE action per response. After each action you receive the result and decide the next.
+BATCHING: When multiple actions are INDEPENDENT (none depends on a previous one's result), batch them to save round-trips.
+
+RESPONSE FORMAT:
+Single: { "actionType": "<type>", "intent": "<action>", ... }
+Batch:  { "batch": [{ action1 }, { action2 }, ...] }
+
+STRUCTURE:
+- "actionType": ONLY "direct" or "delegate".
+  - "direct" = built-in action (print, prompt_user, return, registry_set, call_llm, call_mcp, shell, etc.)
+  - "delegate" = send task to a team member
+- "intent": the specific action to execute
+- Both fields are ALWAYS required on every action.
+
+RULES:
+1. Return { "actionType": "direct", "intent": "return", "data": {...} } ONLY when ALL instructions have been FULLY completed.
+2. If an action fails, TRY A DIFFERENT APPROACH — do NOT repeat the exact same action.
+3. For date/age calculations or array iteration, use "call_llm".
+4. NEVER give up. If an action fails, find an alternative path.
+5. BE PROACTIVE: if an error says how to fix it, use "shell" to fix it, then retry.
+6. When instructions complete successfully, return directly — do NOT ask the user.
+7. Group consecutive prints with \\n.
+8. call_llm: ONLY when instructions say "random", "related to", "based on", "adapted", "generate question". If content can be generated directly, do NOT use call_llm.
+9. Use ACTUAL VALUES from conversation history, NOT template variables.
+10. If instructions say to repeat N times, you MUST execute ALL N iterations.
+
+EXAMPLES:
+
+Delegate: { "actionType": "delegate", "intent": "getUser", "data": { "id": "001" } }
+Direct:   { "actionType": "direct", "intent": "print", "message": "User: Alice" }
+Return:   { "actionType": "direct", "intent": "return", "data": { "success": true } }
+
+STATE UPDATES: Include "state_updates" in return data to update agent state:
+{ "actionType": "direct", "intent": "return", "data": { "state_updates": { "count": 5 }, "count": 5 } }
+${resourceSection}${intentNesting}
+
+CRITICAL: Return a single JSON action object, or { "batch": [...] } for independent actions. No markdown.`;
+  }
+
+  // =========================================================================
+  // SMART RESOURCE SECTION
+  // =========================================================================
+
+  /**
+   * Build a smart resource section for system prompts.
+   * THE RULE:
+   *   - If total intents across ALL resources <= 25: show everything (1-step)
+   *   - If total > 25: collapse resources with > 3 intents to summaries (2-step)
+   *
+   * @param {Agent} agent - The agent
+   * @returns {string} Resource documentation for system prompt
+   */
+  async _buildSmartResourceSection(agent) {
+    // 1. Collect ALL resources with their intents
+    const resources = [];
+
+    // Direct actions (from action registry)
+    const directActions = actionRegistry.getAll().filter(a => {
+      if (a.hidden) return false;
+      if (!a.permission) return true;
+      return agent.hasPermission(a.permission);
+    });
+    if (directActions.length > 0) {
+      resources.push({
+        type: 'direct',
+        name: 'Built-in Actions',
+        intents: directActions.map(a => ({
+          name: a.intent || a.type,
+          description: a.description,
+          schema: a.schema,
+          _actionDef: a
+        }))
+      });
+    }
+
+    // Team members (delegation targets)
+    const peerIntents = this._collectPeerIntents(agent);
+    for (const peer of peerIntents) {
+      resources.push({
+        type: 'delegate',
+        name: peer.agentName,
+        intents: peer.handlers.map(h => ({
+          name: h.name,
+          description: h.description,
+          params: h.params
+        }))
+      });
+    }
+
+    // MCP servers
+    const mcpSummaries = agent.getMCPToolsSummary?.() || [];
+    for (const mcp of mcpSummaries) {
+      resources.push({
+        type: 'mcp',
+        name: mcp.name,
+        intents: mcp.tools.map(t => ({
+          name: t.name,
+          description: t.description || t.name,
+          inputSchema: t.inputSchema
+        }))
+      });
+    }
+
+    // 2. Count total intents
+    const totalIntents = resources.reduce((sum, r) => sum + r.intents.length, 0);
+
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`[SmartPrompt] Total intents: ${totalIntents} across ${resources.length} resources`);
+      for (const r of resources) {
+        console.error(`  [${r.type}] ${r.name}: ${r.intents.length} intents`);
+      }
+    }
+
+    // Always expand all resources (1-step)
+    return this._buildExpandedResourceSection(resources, agent);
+  }
+
+  /**
+   * Collect peer intents (handler names + descriptions) from accessible teams.
+   * @param {Agent} agent
+   * @returns {Array<{agentName, handlers: Array<{name, description}>}>}
+   */
+  _collectPeerIntents(agent) {
+    const result = [];
+    const processedAgents = new Set();
+
+    const collectFrom = (member, teamName) => {
+      if (!member || member === agent || processedAgents.has(member.name)) return;
+      processedAgents.add(member.name);
+
+      if (!member.handlers || Object.keys(member.handlers).length === 0) return;
+
+      const handlers = [];
+      for (const [handlerName, handlerFn] of Object.entries(member.handlers)) {
+        let description = `Handle ${handlerName}`;
+        let params = [];
+
+        // Prefer LLM-generated description from build cache
+        if (handlerFn?.__description__) {
+          description = handlerFn.__description__;
+        } else if (handlerFn?.__playbook__) {
+          // Fallback: first line of playbook
+          const firstLine = handlerFn.__playbook__.split('\n')[0].trim();
+          description = firstLine.replace(/\$\{[^}]+\}/g, '...').substring(0, 80);
+        }
+
+        // Extract required params from ${args.X} patterns in playbook
+        if (handlerFn?.__playbook__) {
+          const paramMatches = handlerFn.__playbook__.matchAll(/\$\{args\.(\w+)/g);
+          params = [...new Set([...paramMatches].map(m => m[1]))];
+        }
+
+        handlers.push({ name: handlerName, description, params });
+      }
+
+      result.push({
+        agentName: teamName ? `${member.name} (${teamName})` : member.name,
+        handlers
+      });
+    };
+
+    // Peers team
+    if (agent.peers?.members) {
+      for (const [name, member] of Object.entries(agent.peers.members)) {
+        collectFrom(member, agent.peers.name);
+      }
+    }
+
+    // Uses teams
+    for (const team of (agent.usesTeams || [])) {
+      if (team?.members) {
+        for (const [name, member] of Object.entries(team.members)) {
+          collectFrom(member, team.name);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Build expanded resource section - show all intents directly.
+   * This is the normal behavior when total intents <= 25.
+   */
+  _buildExpandedResourceSection(resources, agent) {
+    let doc = '\nAvailable actions:\n';
+
+    // Built-in actions first
+    for (const resource of resources) {
+      if (resource.type === 'direct') {
+        doc += actionRegistry.generatePromptDocumentation(agent);
+      }
+    }
+
+    // Delegate targets
+    for (const resource of resources) {
+      if (resource.type === 'delegate') {
+        doc += `\n${resource.name} (delegate):\n`;
+        for (const handler of resource.intents) {
+          const dataTemplate = handler.params?.length > 0
+            ? `{ ${handler.params.map(p => `"${p}": ...`).join(', ')} }`
+            : '{ ... }';
+          doc += `- { "actionType": "delegate", "intent": "${handler.name}", "data": ${dataTemplate} } - ${handler.description}\n`;
+        }
+      }
+    }
+
+    // MCP servers — each in its own section
+    for (const resource of resources) {
+      if (resource.type === 'mcp') {
+        doc += `\nMCP "${resource.name}" tools:\n`;
+        for (const tool of resource.intents) {
+          const inputDesc = tool.inputSchema?.properties
+            ? Object.keys(tool.inputSchema.properties).map(k => `"${k}": ...`).join(', ')
+            : '';
+          doc += `- { "intent": "call_mcp", "mcp": "${resource.name}", "tool": "${tool.name}", "input": { ${inputDesc} } } - ${tool.description}\n`;
+        }
+      }
+    }
+
+    return doc;
+  }
+
   /**
    * Generate embeddings for semantic search
    * Uses OpenAI's text-embedding-3-small for fast, cheap embeddings
@@ -1344,18 +1854,19 @@ REMEMBER: Include print actions for ALL output the user should see, UNLESS the i
       throw new Error('getEmbedding requires non-empty text input');
     }
 
-    if (this.provider === 'openai' || this.provider === 'anthropic') {
-      // Always use OpenAI for embeddings (Anthropic doesn't have embeddings API)
+    if (this.provider === 'openai' || this.provider === 'anthropic' || this.provider === 'gemini') {
+      // Always use OpenAI for embeddings (Anthropic/Gemini don't have compatible embeddings API)
       if (!process.env.OPENAI_API_KEY) {
         throw new Error('OPENAI_API_KEY required for embeddings');
       }
 
-      if (!this.openai) {
-        this.openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+      // Use a dedicated OpenAI client for embeddings (Gemini's openai client points elsewhere)
+      if (!this._embeddingClient) {
+        this._embeddingClient = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
       }
 
       try {
-        const response = await this.openai.embeddings.create({
+        const response = await this._embeddingClient.embeddings.create({
           model: 'text-embedding-3-small',
           input: text.trim()
         });