@koi-language/koi 1.0.5 → 1.1.0

package/src/runtime/playbook-session.js

@@ -0,0 +1,259 @@
+/**
+ * PlaybookSession - Tracks state for the reactive agentic loop.
+ *
+ * In reactive mode, the LLM decides ONE action per iteration,
+ * receives feedback from the result, and adapts its strategy.
+ * This class maintains the state across iterations.
+ *
+ * The loop runs indefinitely until the agent decides to terminate
+ * via a "return" action, or consecutive errors exceed the threshold.
+ */
+export class PlaybookSession {
+  constructor({ playbook, agentName } = {}) {
+    this.playbook = playbook;
+    this.agentName = agentName;
+
+    // Iteration tracking
+    this.iteration = 0;
+    this.isTerminated = false;
+    this.finalResult = null;
+
+    // Action history: { action, result, error, timestamp, iteration }
+    this.actionHistory = [];
+
+    // Action context: accumulates results for template variables (${a1.output.field})
+    // Same structure as actionContext in agent.js
+    this.actionContext = {
+      state: {},
+      results: [],
+      args: {}
+    };
+
+    // Error tracking
+    this.lastError = null;
+    this.consecutiveErrors = 0;
+    this.maxConsecutiveErrors = 10;
+  }
+
+  /**
+   * Check if the loop can continue.
+   * The loop only stops when the agent terminates or consecutive errors exceed threshold.
+   */
+  canContinue() {
+    return (
+      !this.isTerminated &&
+      this.consecutiveErrors < this.maxConsecutiveErrors
+    );
+  }
+
+  /**
+   * Record an action and its result/error.
+   * Updates actionContext with the same chaining logic as agent.js.
+   */
+  recordAction(action, result, error = null) {
+    this.iteration++;
+
+    const entry = {
+      action,
+      result: result || null,
+      error: error ? { message: error.message || String(error) } : null,
+      timestamp: Date.now(),
+      iteration: this.iteration
+    };
+
+    this.actionHistory.push(entry);
+
+    if (error) {
+      this.lastError = error;
+      this.consecutiveErrors++;
+    } else {
+      this.lastError = null;
+      this.consecutiveErrors = 0;
+
+      // Update actionContext (same logic as agent.js onStreamAction)
+      if (result && typeof result === 'object') {
+        // Unwrap double-encoded results
+        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));
+        this.actionContext.results.push(resultForContext);
+
+        // Store result with action ID for explicit referencing
+        if (action.id) {
+          this.actionContext[action.id] = { output: resultForContext };
+        }
+
+        // Only update previousResult for actions that produce meaningful data
+        const intent = action.intent || action.type;
+        const nonDataActions = ['print', 'log', 'format'];
+
+        if (!nonDataActions.includes(intent)) {
+          this.actionContext.previousResult = resultForContext;
+          this.actionContext.lastResult = resultForContext;
+        }
+
+        // Make result fields directly accessible
+        Object.keys(resultForContext).forEach(key => {
+          if (!this.actionContext[key]) {
+            this.actionContext[key] = resultForContext[key];
+          }
+        });
+      }
+    }
+  }
+
+  /**
+   * Terminate the loop with a final result
+   */
+  terminate(result) {
+    this.isTerminated = true;
+    this.finalResult = result;
+  }
+
+  /**
+   * Build feedback context for the next LLM iteration.
+   * Kept MINIMAL to avoid context bloat — the LLM already has
+   * the full conversation history with all previous actions/results.
+   */
+  buildFeedbackContext() {
+    const parts = [];
+
+    // Error feedback
+    if (this.lastError) {
+      const errorMsg = this.lastError.message || String(this.lastError);
+      parts.push(`\u274c LAST ACTION FAILED: ${errorMsg}`);
+
+      // Count recent MCP errors to suggest diagnostics
+      const recentMcpErrors = this.actionHistory.slice(-5).filter(
+        e => e.error && (e.action.intent === 'call_mcp' || e.action.type === 'call_mcp')
+      ).length;
+
+      if (recentMcpErrors >= 2) {
+        parts.push('Multiple MCP failures detected. DIAGNOSE: check available tools on that MCP server for status/diagnostic tools and use them to understand the current state before retrying. The MCP server may have been restarted automatically.');
+      }
+
+      parts.push('NEVER give up. Try a DIFFERENT approach — do NOT repeat the same action that failed. Think about what went wrong and find an alternative path to achieve the goal.');
+    }
+
+    // Loop detection warnings
+    const warnings = this._detectLoops();
+    for (const warning of warnings) {
+      parts.push(`\u26a0\ufe0f ${warning}`);
+    }
+
+    // Last action result
+    const lastEntry = this.actionHistory[this.actionHistory.length - 1];
+    if (lastEntry && !lastEntry.error) {
+      const intent = lastEntry.action.intent || lastEntry.action.type || 'unknown';
+      const id = lastEntry.action.id ? ` [${lastEntry.action.id}]` : '';
+      const resultStr = lastEntry.result
+        ? JSON.stringify(lastEntry.result)
+        : 'ok';
+
+      // Detect when result payload indicates failure (e.g. MCP returns {success: false, error: "..."})
+      if (lastEntry.result && lastEntry.result.success === false && lastEntry.result.error) {
+        const errorMsg = lastEntry.result.error;
+        parts.push(`\u274c${id} ${intent} returned an error: ${errorMsg}`);
+
+        // Include MCP server output (stderr) if available — this often contains
+        // the actual installation commands or detailed error info
+        if (lastEntry.result.serverOutput) {
+          parts.push(`Server output:\n${lastEntry.result.serverOutput}`);
+        }
+
+        // Check if server output contains actual installation commands
+        const serverOutput = lastEntry.result.serverOutput || '';
+        const hasInstallCommands = /\b(brew\s+install|pip\s+install|npm\s+install|apt\s+install|apt-get\s+install)\b/i.test(serverOutput);
+
+        // Check if this SAME error appeared before in history (fix attempt didn't work)
+        const sameErrorBefore = this.actionHistory.slice(0, -1).some(
+          e => e.result && e.result.success === false && e.result.error === errorMsg
+        );
+
+        if (sameErrorBefore) {
+          parts.push('WARNING: This is the SAME error as before — your previous fix did NOT solve it. If you have already tried everything mentioned, inform the user and return with an error.');
+        } else if (hasInstallCommands) {
+          parts.push('APPLY RULE 8: Read the server output above. Use "shell" to run the EXACT commands listed there — ALL of them in a SINGLE shell command chained with && (e.g. "brew tap X && brew install Y && pip install Z"). IMPORTANT: The shell "description" field must express NEED, not action (e.g. "Need to install X, Y, and Z because the MCP server requires IDB for iOS Simulator control" — NOT "Installing X..."). Then RETRY the failed action.');
+          parts.push('SHELL RULES: NEVER use placeholder values like <your_api_key> or <TOKEN> in commands — they cause syntax errors. NEVER try to set/export API keys — they are already in the environment. ONLY install what the server output explicitly lists.');
+        } else {
+          parts.push('This is a configuration or environment error (e.g. missing API key, wrong path). Do NOT try to install anything. Inform the user what is wrong and return with an error explaining how to fix it.');
+        }
+      } else {
+        parts.push(`\u2705${id} ${intent} -> ${resultStr}`);
+      }
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Detect loop patterns in action history
+   */
+  _detectLoops() {
+    const warnings = [];
+    const history = this.actionHistory;
+
+    if (history.length < 2) return warnings;
+
+    // Same action repeated 2x consecutively — compare full action shape
+    // (not just intent+data, since call_mcp actions differ by tool/input, not data)
+    const last = history[history.length - 1];
+    const prev = history[history.length - 2];
+    const lastKey = JSON.stringify({ intent: last.action.intent, tool: last.action.tool, data: last.action.data, input: last.action.input });
+    const prevKey = JSON.stringify({ intent: prev.action.intent, tool: prev.action.tool, data: prev.action.data, input: prev.action.input });
+
+    if (lastKey === prevKey) {
+      warnings.push('You repeated the same action with the same data. Try a different approach!');
+    }
+
+    // Consecutive errors
+    if (this.consecutiveErrors >= 2) {
+      warnings.push(`${this.consecutiveErrors} consecutive errors. Try a completely different approach!`);
+    }
+
+    // Oscillating pattern A-B-A-B (compare full action shape, not just intent)
+    if (history.length >= 4) {
+      const h = history.slice(-4);
+      const keys = h.map(e => JSON.stringify({
+        intent: e.action.intent, tool: e.action.tool,
+        data: e.action.data, input: e.action.input, command: e.action.command
+      }));
+      if (keys[0] === keys[2] && keys[1] === keys[3] && keys[0] !== keys[1]) {
+        const intent0 = h[0].action.tool || h[0].action.intent || h[0].action.type;
+        const intent1 = h[1].action.tool || h[1].action.intent || h[1].action.type;
+        warnings.push(`Oscillating pattern detected (${intent0} <-> ${intent1}). Break the cycle!`);
+      }
+    }
+
+    return warnings;
+  }
+
+  /**
+   * Get available data references (action IDs with output)
+   */
+  _getAvailableDataRefs() {
+    const refs = [];
+
+    for (const key of Object.keys(this.actionContext)) {
+      if (key.match(/^a\d+$/) || (this.actionContext[key]?.output !== undefined && !['state', 'results', 'args', 'previousResult', 'lastResult'].includes(key))) {
+        const output = this.actionContext[key]?.output;
+        if (output !== undefined) {
+          const preview = JSON.stringify(output).substring(0, 80);
+          refs.push(`\${${key}.output} = ${preview}`);
+        }
+      }
+    }
+
+    return refs;
+  }
+}

package/src/runtime/registry-backends/keyv-sqlite.js

@@ -12,7 +12,7 @@ import path from 'path';
 
 export default class KeyvSqliteBackend {
   constructor(options = {}) {
-    this.dbPath = options.path || '.koi-registry/registry.sqlite';
+    this.dbPath = options.path || '.koi/registry/registry.sqlite';
     this.keyv = null;
     this.namespace = options.namespace || 'koi';
     this._keysCache = new Set();

package/src/runtime/registry-backends/local.js

@@ -10,7 +10,7 @@ import path from 'path';
 
 export default class LocalBackend {
   constructor(options = {}) {
-    this.dataDir = options.path || '.koi-registry';
+    this.dataDir = options.path || '.koi/registry';
     this.dataFile = path.join(this.dataDir, 'data.json');
     this.cache = new Map();
     this.dirty = false;

package/src/runtime/router.js

@@ -39,49 +39,33 @@ export class AgentRouter {
 
     this.agents.set(agent.name, agent);
 
-    // Use cached affordances if available
+    // Store affordances without generating embeddings (lazy generation)
     if (cachedAffordances) {
       for (const [eventName, aff] of Object.entries(cachedAffordances)) {
-        if (!aff.embedding) {
-          // Fallback: generate at runtime if cache is incomplete
-          if (aff.description && aff.description.trim() !== '') {
-            aff.embedding = await this.getEmbedding(aff.description);
-          } else {
-            console.warn(`⚠️  [Router] Skipping ${agent.name}.${eventName} - empty description`);
-            continue;
-          }
-        }
+        if (!aff.description || aff.description.trim() === '') continue;
 
         this.affordanceEmbeddings.push({
           agent: agent,
           event: eventName,
           description: aff.description,
-          embedding: aff.embedding,
+          embedding: aff.embedding || null, // May be null — generated lazily
           confidence: aff.confidence,
           metadata: { hasPlaybook: aff.hasPlaybook }
         });
       }
-
       return;
     }
 
-    // No cache: extract and generate affordances at runtime
+    // No cache: extract affordances (still no embedding generation)
     const affordances = this.extractAffordances(agent);
-
-    // Generate embeddings for each affordance
     for (const aff of affordances) {
-      if (!aff.description || aff.description.trim() === '') {
-        console.warn(`⚠️  [Router] Skipping ${agent.name}.${aff.event} - empty description`);
-        continue;
-      }
-
-      const embedding = await this.getEmbedding(aff.description);
+      if (!aff.description || aff.description.trim() === '') continue;
 
       this.affordanceEmbeddings.push({
         agent: agent,
         event: aff.event,
         description: aff.description,
-        embedding: embedding,
+        embedding: null, // Generated lazily on first findMatches call
         confidence: aff.confidence,
         metadata: aff.metadata
       });
@@ -206,13 +190,25 @@ export class AgentRouter {
       return [];
     }
 
+    // Lazy embedding generation: only compute when actually needed for routing
+    const needsEmbeddings = this.affordanceEmbeddings.some(aff => !aff.embedding);
+    if (needsEmbeddings) {
+      for (const aff of this.affordanceEmbeddings) {
+        if (!aff.embedding && aff.description) {
+          aff.embedding = await this.getEmbedding(aff.description);
+        }
+      }
+    }
+
     // Phase 1: Embedding-based similarity search
     const intentEmbedding = await this.getEmbedding(intent);
 
-    const similarities = this.affordanceEmbeddings.map(aff => ({
-      ...aff,
-      similarity: this.cosineSimilarity(intentEmbedding, aff.embedding)
-    }));
+    const similarities = this.affordanceEmbeddings
+      .filter(aff => aff.embedding)
+      .map(aff => ({
+        ...aff,
+        similarity: this.cosineSimilarity(intentEmbedding, aff.embedding)
+      }));
 
     // Sort by similarity descending
     similarities.sort((a, b) => b.similarity - a.similarity);

package/src/runtime/runtime.js

@@ -3,7 +3,7 @@ import { cliLogger } from './cli-logger.js';
 
 export class Runtime {
   static async send(config) {
-    const { base, filters = [], args = {}, timeout = 30000 } = config;
+    const { base, filters = [], args = {}, timeout = 30000, caller = null } = config;
 
     // Validate that base (team/peers) is not null
     if (!base || base === null || base === undefined) {
@@ -11,6 +11,12 @@ export class Runtime {
       throw new Error(`NO_AGENT_HANDLER:${eventName}::no-team`);
     }
 
+    // Check that calling agent has delegate permission
+    if (caller && typeof caller.hasPermission === 'function' && !caller.hasPermission('delegate')) {
+      const eventName = filters.find(f => f.type === 'event')?.name || 'unknown event';
+      throw new Error(`Agent "${caller.name}" cannot delegate: role "${caller.role?.name || 'unknown'}" lacks "can delegate" permission. Add "can delegate" to the role definition.`);
+    }
+
     // Apply timeout
     const timeoutPromise = new Promise((_, reject) => {
       setTimeout(() => reject(new Error(`Timeout after ${timeout}ms`)), timeout);

package/examples/cache-test.koi

@@ -1,29 +0,0 @@
-// Cache Test Example
-package "test.cache"
-
-role Worker { can execute }
-
-Agent TextTranslator : Worker {
-  llm default = { provider: "openai", model: "gpt-4o-mini" }
-
-  on translate(args: Json) {
-    playbook """
-    Translate this text to the target language: ${args.text}
-    Target language: ${args.language}
-    Return JSON with translated text.
-    """
-  }
-}
-
-Agent WordAnalyzer : Worker {
-  llm default = { provider: "openai", model: "gpt-4o-mini" }
-
-  on analyze(args: Json) {
-    playbook """
-    Analyze this text and count words: ${args.text}
-    Return JSON with word count and analysis.
-    """
-  }
-}
-
-run TextTranslator.translate({ text: "hello", language: "spanish" })

package/examples/calculator.koi

@@ -1,61 +0,0 @@
-// ============================================================
-// Koi — Calculator Example
-// Simple calculator with multiple operations (procedural code only)
-// ============================================================
-
-package "demo.koi.calculator"
-
-role Worker { can execute }
-
-// All handlers use procedural code (no playbooks)
-Agent Calculator : Worker {
-  on add(args: Json) {
-    const a = args.a
-    const b = args.b
-    return { result: a + b, operation: "add" }
-  }
-
-  on multiply(args: Json) {
-    const a = args.a
-    const b = args.b
-    return { result: a * b, operation: "multiply" }
-  }
-
-  on divide(args: Json) {
-    const a = args.a
-    const b = args.b
-
-    if b == 0 {
-      return { error: "Division by zero", operation: "divide" }
-    }
-
-    return { result: a / b, operation: "divide" }
-  }
-}
-
-Team CalcTeam {
-  calc = Calculator
-}
-
-Agent Orchestrator : Worker {
-  uses Team CalcTeam
-
-  on start(args: Json) {
-    const sum =
-      await send peers.event("add").role(Worker).any()({ a: 10, b: 5 }) timeout 2s
-
-    const product =
-      await send peers.event("multiply").role(Worker).any()({ a: 10, b: 5 }) timeout 2s
-
-    const quotient =
-      await send peers.event("divide").role(Worker).any()({ a: 10, b: 5 }) timeout 2s
-
-    return {
-      sum: sum,
-      product: product,
-      quotient: quotient
-    }
-  }
-}
-
-run Orchestrator.start({})

package/examples/clear-registry.js

@@ -1,33 +0,0 @@
-#!/usr/bin/env node
-
-// Clear Registry - Delete all data from the registry
-import { registry } from '../src/runtime/index.js';
-
-async function clearRegistry() {
-  console.log("⚠️  WARNING: Clearing all registry data...");
-  console.log("");
-
-  // Show stats before clearing
-  const statsBefore = await registry.stats();
-  console.log("   Current entries:", statsBefore.count);
-  console.log("   Storage:", statsBefore.file);
-  console.log("");
-
-  // Clear the registry
-  await registry.clear();
-
-  console.log("✅ Registry cleared successfully!");
-  console.log("");
-
-  // Show stats after clearing
-  const statsAfter = await registry.stats();
-  console.log("   Entries remaining:", statsAfter.count);
-  console.log("");
-
-  process.exit(0);
-}
-
-clearRegistry().catch((error) => {
-  console.error("❌ Error clearing registry:", error.message);
-  process.exit(1);
-});

package/examples/clear-registry.koi

@@ -1,30 +0,0 @@
-// Clear Registry - Delete all data from the registry
-package "clear.registry"
-
-role Admin { can execute }
-
-Agent Cleaner : Admin {
-  on clearAll(args: Json) {
-    console.log("⚠️  WARNING: Clearing all registry data...")
-
-    // Show current stats before clearing
-    const statsBefore = await registry.stats()
-    console.log("   Current entries:", statsBefore.count)
-    console.log("   Storage:", statsBefore.file)
-    console.log("")
-
-    // Clear the registry
-    await registry.clear()
-
-    console.log("✅ Registry cleared successfully!")
-
-    // Show stats after clearing
-    const statsAfter = await registry.stats()
-    console.log("   Entries remaining:", statsAfter.count)
-    console.log("")
-
-    return { success: true, clearedCount: statsBefore.count }
-  }
-}
-
-run Cleaner.clearAll({})

package/examples/code-introspection-test.koi

@@ -1,149 +0,0 @@
-package "demo.code.introspection"
-
-role Calculator { can calculate }
-role Coordinator { can coordinate }
-
-// Agent con event handler que tiene código (no playbook)
-// El sistema debe hacer introspección para generar affordance
-Agent MathProcessor : Calculator {
-  llm default = {
-    provider: "openai",
-    model: "gpt-4o-mini",
-    temperature: 0.1
-  }
-
-  // Event handler con código Koi (sin playbook)
-  // El sistema hará introspección del código para generar affordance
-  // Este handler suma todos los números en el array
-  on calculateSum(args: Json) {
-    const numbers = args.numbers
-
-    // Procesar números y sumarlos
-    const result = await send peers.event("sumArray").role(Calculator).any()({
-      data: numbers
-    }) timeout 5s
-
-    return {
-      operation: "sum",
-      result: result
-    }
-  }
-
-  // Event handler que multiplica todos los números
-  on calculateProduct(args: Json) {
-    const numbers = args.numbers
-
-    // Multiplicar los números usando delegación
-    const result = await send peers.event("multiplyArray").role(Calculator).any()({
-      data: numbers
-    }) timeout 5s
-
-    return {
-      operation: "product",
-      result: result
-    }
-  }
-
-  // Event handler con playbook (para comparar)
-  on calculateAverage(args: Json) {
-    playbook """
-    Calculate the average of ${JSON.stringify(args.numbers)}
-
-    Sum all numbers and divide by count.
-    Return: { "operation": "average", "result": <value> }
-    """
-  }
-}
-
-Team MathTeam {
-  processor = MathProcessor
-}
-
-// Coordinator que delega basándose en affordances
-Agent Coordinator : Coordinator {
-  llm default = {
-    provider: "openai",
-    model: "gpt-4o-mini",
-    temperature: 0.1
-  }
-
-  uses Team MathTeam
-
-  on process(args: Json) {
-    playbook """
-    Process this math request: ${JSON.stringify(args)}
-
-    Available operations (delegate to Calculator role):
-    - Calculate sum/total of numbers
-    - Calculate product/multiplication of numbers
-    - Calculate average/mean of numbers
-
-    Determine the intent and delegate with an action:
-    {
-      "actions": [{
-        "title": "Calculating...",
-        "intent": "<your interpretation of what math operation is needed>",
-        "data": { "numbers": ${JSON.stringify(args.numbers)} }
-      }]
-    }
-    """
-  }
-}
-
-Team CoordinatorTeam {
-  coordinator = Coordinator
-}
-
-Agent Main : Coordinator {
-  uses Team CoordinatorTeam
-
-  on start(args: Json) {
-    console.log("╔════════════════════════════════════════════╗")
-    console.log("║  Code Introspection Test                   ║")
-    console.log("║  Event handlers with source code           ║")
-    console.log("╚════════════════════════════════════════════╝\n")
-
-    // Test 1: Request sum (should route to calculateSum)
-    console.log("📋 Test 1: Calculate the total")
-    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
-
-    const sumResult =
-      await send peers.event("process").role(Coordinator).any()({
-        operation: "calculate the total of these numbers",
-        numbers: [5, 10, 15, 20]
-      }) timeout 30s
-
-    console.log("Result:", JSON.stringify(sumResult, null, 2))
-
-    // Test 2: Request product (should route to calculateProduct)
-    console.log("\n📋 Test 2: Multiply all numbers")
-    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
-
-    const productResult =
-      await send peers.event("process").role(Coordinator).any()({
-        operation: "multiply all the numbers together",
-        numbers: [2, 3, 4, 5]
-      }) timeout 30s
-
-    console.log("Result:", JSON.stringify(productResult, null, 2))
-
-    // Test 3: Request average (should route to calculateAverage with playbook)
-    console.log("\n📋 Test 3: Find the average")
-    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
-
-    const avgResult =
-      await send peers.event("process").role(Coordinator).any()({
-        operation: "find the average value",
-        numbers: [10, 20, 30, 40, 50]
-      }) timeout 30s
-
-    console.log("Result:", JSON.stringify(avgResult, null, 2))
-
-    return {
-      success: true,
-      tests_completed: 3
-    }
-  }
-}
-
-run Main.start({})