@koi-language/koi 1.0.5 → 1.1.0

package/src/compiler/transpiler.js

@@ -116,7 +116,11 @@ export class KoiTranspiler {
     // Store routerImportPath for later use
     this.routerImportPath = routerImportPath;
 
-    code += this.emit(`import { Agent, Team, Skill, Role, Runtime, SkillRegistry, skillSelector, registry } from '${runtimeImportPath}';\n\n`);
+    code += this.emit(`import { Agent, Team, Skill, Role, Runtime, SkillRegistry, skillSelector, registry, mcpRegistry } from '${runtimeImportPath}';\n`);
+
+    // Add CommonJS compatibility for require() in ES modules
+    code += this.emit(`import { createRequire } from 'module';\n`);
+    code += this.emit(`const require = createRequire(import.meta.url);\n\n`);
 
     // Generate imports for external TypeScript/JavaScript modules
     if (this.externalImports && this.externalImports.length > 0) {
@@ -168,10 +172,11 @@ export class KoiTranspiler {
       code += this.emit(`\n`);
     }
 
-    // Make SkillRegistry and registry available globally
+    // Make SkillRegistry, registry, and mcpRegistry available globally
     code += this.emit(`globalThis.SkillRegistry = SkillRegistry;\n`);
     code += this.emit(`globalThis.skillSelector = skillSelector;\n`);
-    code += this.emit(`globalThis.registry = registry;\n\n`);
+    code += this.emit(`globalThis.registry = registry;\n`);
+    code += this.emit(`globalThis.mcpRegistry = mcpRegistry;\n\n`);
 
     // Inject build-time cache if available
     if (this.cacheData && this.cacheData.affordances) {
@@ -182,28 +187,30 @@ export class KoiTranspiler {
     const agentDecls = [];
     const skillDecls = [];
     const runStatements = [];
-    const otherDecls = [];
+    const sortableDecls = [];
 
     for (const decl of node.declarations) {
       if (decl.type === 'RunStatement') {
         runStatements.push(decl);
-      } else if (decl.type === 'AgentDecl') {
-        agentDecls.push(decl);
-      } else if (decl.type === 'SkillDecl') {
-        skillDecls.push(decl);
       } else {
-        otherDecls.push(decl);
+        sortableDecls.push(decl);
+        if (decl.type === 'AgentDecl') agentDecls.push(decl);
+        else if (decl.type === 'SkillDecl') skillDecls.push(decl);
       }
     }
 
-    // Generate all declarations in original order (except RunStatements)
-    // This preserves dependencies between roles, teams, and agents
+    // Generate declarations in dependency order using topological sort.
+    // Dependencies:
+    //   AgentDecl  → depends on teams from "uses team X" body items
+    //   TeamDecl   → depends on its member agents
+    //   RoleDecl, SkillDecl, MCPDecl → no deps (generated first)
     this.skipAgentRegistration = true;
-    for (const decl of node.declarations) {
-      if (decl.type !== 'RunStatement') {
-        code += this.generateDeclaration(decl);
-      }
+
+    const sorted = this._topologicalSortDeclarations(sortableDecls);
+    for (const decl of sorted) {
+      code += this.generateDeclaration(decl);
     }
+
     this.skipAgentRegistration = false;
 
     // Generate main async function that coordinates everything
@@ -265,7 +272,13 @@ export class KoiTranspiler {
         code += this.generateRunBody(runStmt);
       }
 
+      // Graceful MCP shutdown on signals
+      code += this.emit(`${this.getIndent()}const _gracefulShutdown = async () => { await mcpRegistry.disconnectAll(); process.exit(0); };\n`);
+      code += this.emit(`${this.getIndent()}process.on('SIGINT', _gracefulShutdown);\n`);
+      code += this.emit(`${this.getIndent()}process.on('SIGTERM', _gracefulShutdown);\n\n`);
+
       // Clean exit
+      code += this.emit(`${this.getIndent()}await mcpRegistry.disconnectAll();\n`);
       code += this.emit(`${this.getIndent()}process.exit(0);\n`);
 
       this.indent--;
@@ -296,6 +309,125 @@ export class KoiTranspiler {
     return code;
   }
 
+  // ============================================================
+  // Declaration ordering (topological sort)
+  // ============================================================
+
+  /**
+   * Extract the name of a declaration node.
+   */
+  _getDeclName(decl) {
+    if (decl.name && decl.name.name) return decl.name.name;
+    if (decl.name && typeof decl.name === 'string') return decl.name;
+    return null;
+  }
+
+  /**
+   * Get dependency names for a declaration.
+   *   AgentDecl  → depends on teams from "uses team X"
+   *   TeamDecl   → depends on its member agents
+   *   Others     → no deps
+   */
+  _getDeclDeps(decl) {
+    const deps = [];
+    if (decl.type === 'AgentDecl' && decl.body) {
+      for (const item of decl.body) {
+        if (item.type === 'UsesTeam') {
+          const teamName = item.team?.name || (typeof item.team === 'string' ? item.team : null);
+          if (teamName) deps.push(teamName);
+        }
+      }
+    } else if (decl.type === 'TeamDecl' && decl.members) {
+      for (const member of decl.members) {
+        let agentName = null;
+        if (member.value?.type === 'AgentReference') {
+          agentName = member.value.agent.name;
+        } else if (member.value?.type === 'Identifier') {
+          agentName = member.value.name;
+        }
+        if (agentName) deps.push(agentName);
+      }
+    }
+    return deps;
+  }
+
+  /**
+   * Topological sort of declarations to prevent forward reference errors.
+   * Roles, Skills, MCPs have no deps and go first.
+   * Agents and Teams are sorted by their dependency graph.
+   */
+  _topologicalSortDeclarations(decls) {
+    // Priority for types without dependencies (lower = earlier)
+    const typePriority = { RoleDecl: 0, MCPDecl: 1, SkillDecl: 2 };
+
+    // Split into no-dep types (always first) and graph-sorted types
+    const noDeps = [];
+    const graphDecls = [];
+    for (const decl of decls) {
+      if (typePriority[decl.type] !== undefined) {
+        noDeps.push(decl);
+      } else if (decl.type === 'AgentDecl' || decl.type === 'TeamDecl') {
+        graphDecls.push(decl);
+      } else {
+        noDeps.push(decl);
+      }
+    }
+
+    // Sort no-dep types by priority
+    noDeps.sort((a, b) => (typePriority[a.type] ?? 99) - (typePriority[b.type] ?? 99));
+
+    if (graphDecls.length === 0) return [...noDeps];
+
+    // Build adjacency: name → decl, name → deps
+    const nameToDecl = new Map();
+    const nameToIdx = new Map();
+    for (let i = 0; i < graphDecls.length; i++) {
+      const name = this._getDeclName(graphDecls[i]);
+      if (name) {
+        nameToDecl.set(name, graphDecls[i]);
+        nameToIdx.set(name, i);
+      }
+    }
+
+    // Kahn's algorithm for topological sort
+    const inDegree = new Array(graphDecls.length).fill(0);
+    const adj = new Array(graphDecls.length).fill(null).map(() => []);
+
+    for (let i = 0; i < graphDecls.length; i++) {
+      const deps = this._getDeclDeps(graphDecls[i]);
+      for (const dep of deps) {
+        const j = nameToIdx.get(dep);
+        if (j !== undefined && j !== i) {
+          adj[j].push(i); // j must come before i
+          inDegree[i]++;
+        }
+      }
+    }
+
+    const queue = [];
+    for (let i = 0; i < graphDecls.length; i++) {
+      if (inDegree[i] === 0) queue.push(i);
+    }
+
+    const sorted = [];
+    while (queue.length > 0) {
+      const i = queue.shift();
+      sorted.push(graphDecls[i]);
+      for (const next of adj[i]) {
+        inDegree[next]--;
+        if (inDegree[next] === 0) queue.push(next);
+      }
+    }
+
+    // If cycle detected, fall back to original order
+    if (sorted.length < graphDecls.length) {
+      console.warn('[Transpiler] Circular dependency detected in declarations, using original order');
+      return [...noDeps, ...graphDecls];
+    }
+
+    return [...noDeps, ...sorted];
+  }
+
   // ============================================================
   // Declarations
   // ============================================================
@@ -303,7 +435,7 @@ export class KoiTranspiler {
   generateDeclaration(node) {
     switch (node.type) {
       case 'PackageDecl':
-        return this.emit(`// Package: ${node.name.value}\n\n`, node);
+        return ''; // Package declarations are ignored (kept for backwards compatibility)
       case 'ImportDecl':
         return this.generateImport(node);
       case 'RoleDecl':
@@ -314,6 +446,8 @@ export class KoiTranspiler {
         return this.generateAgent(node);
       case 'SkillDecl':
         return this.generateSkill(node);
+      case 'MCPDecl':
+        return this.generateMCP(node);
       case 'RunStatement':
         return this.generateRun(node);
       default:
@@ -369,6 +503,12 @@ export class KoiTranspiler {
     return code;
   }
 
+  generateMCP(node) {
+    let code = this.emit(`// MCP Server: ${node.name.name}\n`, node);
+    code += this.emit(`mcpRegistry.register('${node.name.name}', ${this.generateExpression(node.config)});\n\n`);
+    return code;
+  }
+
   generateAgent(node) {
     let code = this.emit(`const ${node.name.name} = new Agent({\n`, node);
     this.indent++;
@@ -378,11 +518,13 @@ export class KoiTranspiler {
     // Extract body items
     const skills = node.body.filter(b => b.type === 'UsesSkill');
     const usesTeams = node.body.filter(b => b.type === 'UsesTeam');
+    const usesMCP = node.body.filter(b => b.type === 'UsesMCP');
     const llmConfig = node.body.find(b => b.type === 'LLMConfig');
     const eventHandlers = node.body.filter(b => b.type === 'EventHandler');
     const state = node.body.find(b => b.type === 'StateDecl');
     const playbooks = node.body.filter(b => b.type === 'PlaybookDecl');
     const resilience = node.body.find(b => b.type === 'ResilienceDecl');
+    const amnesia = node.body.find(b => b.type === 'AmnesiaDecl');
     const peers = node.body.find(b => b.type === 'PeersDecl');
 
     // Track if agent has handlers for auto-registration
@@ -402,10 +544,18 @@ export class KoiTranspiler {
       }
     }
 
+    if (usesMCP.length > 0) {
+      code += this.emit(`${this.getIndent()}usesMCP: [${usesMCP.map(m => `'${m.mcp.name}'`).join(', ')}],\n`);
+    }
+
     if (llmConfig) {
       code += this.emit(`${this.getIndent()}llm: ${this.generateExpression(llmConfig.config)},\n`);
     }
 
+    if (amnesia) {
+      code += this.emit(`${this.getIndent()}amnesia: ${amnesia.value.value},\n`);
+    }
+
     if (state) {
       code += this.emit(`${this.getIndent()}state: {\n`);
       this.indent++;
@@ -454,7 +604,7 @@ export class KoiTranspiler {
       code += this.emit(`${this.getIndent()}handlers: {\n`);
       this.indent++;
       for (const handler of eventHandlers) {
-        code += this.generateEventHandler(handler);
+        code += this.generateEventHandler(handler, node.name.name);
       }
       this.indent--;
       code += this.emit(`${this.getIndent()}}\n`);
@@ -475,7 +625,7 @@ export class KoiTranspiler {
 
       if (hasCachedAffordances) {
         // Use cached affordances (no embedding generation needed)
-        code += this.emit(`${this.getIndent()}// Using pre-computed embeddings from build cache\n`);
+        code += this.emit(`${this.getIndent()}// Using pre-generated descriptions from build cache\n`);
         code += this.emit(`${this.getIndent()}await agentRouter.register(${agentName}, CACHED_AFFORDANCES['${agentName}']);\n`);
       } else {
         // No cache, generate at runtime
@@ -490,8 +640,12 @@ export class KoiTranspiler {
     return code;
   }
 
-  generateEventHandler(node) {
+  generateEventHandler(node, agentName = null) {
     const params = node.params.map(p => p.name.name).join(', ');
+    const handlerName = node.event.name;
+
+    // Look up cached description for this handler
+    const cachedDesc = agentName && this.cacheData?.affordances?.[agentName]?.[handlerName]?.description;
 
     // Check if this is a playbook-only handler (only has PlaybookStatement, no other code)
     const hasOnlyPlaybook = node.body.length === 1 && node.body[0].type === 'PlaybookStatement';
@@ -501,7 +655,7 @@ export class KoiTranspiler {
       const playbook = node.body[0].content.value;
       const escapedPlaybook = JSON.stringify(playbook);
 
-      let code = this.emit(`${this.getIndent()}${node.event.name}: (() => {\n`);
+      let code = this.emit(`${this.getIndent()}${handlerName}: (() => {\n`);
       this.indent++;
       code += this.emit(`${this.getIndent()}const handler = async function(${params}) {\n`);
       this.indent++;
@@ -511,6 +665,9 @@ export class KoiTranspiler {
       code += this.emit(`${this.getIndent()}};\n`);
       code += this.emit(`${this.getIndent()}handler.__playbookOnly__ = true;\n`);
       code += this.emit(`${this.getIndent()}handler.__playbook__ = ${escapedPlaybook};\n`);
+      if (cachedDesc) {
+        code += this.emit(`${this.getIndent()}handler.__description__ = ${JSON.stringify(cachedDesc)};\n`);
+      }
       code += this.emit(`${this.getIndent()}return handler;\n`);
       this.indent--;
       code += this.emit(`${this.getIndent()}})(),\n`);
@@ -518,7 +675,27 @@ export class KoiTranspiler {
     }
 
     // Regular handler with code
-    let code = this.emit(`${this.getIndent()}${node.event.name}: async function(${params}) {\n`);
+    if (cachedDesc) {
+      // Wrap in IIFE to attach __description__
+      let code = this.emit(`${this.getIndent()}${handlerName}: (() => {\n`);
+      this.indent++;
+      code += this.emit(`${this.getIndent()}const handler = async function(${params}) {\n`);
+      this.indent++;
+      this.inEventHandler = true;
+      for (const stmt of node.body) {
+        code += this.generateStatement(stmt);
+      }
+      this.inEventHandler = false;
+      this.indent--;
+      code += this.emit(`${this.getIndent()}};\n`);
+      code += this.emit(`${this.getIndent()}handler.__description__ = ${JSON.stringify(cachedDesc)};\n`);
+      code += this.emit(`${this.getIndent()}return handler;\n`);
+      this.indent--;
+      code += this.emit(`${this.getIndent()}})(),\n`);
+      return code;
+    }
+
+    let code = this.emit(`${this.getIndent()}${handlerName}: async function(${params}) {\n`);
     this.indent++;
     this.inEventHandler = true;
     for (const stmt of node.body) {
@@ -542,6 +719,35 @@ export class KoiTranspiler {
     }
     code += this.emit(`// ============================================================\n\n`);
 
+    // Check if we need to create a closure for local scope
+    const hasLocalDeclarations = (node.constants && node.constants.length > 0) ||
+                                   (node.variables && node.variables.length > 0) ||
+                                   (node.functions && node.functions.some(f => !f.isExport));
+
+    const exportedFunctionNames = node.functions ? node.functions.filter(f => f.isExport).map(f => f.name.name) : [];
+
+    if (hasLocalDeclarations && exportedFunctionNames.length > 0) {
+      // Use IIFE to create local scope and export functions
+      code += this.emit(`const { ${exportedFunctionNames.join(', ')} } = (() => {\n`);
+      this.indent++;
+    }
+
+    // Generate constants
+    if (node.constants && node.constants.length > 0) {
+      for (const constDecl of node.constants) {
+        code += this.generateSkillConstant(constDecl);
+      }
+      code += this.emit(`\n`);
+    }
+
+    // Generate variables
+    if (node.variables && node.variables.length > 0) {
+      for (const varDecl of node.variables) {
+        code += this.generateSkillVariable(varDecl);
+      }
+      code += this.emit(`\n`);
+    }
+
     // Generate internal agents
     if (node.agents && node.agents.length > 0) {
       for (const agent of node.agents) {
@@ -556,21 +762,28 @@ export class KoiTranspiler {
       }
     }
 
-    // Generate exported functions
-    const functionNames = [];
+    // Generate all functions (exported and non-exported)
     if (node.functions && node.functions.length > 0) {
       for (const func of node.functions) {
-        code += this.generateFunction(func);
-        if (func.isExport) {
-          functionNames.push(func.name.name);
-        }
+        // Remove 'export' keyword if inside IIFE closure
+        const funcCopy = hasLocalDeclarations && exportedFunctionNames.length > 0
+          ? { ...func, isExport: false }
+          : func;
+        code += this.generateFunction(funcCopy);
       }
     }
 
+    // Return exported functions from IIFE
+    if (hasLocalDeclarations && exportedFunctionNames.length > 0) {
+      code += this.emit(`${this.getIndent()}return { ${exportedFunctionNames.join(', ')} };\n`);
+      this.indent--;
+      code += this.emit(`})();\n\n`);
+    }
+
     // Register exported functions in SkillRegistry
-    if (functionNames.length > 0) {
+    if (exportedFunctionNames.length > 0) {
       code += this.emit(`// Register skill functions\n`);
-      for (const funcName of functionNames) {
+      for (const funcName of exportedFunctionNames) {
         code += this.emit(`SkillRegistry.register('${skillName}', '${funcName}', ${funcName}, { affordance: ${JSON.stringify(node.affordance || '')} });\n`);
       }
       code += this.emit(`\n`);
@@ -586,7 +799,14 @@ export class KoiTranspiler {
     // Function signature (strip TypeScript type annotations for JavaScript output)
     const exportKeyword = node.isExport ? 'export ' : '';
     const asyncKeyword = node.isAsync ? 'async ' : '';
-    const params = node.params ? node.params.map(p => p.name.name).join(', ') : '';
+    const params = node.params ? node.params.map(p => {
+      const paramName = p.name.name;
+      if (p.default) {
+        const defaultValue = this.generateExpression(p.default);
+        return `${paramName} = ${defaultValue}`;
+      }
+      return paramName;
+    }).join(', ') : '';
 
     code += this.emit(`${exportKeyword}${asyncKeyword}function ${node.name.name}(${params}) {\n`, node);
 
@@ -608,6 +828,44 @@ export class KoiTranspiler {
     return code;
   }
 
+  generateSkillConstant(node) {
+    const pattern = this.generateDestructuringPattern(node.pattern);
+    const value = this.generateExpression(node.value);
+    return this.emit(`${this.getIndent()}const ${pattern} = ${value};\n`);
+  }
+
+  generateSkillVariable(node) {
+    const pattern = this.generateDestructuringPattern(node.pattern);
+    const init = node.init ? ` = ${this.generateExpression(node.init)}` : '';
+    return this.emit(`${this.getIndent()}let ${pattern}${init};\n`);
+  }
+
+  generateDestructuringPattern(pattern) {
+    if (typeof pattern === 'string') {
+      return pattern;
+    }
+
+    if (pattern.type === 'Identifier') {
+      return pattern.name;
+    }
+
+    if (pattern.type === 'ObjectPattern') {
+      const props = pattern.properties.map(prop => {
+        if (prop.key === prop.value) {
+          return prop.key;
+        }
+        return `${prop.key}: ${prop.value}`;
+      }).join(', ');
+      return `{ ${props} }`;
+    }
+
+    if (pattern.type === 'ArrayPattern') {
+      return `[ ${pattern.elements.join(', ')} ]`;
+    }
+
+    return pattern;
+  }
+
   generateTypeExpression(typeNode) {
     if (!typeNode) return 'any';
 
@@ -702,6 +960,10 @@ export class KoiTranspiler {
         return this.generateWhile(node);
       case 'ReturnStatement':
         return this.generateReturn(node);
+      case 'ThrowStatement':
+        return this.generateThrow(node);
+      case 'TryStatement':
+        return this.generateTry(node);
       case 'SendStatement':
         return this.generateSend(node);
       case 'UsePlaybookStatement':
@@ -818,6 +1080,43 @@ export class KoiTranspiler {
     return this.emit(`${this.getIndent()}return${value};\n`, node);
   }
 
+  generateThrow(node) {
+    return this.emit(`${this.getIndent()}throw ${this.generateExpression(node.argument)};\n`, node);
+  }
+
+  generateTry(node) {
+    let code = this.emit(`${this.getIndent()}try {\n`, node);
+    this.indent++;
+    for (const stmt of node.body) {
+      code += this.generateStatement(stmt);
+    }
+    this.indent--;
+    code += this.emit(`${this.getIndent()}}`);
+
+    if (node.handler) {
+      code += this.emit(` catch (${node.handler.param.name}) {\n`);
+      this.indent++;
+      for (const stmt of node.handler.body) {
+        code += this.generateStatement(stmt);
+      }
+      this.indent--;
+      code += this.emit(`${this.getIndent()}}`);
+    }
+
+    if (node.finalizer) {
+      code += this.emit(` finally {\n`);
+      this.indent++;
+      for (const stmt of node.finalizer) {
+        code += this.generateStatement(stmt);
+      }
+      this.indent--;
+      code += this.emit(`${this.getIndent()}}`);
+    }
+
+    code += this.emit('\n');
+    return code;
+  }
+
   generateSend(node) {
     let code = `await Runtime.send({\n`;
     this.indent++;
@@ -849,9 +1148,11 @@ export class KoiTranspiler {
     }
 
     if (node.timeout) {
-      code += `${this.getIndent()}timeout: ${node.timeout.value}${node.timeout.unit === 's' ? '000' : ''}\n`;
+      code += `${this.getIndent()}timeout: ${node.timeout.value}${node.timeout.unit === 's' ? '000' : ''},\n`;
     }
 
+    code += `${this.getIndent()}caller: this\n`;
+
     this.indent--;
     code += `${this.getIndent()}})`;
     return this.emit(`${this.getIndent()}${code};\n`, node);
@@ -885,6 +1186,8 @@ export class KoiTranspiler {
         return node.name;
       case 'StringLiteral':
         return JSON.stringify(node.value);
+      case 'RegexLiteral':
+        return `/${node.pattern}/${node.flags}`;
       case 'NumberLiteral':
         return String(node.value);
       case 'BooleanLiteral':
@@ -901,6 +1204,8 @@ export class KoiTranspiler {
         return this.generateTemplateLiteral(node);
       case 'AssignmentExpression':
         return this.generateAssignment(node);
+      case 'ConditionalExpression':
+        return `(${this.generateExpression(node.test)} ? ${this.generateExpression(node.consequent)} : ${this.generateExpression(node.alternate)})`;
       default:
         return `/* Unknown expr: ${node.type} */`;
     }
@@ -938,7 +1243,7 @@ export class KoiTranspiler {
         result += `, timeout: ${timeout}`;
       }
 
-      result += ' })';
+      result += ', caller: this })';
       return result;
     });
   }
@@ -1009,23 +1314,25 @@ export class KoiTranspiler {
 
     const callee = this.generateExpression(node.callee);
     const args = node.arguments.map(arg => this.generateExpression(arg)).join(', ');
-    return `${callee}(${args})`;
+    const optional = node.optional ? '?.' : '';
+    return `${callee}${optional}(${args})`;
   }
 
   generateMember(node) {
     const obj = this.generateExpression(node.object);
+    const optional = node.optional ? '?' : '';
 
     // Check if property is computed (array access with brackets)
     if (node.computed || node.property.type === 'NumberLiteral') {
       const prop = this.generateExpression(node.property);
-      return `${obj}[${prop}]`;
+      return `${obj}${optional}[${prop}]`;
     }
 
     // Regular property access with dot notation
     const prop = typeof node.property === 'string'
       ? node.property
       : node.property.name || this.generateExpression(node.property);
-    return `${obj}.${prop}`;
+    return `${obj}${optional}.${prop}`;
   }
 
   generateObject(node) {
@@ -1053,6 +1360,7 @@ export class KoiTranspiler {
   generateArrowFunction(node) {
     // Generate parameters
     const params = node.params.map(p => p.name || p).join(', ');
+    const asyncKeyword = node.isAsync ? 'async ' : '';
 
     // Generate body
     if (node.body.type === 'BlockStatement') {
@@ -1064,17 +1372,17 @@ export class KoiTranspiler {
       }
       this.indent--;
       body += `${this.getIndent()}}`;
-      return `(${params}) => ${body}`;
+      return `${asyncKeyword}(${params}) => ${body}`;
     } else {
       // Expression body (implicit return)
       const body = this.generateExpression(node.body);
 
       // If body is an object literal, wrap it in parentheses to avoid ambiguity
       if (node.body.type === 'ObjectLiteral') {
-        return `(${params}) => (${body})`;
+        return `${asyncKeyword}(${params}) => (${body})`;
       }
 
-      return `(${params}) => ${body}`;
+      return `${asyncKeyword}(${params}) => ${body}`;
     }
   }