@koi-language/koi 1.0.5 → 1.1.0

package/src/runtime/agent.js

@@ -1,20 +1,101 @@
 import { LLMProvider } from './llm-provider.js';
 import { cliLogger } from './cli-logger.js';
 import { actionRegistry } from './action-registry.js';
+import { PlaybookSession } from './playbook-session.js';
+import { buildActionDisplay } from './cli-display.js';
 
 // Global call stack to detect infinite loops across all agents
 const globalCallStack = [];
 
+
+/**
+ * Use LLM to infer action metadata from playbook
+ * @param {string} playbook - The playbook text
+ * @returns {Promise<{description: string, inputParams: string, returnType: string}>}
+ */
+async function inferActionMetadata(playbook) {
+  try {
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error('[InferActionMetadata] Analyzing playbook...');
+    }
+
+    if (!process.env.OPENAI_API_KEY) {
+      return {
+        description: 'Execute action',
+        inputParams: '{ ... }',
+        returnType: '{ "result": "any" }'
+      };
+    }
+
+    // Call OpenAI API directly
+    const fetch = (await import('node-fetch')).default;
+    const response = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`
+      },
+      body: JSON.stringify({
+        model: 'gpt-4o-mini',
+        temperature: 0,
+        messages: [
+          {
+            role: 'system',
+            content: 'Extract action metadata from agent playbooks. Focus on UNIQUE, SPECIFIC characteristics that distinguish this action from others. Return ONLY valid JSON.'
+          },
+          {
+            role: 'user',
+            content: `Analyze this playbook and identify what makes it UNIQUE:\n\n${playbook}\n\nExtract:\n1. description: What makes THIS action unique and specific (15-20 words). Focus on:\n   - The specific role/persona (e.g., "left-wing activist", "philosopher", "poet")\n   - The unique perspective or style it brings\n   - What differentiates it from similar actions\n   Example: "Generates radical left-wing political response from activist perspective" NOT "Generates response"\n\n2. inputParams: Input parameters structure (look for \${args.X} references)\n   Example: { "context": "string", "conversation": "string" }\n\n3. returnType: Output structure (look for "Return:" or return statements)\n   Example: { "answer": "string" }\n\nRespond with JSON:\n{ "description": "...", "inputParams": "{ ... }", "returnType": "{ ... }" }\n\nNO markdown, NO explanations, ONLY JSON.`
+          }
+        ]
+      })
+    });
+
+    const data = await response.json();
+    let result = data.choices[0].message.content.trim();
+
+    // Clean up response (remove markdown if present)
+    if (result.startsWith('```')) {
+      result = result.replace(/```json?\n?/g, '').replace(/```/g, '').trim();
+    }
+
+    const parsed = JSON.parse(result);
+
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`[InferActionMetadata] Result:`, parsed);
+    }
+
+    return {
+      description: parsed.description || 'Execute action',
+      inputParams: parsed.inputParams || '{ ... }',
+      returnType: parsed.returnType || '{ "result": "any" }'
+    };
+  } catch (error) {
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`[InferActionMetadata] Error: ${error.message}`);
+    }
+    // If inference fails, use defaults
+    return {
+      description: 'Execute action',
+      inputParams: '{ ... }',
+      returnType: '{ "result": "any" }'
+    };
+  }
+}
+
 export class Agent {
   constructor(config) {
     this.name = config.name;
     this.role = config.role;
     this.skills = config.skills || [];
     this.usesTeams = config.usesTeams || []; // Teams this agent uses as a client
+    this.usesMCPNames = config.usesMCP || []; // MCP server names this agent uses
     this.llm = config.llm || { provider: 'openai', model: 'gpt-4', temperature: 0.2 };
     this.state = config.state || {};
     this.playbooks = config.playbooks || {};
     this.resilience = config.resilience || null;
+    this.amnesia = config.amnesia || false;
+    this.memory = []; // Conversation history across playbook executions
 
     // Never allow peers to be null - use a proxy that throws helpful error
     if (config.peers) {
@@ -191,12 +272,19 @@ export class Agent {
 
     // Evaluate template string with context (interpolate ${...} expressions)
     // Create a function that evaluates the template in the context of args and state
+    // Wraps args/state in Proxy so undefined properties resolve to "" instead of "undefined"
     const evaluateTemplate = (template, context) => {
       try {
-        const args = context.args || {};
-        const state = context.state || {};
-        // Use Function constructor to evaluate template string
-        // This allows ${args.url}, ${state.foo}, etc. to be interpolated
+        const safeProxy = (obj) => new Proxy(obj || {}, {
+          get(target, prop) {
+            const val = target[prop];
+            if (val === undefined || val === null) return '';
+            if (typeof val === 'object' && !Array.isArray(val)) return safeProxy(val);
+            return val;
+          }
+        });
+        const args = safeProxy(context.args);
+        const state = safeProxy(context.state);
         const fn = new Function('args', 'state', `return \`${template}\`;`);
         return fn(args, state);
       } catch (error) {
@@ -219,8 +307,41 @@ export class Agent {
       }
     }
 
+    // Agent memory: pass previous conversation history unless amnesia is enabled
+    const memory = this.amnesia ? [] : this.memory;
+    if (process.env.KOI_DEBUG_LLM) {
+      const memoryTokens = this._estimateTokens(this.memory);
+      console.error(`[Agent:${this.name}] 🧠 Memory check: amnesia=${this.amnesia}, messages=${this.memory.length}, ~${memoryTokens} tokens`);
+    }
+
+    // All agents use reactive loop mode (step by step, one action per LLM call)
+    return await this._executePlaybookReactive(eventName, interpolatedPlaybook, args, context, memory);
+  }
+
+  /**
+   * Plan-then-execute mode: send playbook to LLM in ONE call, get ALL actions back.
+   * This is the original execution path, used for delegated tasks.
+   */
+  async _executePlaybookPlanThenExecute(eventName, interpolatedPlaybook, args, context, _fromDelegation, selectedTools, memory = []) {
+    // Connect MCPs eagerly so their tools appear in the system prompt
+    if (this.usesMCPNames.length > 0) {
+      const mcpRegistry = globalThis.mcpRegistry;
+      if (mcpRegistry) {
+        for (const mcpName of this.usesMCPNames) {
+          const client = mcpRegistry.get(mcpName);
+          if (client && !client.initialized) {
+            try {
+              await client.connect();
+            } catch (err) {
+              const cause = client.lastError || err.message;
+              console.error(`[Agent:${this.name}] ❌ MCP "${mcpName}" failed to connect: ${cause}`);
+            }
+          }
+        }
+      }
+    }
+
     // STREAMING OPTIMIZATION: Execute actions incrementally as they arrive
-    // This reduces latency by starting execution before the full JSON is received
     const streamedActions = [];
     const actionContext = {
       state: this.state,
@@ -232,55 +353,42 @@ export class Agent {
     const onStreamAction = async (action) => {
       streamedActions.push(action);
 
-      // Execute action immediately (sequential execution for proper chaining)
       try {
         const resolvedAction = this.resolveActionReferences(action, actionContext);
 
-        // Check condition if present
-        if (resolvedAction.condition !== undefined) {
+        // Check condition if present (but skip for actions that handle their own conditions internally)
+        const actionsWithOwnConditions = ['if', 'while', 'repeat'];
+        if (resolvedAction.condition !== undefined &&
+            !actionsWithOwnConditions.includes(resolvedAction.intent) &&
+            !actionsWithOwnConditions.includes(resolvedAction.type)) {
           const conditionMet = this.evaluateCondition(resolvedAction.condition, actionContext);
           if (!conditionMet) {
-            return; // Skip this action
+            return;
           }
         }
 
-        const intent = resolvedAction.intent || resolvedAction.type || resolvedAction.description;
-        const actionTitle = resolvedAction.title || intent;
-        cliLogger.progress(`[${this.name}] ${actionTitle}`);
+        cliLogger.planning(buildActionDisplay(this.name, resolvedAction));
 
-        let result;
-
-        // Check if this is a delegation action
-        if (action.actionType === 'delegate') {
-          // Delegation: route to appropriate team member
-          if (process.env.KOI_DEBUG_LLM) {
-            console.error(`[Agent:${this.name}] 🔀 Delegating action: ${action.intent}`);
-          }
-          result = await this.resolveAction(resolvedAction, actionContext);
-        } else {
-          // Direct action: check if this is a registered action with an executor
-          const actionDef = actionRegistry.get(action.intent || action.type);
-
-          if (actionDef && actionDef.execute) {
-            // Fast path: execute registered action
-            result = await actionDef.execute(resolvedAction, this);
-          } else if (action.intent || action.description) {
-            // Resolve via router (legacy fallback)
-            result = await this.resolveAction(resolvedAction, actionContext);
-          } else {
-            // Fallback legacy
-            result = await this.executeLegacyAction(resolvedAction);
-          }
-        }
+        const { result } = await this._executeAction(action, resolvedAction, actionContext);
 
         cliLogger.clear();
 
-        // Update context for next action (chaining)
         if (result && typeof result === 'object') {
-          const resultForContext = JSON.parse(JSON.stringify(result));
+          let unwrappedResult = result;
+          if (result.result && typeof result.result === 'string' && Object.keys(result).length === 1) {
+            try {
+              const parsed = JSON.parse(result.result);
+              if (typeof parsed === 'object') {
+                unwrappedResult = parsed;
+              }
+            } catch (e) {
+              // Not JSON, keep as-is
+            }
+          }
+
+          const resultForContext = JSON.parse(JSON.stringify(unwrappedResult));
           actionContext.results.push(resultForContext);
 
-          // Store result with action ID for explicit referencing
           if (action.id) {
             actionContext[action.id] = { output: resultForContext };
 
@@ -290,11 +398,8 @@ export class Agent {
             }
           }
 
-          // Only update previousResult for actions that produce meaningful data
-          // Side-effect actions like print, log (that return metadata) should not override previousResult
           const nonDataActions = ['print', 'log', 'format'];
-
-          if (!nonDataActions.includes(intent)) {
+          if (!nonDataActions.includes(action.intent || action.type)) {
             actionContext.previousResult = resultForContext;
             actionContext.lastResult = resultForContext;
           }
@@ -312,7 +417,6 @@ export class Agent {
       }
     };
 
-    // Execute playbook with streaming (onAction callback receives each action as it completes)
     const result = await this.llmProvider.executePlaybook(
       interpolatedPlaybook,
       context,
@@ -320,16 +424,37 @@ export class Agent {
       selectedTools,
       this,
       _fromDelegation,
-      onStreamAction  // Pass callback for incremental execution
+      onStreamAction,
+      memory
     );
 
-    // If streaming was used, actions were already executed
     if (streamedActions.length > 0) {
-      // Actions already executed via streaming - return final result from context
-      const finalResult = actionContext.results.length > 0
+      let finalResult = actionContext.results.length > 0
         ? actionContext.results[actionContext.results.length - 1]
         : {};
 
+      // Apply state updates if returned by LLM (streaming path)
+      if (finalResult && typeof finalResult === 'object') {
+        if (finalResult.state_updates || finalResult.stateUpdates) {
+          const updates = finalResult.state_updates || finalResult.stateUpdates;
+          Object.keys(updates).forEach(key => {
+            this.state[key] = updates[key];
+          });
+          // Strip state_updates from returned result
+          const { state_updates, stateUpdates, ...resultData } = finalResult;
+          finalResult = resultData;
+        }
+      }
+
+      // Save conversation to agent memory (unless amnesia is enabled)
+      // Save the ACTUAL executed result, not the raw LLM action plan
+      if (!this.amnesia) {
+        this._saveToMemory([
+          { role: 'user', content: interpolatedPlaybook },
+          { role: 'assistant', content: JSON.stringify(finalResult) }
+        ]);
+      }
+
       if (actionContext.results.length > 1) {
         return {
           ...finalResult,
@@ -341,13 +466,18 @@ export class Agent {
       return finalResult;
     }
 
+    // Save conversation to agent memory for non-streaming path
+    if (!this.amnesia) {
+      this._saveToMemory([
+        { role: 'user', content: interpolatedPlaybook },
+        { role: 'assistant', content: JSON.stringify(result) }
+      ]);
+    }
+
     // No streaming - handle traditional execution path
-    // Handle malformed responses - if LLM didn't return actions or result, try to extract
     if (result && !result.actions && !result.result) {
-      // LLM returned unexpected format - try to find actions in other fields
       for (const key of Object.keys(result)) {
         if (Array.isArray(result[key]) && result[key].length > 0 && result[key][0].type) {
-          // Found array of actions under different key
           console.warn(`[${this.name}] ⚠️  LLM returned actions under "${key}" instead of "actions" - fixing`);
           result.actions = result[key];
           delete result[key];
@@ -356,29 +486,14 @@ export class Agent {
       }
     }
 
-    // Check if LLM returned actions (new action-based system)
     if (result && result.actions && Array.isArray(result.actions)) {
-      // Decision: Should this agent execute actions or return them?
-      //
-      // Execute actions if:
-      // - NOT called from delegation (orchestrators always execute)
-      // - OR agent is a specialized worker (has no teams to delegate to)
-      //   Workers should execute their specialized actions (registry ops, tool calls, etc.)
-      //   even when called from delegation
       const canDelegateToTeams = this.usesTeams && this.usesTeams.length > 0;
       const shouldExecuteActions = !_fromDelegation || !canDelegateToTeams;
 
       if (shouldExecuteActions) {
-        // Don't log action count - not useful information
-        // console.log(`[${this.name}] → ${result.actions.length} actions`);
-
-        // Extract any additional fields the LLM provided (plan, explanation, etc.)
         const { actions, ...additionalFields } = result;
-
-        // Execute the actions
         const actionResults = await this.executeActions(actions);
 
-        // If there are additional fields, merge them with the action results
         if (Object.keys(additionalFields).length > 0) {
           return {
             ...additionalFields,
@@ -388,14 +503,9 @@ export class Agent {
 
         return actionResults;
       } else {
-        // Agent is an orchestrator called from delegation - don't execute nested delegation
-        // (This prevents infinite loops where orchestrators try to delegate from within delegation)
         console.log(`[${this.name}] ⚠️  Ignoring nested actions (orchestrator in delegated call)`);
-
-        // Return the result without the actions field
         const { actions, ...actualResult } = result;
 
-        // If there's no other data besides actions, try to extract from first action
         if (Object.keys(actualResult).length === 0 && actions.length > 0) {
           const firstAction = actions[0];
           return firstAction.data || firstAction.result || {};
@@ -407,17 +517,13 @@ export class Agent {
 
     // Legacy support: Apply state updates if returned by LLM
     if (result && typeof result === 'object') {
-      // Check if LLM returned state updates
       if (result.state_updates || result.stateUpdates) {
         const updates = result.state_updates || result.stateUpdates;
-
-        // Apply updates to agent state
         Object.keys(updates).forEach(key => {
           this.state[key] = updates[key];
         });
       }
 
-      // If result has both state_updates and other fields, return just the result fields
       if (result.state_updates || result.stateUpdates) {
         const { state_updates, stateUpdates, ...resultData } = result;
         return resultData;
@@ -427,6 +533,259 @@ export class Agent {
     return result;
   }
 
+  /**
+   * Reactive agentic loop: LLM decides ONE action per iteration,
+   * receives feedback, and adapts its strategy.
+   * Used for top-level orchestration (not delegated tasks).
+   */
+  async _executePlaybookReactive(eventName, interpolatedPlaybook, args, context, memory = []) {
+    const session = new PlaybookSession({
+      playbook: interpolatedPlaybook,
+      agentName: this.name
+    });
+    session.actionContext.args = args;
+    session.actionContext.state = this.state;
+
+    // Seed conversation history with previous memory
+    const conversationHistory = [];
+    if (memory.length > 0) {
+      // Build system prompt first (needed as sentinel for provider extraction)
+      const systemPrompt = await this.llmProvider._buildReactiveSystemPrompt(this);
+      conversationHistory.push({ _system: systemPrompt });
+      // Insert previous conversation turns as context
+      conversationHistory.push(...memory);
+    }
+
+    // Connect MCPs eagerly so their tools appear in the system prompt
+    const mcpErrors = {};
+    if (this.usesMCPNames.length > 0) {
+      const mcpRegistry = globalThis.mcpRegistry;
+      if (mcpRegistry) {
+        for (const mcpName of this.usesMCPNames) {
+          const client = mcpRegistry.get(mcpName);
+          if (client && !client.initialized) {
+            try {
+              await client.connect();
+            } catch (err) {
+              const cause = client.lastError || err.message;
+              mcpErrors[mcpName] = cause;
+              console.error(`[Agent:${this.name}] ❌ MCP "${mcpName}" failed to connect: ${cause}`);
+            }
+          }
+        }
+      }
+    }
+
+    // If any MCPs failed, inject the errors so the LLM knows
+    if (Object.keys(mcpErrors).length > 0) {
+      session.mcpErrors = mcpErrors;
+    }
+
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`[Agent:${this.name}] 🔄 Starting reactive loop`);
+    }
+
+    let isFirstCall = true;
+    while (session.canContinue()) {
+      // 1. GET ACTION(S) from LLM — may be a single action or a batched array
+      let response;
+      try {
+        response = await this.llmProvider.executePlaybookReactive({
+          playbook: interpolatedPlaybook,
+          context,
+          agentName: this.name,
+          session,
+          agent: this,
+          conversationHistory,
+          isFirstCall
+        });
+        isFirstCall = false;
+      } catch (error) {
+        if (process.env.KOI_DEBUG_LLM) {
+          console.error(`[Agent:${this.name}] ❌ LLM call failed: ${error.message}`);
+        }
+        session.recordAction({ intent: '_llm_error', actionType: 'direct' }, null, error);
+        continue;
+      }
+
+      // Normalize to array for uniform processing
+      const actionBatch = Array.isArray(response) ? response : [response];
+
+      if (process.env.KOI_DEBUG_LLM && actionBatch.length > 1) {
+        console.error(`[Agent:${this.name}] 📦 Batched ${actionBatch.length} actions`);
+      }
+
+      // Process each action in the batch sequentially
+      let terminated = false;
+      for (const action of actionBatch) {
+        if (!session.canContinue()) break;
+
+        if (process.env.KOI_DEBUG_LLM) {
+          const intent = action.intent || action.type || 'unknown';
+          console.error(`[Agent:${this.name}] 🎯 Reactive step ${session.iteration + 1}: ${intent}`);
+        }
+
+        // CHECK TERMINAL ACTION
+        if ((action.intent || action.type) === 'return') {
+          const resolved = this.resolveActionReferences(action, session.actionContext);
+          let returnData = resolved.data || {};
+
+          // Apply state updates if present
+          if (returnData && typeof returnData === 'object' && (returnData.state_updates || returnData.stateUpdates)) {
+            const updates = returnData.state_updates || returnData.stateUpdates;
+            Object.keys(updates).forEach(key => {
+              this.state[key] = updates[key];
+            });
+            const { state_updates, stateUpdates, ...cleanData } = returnData;
+            returnData = cleanData;
+          }
+
+          session.terminate(returnData);
+          terminated = true;
+          break;
+        }
+
+        // EXECUTE ACTION (reusing _executeAction)
+        try {
+          const resolved = this.resolveActionReferences(action, session.actionContext);
+
+          // Check condition (skip for actions that handle their own conditions)
+          const actionsWithOwnConditions = ['if', 'while', 'repeat'];
+          if (resolved.condition !== undefined &&
+              !actionsWithOwnConditions.includes(resolved.intent) &&
+              !actionsWithOwnConditions.includes(resolved.type)) {
+            if (!this.evaluateCondition(resolved.condition, session.actionContext)) {
+              session.recordAction(action, { skipped: true });
+              continue;
+            }
+          }
+
+          cliLogger.planning(buildActionDisplay(this.name, resolved));
+
+          const { result } = await this._executeAction(action, resolved, session.actionContext);
+
+          cliLogger.clear();
+          session.recordAction(action, result);
+
+          if (process.env.KOI_DEBUG_LLM) {
+            const preview = result ? JSON.stringify(result).substring(0, 150) : 'null';
+            console.error(`[Agent:${this.name}] ✅ Result: ${preview}`);
+          }
+        } catch (error) {
+          cliLogger.clear();
+          if (process.env.KOI_DEBUG_LLM) {
+            console.error(`[Agent:${this.name}] ❌ Action failed: ${error.message}`);
+          }
+          session.recordAction(action, null, error);
+          // On error in a batch, stop processing remaining actions so LLM can react
+          break;
+        }
+      }
+
+      if (terminated) break;
+    }
+
+    if (process.env.KOI_DEBUG_LLM) {
+      console.error(`[Agent:${this.name}] 🔄 Reactive loop finished after ${session.iteration} iterations`);
+    }
+
+    // Save conversation to agent memory (unless amnesia is enabled)
+    if (!this.amnesia) {
+      // Extract only user/assistant messages (skip system sentinel)
+      const newMessages = conversationHistory.filter(m => m.role === 'user' || m.role === 'assistant');
+      // Only save the new messages (skip the ones that came from previous memory)
+      const newCount = newMessages.length - memory.length;
+      if (newCount > 0) {
+        this._saveToMemory(newMessages.slice(-newCount));
+      }
+    }
+
+    // Return final result
+    if (session.finalResult) return session.finalResult;
+
+    // Fallback: return last result if loop exhausted
+    const results = session.actionContext.results;
+    return results.length > 0 ? results[results.length - 1] : {};
+  }
+
+  /**
+   * Save messages to agent memory, trimming to max size.
+   * @private
+   */
+  _saveToMemory(messages) {
+    const maxMemory = this.llm.maxMemory || 50;
+    this.memory.push(...messages);
+    if (this.memory.length > maxMemory) {
+      // Trim oldest messages, keeping the last maxMemory entries
+      this.memory = this.memory.slice(-maxMemory);
+    }
+    if (process.env.KOI_DEBUG_LLM) {
+      const memoryTokens = this._estimateTokens(this.memory);
+      console.error(`[Agent:${this.name}] 🧠 Memory saved (${this.memory.length} messages, ~${memoryTokens} tokens)`);
+    }
+  }
+
+  /**
+   * Estimate token count for an array of messages (~4 chars per token).
+   * @private
+   */
+  _estimateTokens(messages) {
+    let chars = 0;
+    for (const msg of messages) {
+      if (typeof msg.content === 'string') {
+        chars += msg.content.length;
+      } else if (msg.content) {
+        chars += JSON.stringify(msg.content).length;
+      }
+      if (msg.role) chars += msg.role.length;
+    }
+    return Math.ceil(chars / 4);
+  }
+
+  /**
+   * Execute a single action (common code for both streaming and batch execution)
+   * @private
+   * @returns {Object} { result, shouldExitLoop }
+   */
+  async _executeAction(action, resolvedAction, context) {
+    const actionRegistry = (await import('./action-registry.js')).actionRegistry;
+    let result;
+    let shouldExitLoop = false;
+
+    // Check if this is a delegation action
+    if (action.actionType === 'delegate') {
+      // Delegation: route to appropriate team member
+      if (process.env.KOI_DEBUG_LLM) {
+        console.error(`[Agent:${this.name}] 🔀 Delegating action: ${action.intent}`);
+      }
+      result = await this.resolveAction(resolvedAction, context);
+    } else {
+      // Direct action: check if this is a registered action with an executor
+      const actionDef = actionRegistry.get(action.intent || action.type);
+
+      if (actionDef && actionDef.execute) {
+        // Fast path: execute registered action
+        // Store current context in agent for actions that need it (like 'if', 'while', etc.)
+        this._currentActionContext = context;
+        result = await actionDef.execute(resolvedAction, this);
+        delete this._currentActionContext;
+
+        // Special handling for return action with conditions
+        if ((action.intent === 'return' || action.type === 'return') && action.condition !== undefined) {
+          shouldExitLoop = true;
+        }
+      } else if (action.intent || action.description) {
+        // Resolve via router (legacy fallback)
+        result = await this.resolveAction(resolvedAction, context);
+      } else {
+        // Fallback legacy
+        result = await this.executeLegacyAction(resolvedAction);
+      }
+    }
+
+    return { result, shouldExitLoop };
+  }
+
   async executeActions(actions) {
     let finalResult = {};
     let context = {
@@ -442,7 +801,8 @@ export class Agent {
 
       // Check if action has a condition - skip if condition is false
       // IMPORTANT: Evaluate condition BEFORE the action executes, using current context
-      if (resolvedAction.condition !== undefined) {
+      // EXCEPTION: Skip this check for "if" action which handles its own condition internally
+      if (resolvedAction.condition !== undefined && resolvedAction.intent !== 'if' && resolvedAction.type !== 'if') {
         const conditionMet = this.evaluateCondition(resolvedAction.condition, context);
         if (!conditionMet) {
           // Skip this action silently
@@ -455,37 +815,18 @@ export class Agent {
       // Show what action is being executed
       // Use the "title" field if the LLM provided one, otherwise use intent
       const actionTitle = resolvedAction.title || intent;
-      cliLogger.progress(`[${this.name}] ${actionTitle}`);
-
-      // Check if this is a delegation action
-      if (action.actionType === 'delegate') {
-        // Delegation: route to appropriate team member
-        if (process.env.KOI_DEBUG_LLM) {
-          console.error(`[Agent:${this.name}] 🔀 Delegating action: ${action.intent}`);
-        }
-        finalResult = await this.resolveAction(resolvedAction, context);
-      } else {
-        // Direct action: check if this is a registered action with an executor
-        const actionDef = actionRegistry.get(action.intent || action.type);
-
-        if (actionDef && actionDef.execute) {
-          // Fast path: execute registered action
-          finalResult = await actionDef.execute(resolvedAction, this);
-
-          // Special handling for return action with conditions
-          if ((action.intent === 'return' || action.type === 'return') && action.condition !== undefined) {
-            context.results.push(finalResult);
-            context.previousResult = finalResult;
-            context.lastResult = finalResult;
-            i = actions.length; // Exit loop
-          }
-        } else if (action.intent || action.description) {
-          // Resolve via router (legacy fallback)
-          finalResult = await this.resolveAction(resolvedAction, context);
-        } else {
-          // Fallback legacy
-          finalResult = await this.executeLegacyAction(resolvedAction);
-        }
+      cliLogger.progress(`[${this.name}] Thinking...`);
+
+      // Execute the action using common method
+      const { result, shouldExitLoop } = await this._executeAction(action, resolvedAction, context);
+      finalResult = result;
+
+      // Handle special return action with conditions
+      if (shouldExitLoop) {
+        context.results.push(finalResult);
+        context.previousResult = finalResult;
+        context.lastResult = finalResult;
+        i = actions.length; // Exit loop
       }
 
       // Clear progress after action completes
@@ -572,10 +913,6 @@ export class Agent {
     // Deep clone to avoid mutating original
     const resolved = JSON.parse(JSON.stringify(action));
 
-    if (process.env.KOI_DEBUG_LLM) {
-      console.error(`[Agent:${this.name}] 🔄 Resolving references for action: ${action.intent || action.type}`);
-    }
-
     // DON'T resolve condition here - it will be evaluated directly in evaluateCondition()
     // (Conditions need special handling to preserve boolean expressions)
 
@@ -611,6 +948,23 @@ export class Agent {
       resolved.text = this.resolveObjectReferences(resolved.text, context);
     }
 
+    // Resolve references in question field (for prompt_user action)
+    if (resolved.question !== undefined) {
+      resolved.question = this.resolveObjectReferences(resolved.question, context);
+    }
+
+    // Resolve references in mcp/tool fields (for call_mcp action)
+    if (resolved.mcp !== undefined) {
+      resolved.mcp = this.resolveObjectReferences(resolved.mcp, context);
+    }
+    if (resolved.tool !== undefined) {
+      resolved.tool = this.resolveObjectReferences(resolved.tool, context);
+    }
+
+    if (resolved.description !== undefined) {
+      resolved.description = this.resolveObjectReferences(resolved.description, context);
+    }
+
     return resolved;
   }
 
@@ -628,9 +982,10 @@ export class Agent {
       JSON, // Allow JSON methods
       Math  // Allow Math methods
     };
-    // Add all action IDs from context (a1, a2, a3, etc.)
+    // Add all action IDs from context (any key with .output)
+    const reservedKeys = ['previousResult', 'lastResult', 'results', 'state', 'args'];
     for (const key in context) {
-      if (key.match(/^a\d+$/)) { // Match action IDs like a1, a2, a3...
+      if (!reservedKeys.includes(key) && context[key]?.output !== undefined) {
         evalContext[key] = context[key];
       }
     }
@@ -773,8 +1128,15 @@ export class Agent {
           const evalContext = { ...this.buildEvalContext(context), ...context };
           const fn = new Function(...Object.keys(evalContext), `return ${expr};`);
           const result = fn(...Object.values(evalContext));
-          // Convert to string for template interpolation
-          return typeof result === 'object' ? JSON.stringify(result) : String(result);
+          // Convert to proper JavaScript literal for condition evaluation
+          if (typeof result === 'string') {
+            // Quote strings properly to avoid "undefined variable" errors
+            return `'${result.replace(/'/g, "\\'")}'`;
+          } else if (typeof result === 'object') {
+            return JSON.stringify(result);
+          } else {
+            return String(result);
+          }
         } catch (error) {
           console.warn(`[Agent:${this.name}] Failed to evaluate condition sub-expression "${expr}": ${error.message}`);
           return match;
@@ -835,7 +1197,7 @@ export class Agent {
       // 2️⃣ Do I have a matching skill?
       const matchingSkill = this.findMatchingSkill(intent);
       if (matchingSkill) {
-        cliLogger.progress(`  → [${this.name}] skill:${matchingSkill}...`);
+        cliLogger.planning(buildActionDisplay(this.name, action));
         const result = await this.callSkill(matchingSkill, action.data || action.input || {});
         cliLogger.clear();
         globalCallStack.pop();
@@ -844,6 +1206,12 @@ export class Agent {
 
       // 3️⃣ Can someone in my teams handle it? (check peers + usesTeams)
       if (this.peers || this.usesTeams.length > 0) {
+        // Check delegate permission
+        if (!this.hasPermission('delegate')) {
+          globalCallStack.pop();
+          throw new Error(`Agent "${this.name}" cannot delegate: role "${this.role?.name || 'unknown'}" lacks "can delegate" permission.`);
+        }
+
         // Search within team members - team defines communication boundaries
         const teamMember = await this.findTeamMemberForIntent(intent);
 
@@ -913,20 +1281,13 @@ export class Agent {
       return null;
     }
 
-    const { agentRouter } = await import('./router.js');
-
-    // Get all potential matches from the global router
-    let matches = await agentRouter.findMatches(intent, 10);
-
     // Collect all teams this agent can access
     const accessibleTeams = [];
 
-    // Add peers team (if this agent is a member of a team)
     if (this.peers && this.peers.members) {
       accessibleTeams.push(this.peers);
     }
 
-    // Add usesTeams (teams this agent uses as a client)
     for (const team of this.usesTeams) {
       if (team && team.members) {
         accessibleTeams.push(team);
@@ -937,18 +1298,34 @@ export class Agent {
       return null;
     }
 
-    // Filter to only include agents that are in accessible teams
+    // 1. Try direct handler name matching first (no LLM call needed!)
+    for (const team of accessibleTeams) {
+      for (const memberName of Object.keys(team.members)) {
+        const member = team.members[memberName];
+        if (member === this) continue;
+
+        const matchingEvent = member.findMatchingHandler(intent);
+        if (matchingEvent) {
+          if (process.env.KOI_DEBUG_LLM) {
+            console.error(`[Agent:${this.name}] ✅ Direct match: ${member.name}.${matchingEvent} for intent "${intent}"`);
+          }
+          return { agent: member, event: matchingEvent };
+        }
+      }
+    }
+
+    // 2. No direct match — use semantic router as fallback
+    const { agentRouter } = await import('./router.js');
+    let matches = await agentRouter.findMatches(intent, 10);
+
+    // Filter to only include agents in accessible teams (exclude self)
     matches = matches.filter(match => {
-      // Check if this agent is in any accessible team
       const isAccessible = accessibleTeams.some(team => {
-        const teamMemberNames = Object.keys(team.members);
-        return teamMemberNames.some(name => {
+        return Object.keys(team.members).some(name => {
           const member = team.members[name];
           return member === match.agent || member.name === match.agent.name;
         });
       });
-
-      // Also exclude self
       return isAccessible && match.agent !== this;
     });
 
@@ -956,20 +1333,6 @@ export class Agent {
       return matches[0];
     }
 
-    // Fallback: Try direct handler matching in accessible team members
-    for (const team of accessibleTeams) {
-      const memberNames = Object.keys(team.members);
-      for (const memberName of memberNames) {
-        const member = team.members[memberName];
-        if (member === this) continue; // Skip self
-
-        const matchingEvent = member.findMatchingHandler(intent);
-        if (matchingEvent) {
-          return { agent: member, event: matchingEvent };
-        }
-      }
-    }
-
     return null;
   }
 
@@ -1115,12 +1478,12 @@ export class Agent {
    * Generate peer capabilities formatted as available actions
    * Returns a string listing delegation actions in the same format as action registry
    */
-  getPeerCapabilitiesAsActions() {
+  async getPeerCapabilitiesAsActions() {
     const capabilities = [];
     const processedAgents = new Set();
 
     // Helper function to collect handlers from an agent
-    const collectHandlers = (agent, teamName = null) => {
+    const collectHandlers = async (agent, teamName = null) => {
       if (!agent || processedAgents.has(agent.name)) {
         return;
       }
@@ -1133,46 +1496,40 @@ export class Agent {
 
           // Extract affordance/description from handler
           let description = '';
+          let inputParams = '{ ... }';
+          let returnType = null;
           const handlerFn = agent.handlers[handler];
 
           if (handlerFn && handlerFn.__playbook__) {
-            // Extract first line or first sentence from playbook as description
             const playbook = handlerFn.__playbook__;
-            const lines = playbook.split('\n');
-            const firstLine = lines[0].trim();
 
-            // Remove template variables for cleaner description
-            description = firstLine.replace(/\$\{[^}]+\}/g, '...').substring(0, 80);
-            if (description.length < firstLine.length) {
-              description += '...';
+            if (process.env.KOI_DEBUG_LLM) {
+              console.error(`[CollectHandlers] Found playbook for ${handler}, length: ${playbook.length}`);
             }
 
-            // Try to extract return structure from playbook
-            // Look for patterns like "return: { ... }" or "2. Return: { ... }"
-            for (const line of lines) {
-              const returnMatch = line.match(/(?:return|Return):\s*\{([^}]+)\}/i);
-              if (returnMatch) {
-                // Found a return statement - extract key structure
-                const returnContent = returnMatch[1];
-                // Extract field names (simple parsing)
-                const fields = returnContent.match(/"([^"]+)":/g);
-                if (fields) {
-                  const fieldNames = fields.map(f => f.replace(/[":]/g, '')).join(', ');
-                  description += ` → Returns: {${fieldNames}}`;
-                }
-                break;
-              }
+            // Use LLM to infer metadata from playbook
+            const metadata = await inferActionMetadata(playbook);
+            description = metadata.description;
+            inputParams = metadata.inputParams;
+            returnType = metadata.returnType;
+
+            if (process.env.KOI_DEBUG_LLM) {
+              console.error(`[CollectHandlers] Inferred metadata for ${handler}:`, metadata);
             }
           } else if (handlerFn && typeof handlerFn === 'function') {
             // For regular functions, generate description from name
             description = `Handle ${handler} event`;
+            inputParams = '{ ... }';
+            returnType = '{ "result": "any" }';
           }
 
           capabilities.push({
             intent: handler,
             agent: agentInfo,
             role: agent.role ? agent.role.name : 'Unknown',
-            description: description || `Execute ${handler}`
+            description: description || `Execute ${handler}`,
+            inputParams: inputParams,
+            returnType: returnType || '{ "result": "any" }'
           });
         }
       }
@@ -1184,7 +1541,7 @@ export class Agent {
       for (const memberName of memberNames) {
         const member = this.peers.members[memberName];
         if (member !== this) {
-          collectHandlers(member, this.peers.name);
+          await collectHandlers(member, this.peers.name);
         }
       }
     }
@@ -1195,7 +1552,7 @@ export class Agent {
         const memberNames = Object.keys(team.members);
         for (const memberName of memberNames) {
           const member = team.members[memberName];
-          collectHandlers(member, team.name);
+          await collectHandlers(member, team.name);
         }
       }
     }
@@ -1206,7 +1563,8 @@ export class Agent {
 
     let doc = '\n\nDelegation actions (to team members):\n';
     for (const cap of capabilities) {
-      doc += `- { "actionType": "delegate", "intent": "${cap.intent}", "data": ... } - ${cap.description} (Delegate to ${cap.agent} [${cap.role}])\n`;
+      // Build delegation description with inferred metadata
+      doc += `- { "actionType": "delegate", "intent": "${cap.intent}", "data": ${cap.inputParams} } - ${cap.description} → Returns: ${cap.returnType} (Delegate to ${cap.agent} [${cap.role}])\n`;
     }
 
     return doc;
@@ -1324,17 +1682,48 @@ Execute this task and return the result as JSON.
   }
 
 
-  async callSkill(skillName, input) {
-    // Calling skill
-
+  async callSkill(skillName, functionNameOrInput, inputOrUndefined) {
     if (!this.skills.includes(skillName)) {
       throw new Error(`Agent ${this.name} does not have skill: ${skillName}`);
     }
 
-    // In a real implementation, this would look up and execute the skill
-    // For now, we'll simulate it
-    // Skill processing
-    return { success: true, skill: skillName, input };
+    // Support two calling conventions:
+    // 1. callSkill(skillName, functionName, input) - call specific function
+    // 2. callSkill(skillName, input) - legacy: find matching function by intent
+    let functionName, input;
+
+    if (inputOrUndefined !== undefined) {
+      // Convention 1: explicit function name
+      functionName = functionNameOrInput;
+      input = inputOrUndefined;
+    } else {
+      // Convention 2: auto-select function (legacy)
+      input = functionNameOrInput;
+
+      // Try to find a matching function using skill selector
+      // For now, we'll just use the first available function
+      const skillFunctions = globalThis.SkillRegistry?.getAll(skillName);
+      if (!skillFunctions || Object.keys(skillFunctions).length === 0) {
+        throw new Error(`No functions found in skill: ${skillName}`);
+      }
+
+      functionName = Object.keys(skillFunctions)[0];
+    }
+
+    // Get the function from SkillRegistry
+    const skillFunction = globalThis.SkillRegistry?.get(skillName, functionName);
+
+    if (!skillFunction) {
+      throw new Error(`Function ${functionName} not found in skill ${skillName}`);
+    }
+
+    // Execute the skill function
+    try {
+      const result = await skillFunction.fn(input);
+      return result;
+    } catch (error) {
+      throw new Error(`Skill ${skillName}.${functionName} failed: ${error.message}`);
+    }
   }
 
   /**
@@ -1362,6 +1751,31 @@ Execute this task and return the result as JSON.
   }
 
 
+  /**
+   * Get MCP tool summaries for system prompt generation.
+   * Returns tool info from all MCP servers this agent has access to.
+   */
+  getMCPToolsSummary() {
+    const mcpRegistry = globalThis.mcpRegistry;
+    if (!mcpRegistry || this.usesMCPNames.length === 0) return [];
+
+    const summaries = [];
+    for (const mcpName of this.usesMCPNames) {
+      const client = mcpRegistry.get(mcpName);
+      if (client && client.tools.length > 0) {
+        summaries.push({
+          name: mcpName,
+          tools: client.tools.map(t => ({
+            name: t.name,
+            description: t.description || '',
+            inputSchema: t.inputSchema
+          }))
+        });
+      }
+    }
+    return summaries;
+  }
+
   toString() {
     return `Agent(${this.name}:${this.role.name})`;
   }