@koi-language/koi 1.0.6 → 1.1.0

package/examples/skills/advanced/.build/index.ts.map

@@ -0,0 +1 @@
+{"version":3,"sources":["index.koi"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAUA;;;;;;;AAWE;;;;;;;;;;;;;;;;AAgBA;;;;;;;;;;;;;;;;;;;AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;AAwBF","file":"index.koi.js"}

package/examples/skills/advanced/.build/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/examples/skills/advanced/index.koi

@@ -3,8 +3,6 @@
 // Entry point that exports all skills from this directory
 // ============================================================
 
-package "skills.advanced"
-
 // Re-export from other files in this directory
 // (In a future version, we could support automatic re-export)
 
@@ -16,7 +14,7 @@ role DataScientist { can analyze }
 // Statistical Analysis Skill
 // ============================================================
 
-Skill StatisticalAnalysis {
+skill StatisticalAnalysis {
   affordance """
   Perform statistical analysis including mean, median, standard deviation
   """
@@ -80,9 +78,9 @@ Skill StatisticalAnalysis {
 // Data Analysis Agent
 // ============================================================
 
-Agent DataAnalyzer : DataScientist {
+agent DataAnalyzer : DataScientist {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 400 }
-  uses Skill StatisticalAnalysis
+  uses skill StatisticalAnalysis
 
   on analyze(args: Json) {
     playbook """

package/examples/skills/math-operations.koi

@@ -3,9 +3,7 @@
 // A reusable skill that provides math operations
 // ============================================================
 
-package "skills.math"
-
-Skill MathOperations {
+skill MathOperations {
   affordance """
   Perform mathematical operations like addition, subtraction, multiplication, and division
   """

package/examples/skills/string-operations.koi

@@ -3,9 +3,7 @@
 // A reusable skill for string manipulation
 // ============================================================
 
-package "skills.string"
-
-Skill StringOperations {
+skill StringOperations {
   affordance """
   Perform string operations like uppercase, lowercase, reverse, and length
   """

package/examples/tic-tac-toe.koi

@@ -0,0 +1,19 @@
+// Demo: Iteration Actions (repeat and while)
+// Shows how to repeat actions fixed number of times or until condition
+
+role Worker { can execute }
+
+agent Assistant : Worker {
+  llm default = { provider: "openai", model: "gpt-5.2" }
+
+  on test_while(args: Json) {
+    playbook """
+    Play tic-tac-toe with the user.
+    On each turn you show the board, and the user says where to move with a combination like A2, B3
+    Then you make your move and show the board as it looks after your move.
+    End the game when someone wins or if the user expresses their wish to stop.
+    """
+  }
+}
+
+run Assistant.test_while({})

package/examples/utils/echo-mcp-server.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+
+/**
+ * Simple Echo MCP Server for testing Koi's MCP stdio integration.
+ * Communicates via JSON-RPC 2.0 over stdin/stdout.
+ *
+ * Tools:
+ *   - echo: Echoes back the input message
+ *   - reverse: Reverses the input string
+ *   - uppercase: Converts input to uppercase
+ */
+
+import { createInterface } from 'readline';
+
+const SERVER_INFO = {
+  name: 'echo-mcp-server',
+  version: '1.0.0'
+};
+
+const TOOLS = [
+  {
+    name: 'echo',
+    description: 'Echo back the input message',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message: { type: 'string', description: 'The message to echo back' }
+      },
+      required: ['message']
+    }
+  },
+  {
+    name: 'reverse',
+    description: 'Reverse the input string',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'The text to reverse' }
+      },
+      required: ['text']
+    }
+  },
+  {
+    name: 'uppercase',
+    description: 'Convert text to uppercase',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'The text to convert to uppercase' }
+      },
+      required: ['text']
+    }
+  }
+];
+
+function sendResponse(id, result) {
+  const response = JSON.stringify({ jsonrpc: '2.0', id, result });
+  process.stdout.write(response + '\n');
+}
+
+function sendError(id, code, message) {
+  const response = JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } });
+  process.stdout.write(response + '\n');
+}
+
+function handleRequest(message) {
+  const { id, method, params } = message;
+
+  switch (method) {
+    case 'initialize':
+      sendResponse(id, {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: SERVER_INFO
+      });
+      break;
+
+    case 'tools/list':
+      sendResponse(id, { tools: TOOLS });
+      break;
+
+    case 'tools/call': {
+      const toolName = params?.name;
+      const args = params?.arguments || {};
+
+      switch (toolName) {
+        case 'echo':
+          sendResponse(id, {
+            content: [{ type: 'text', text: JSON.stringify({ echo: args.message || '' }) }]
+          });
+          break;
+
+        case 'reverse':
+          const reversed = (args.text || '').split('').reverse().join('');
+          sendResponse(id, {
+            content: [{ type: 'text', text: JSON.stringify({ reversed }) }]
+          });
+          break;
+
+        case 'uppercase':
+          sendResponse(id, {
+            content: [{ type: 'text', text: JSON.stringify({ uppercased: (args.text || '').toUpperCase() }) }]
+          });
+          break;
+
+        default:
+          sendError(id, -32601, `Unknown tool: ${toolName}`);
+      }
+      break;
+    }
+
+    case 'notifications/initialized':
+    case 'notifications/cancelled':
+      // Notifications don't require a response
+      break;
+
+    default:
+      if (id !== undefined) {
+        sendError(id, -32601, `Method not found: ${method}`);
+      }
+  }
+}
+
+// Read JSON-RPC messages from stdin (newline-delimited)
+const rl = createInterface({ input: process.stdin });
+
+rl.on('line', (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  try {
+    const message = JSON.parse(trimmed);
+    handleRequest(message);
+  } catch (e) {
+    process.stderr.write(`[echo-mcp-server] Parse error: ${e.message}\n`);
+  }
+});
+
+rl.on('close', () => {
+  process.exit(0);
+});

package/examples/web-delegation-demo.koi

@@ -3,16 +3,14 @@
 // Demonstrates delegation with indentation and loop detection
 // ============================================================
 
-package "demo.koi.delegation"
-
 role Worker { can execute }
-role Assistant { can help }
+role Assistant { can help, can delegate }
 
 // ============================================================
 // Skills - JavaScript functions agents can use
 // ============================================================
 
-Skill WebFetching {
+skill WebFetching {
   affordance """
   Fetch content from web URLs
   """
@@ -60,9 +58,9 @@ Skill WebFetching {
 // Worker Agents with Specialized Capabilities
 // ============================================================
 
-Agent WebFetcher : Worker {
+agent WebFetcher : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.2, max_tokens: 500 }
-  uses Skill WebFetching
+  uses skill WebFetching
 
   on fetchWebPage(args: Json) {
     playbook """
@@ -73,7 +71,7 @@ Agent WebFetcher : Worker {
   }
 }
 
-Agent ContentSummarizer : Worker {
+agent ContentSummarizer : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.3, max_tokens: 300 }
 
   on summarize(args: Json) {
@@ -86,7 +84,7 @@ Agent ContentSummarizer : Worker {
   }
 }
 
-Agent WordCounter : Worker {
+agent WordCounter : Worker {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
 
   on count(args: Json) {
@@ -102,10 +100,10 @@ Agent WordCounter : Worker {
 // Orchestrator Agent
 // ============================================================
 
-Agent TaskOrchestrator : Assistant {
+agent TaskOrchestrator : Assistant {
   llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.3, max_tokens: 800 }
 
-  //no cambies este agente!!! Es el que se encarga de delegar la tarea. No cambies su playbook!!!!
+  //don't change this agent!!! It is the one responsible for delegating the task. Don't change its playbook!!!!
   on processWebTask(args: Json) {
     playbook """
     User request: ${args.request}
@@ -119,19 +117,19 @@ Agent TaskOrchestrator : Assistant {
 // Team
 // ============================================================
 
-Team WorkerTeam {
-  orchestrator = TaskOrchestrator
-  webFetcher = WebFetcher
-  summarizer = ContentSummarizer
-  counter = WordCounter
+team WorkerTeam {
+  orchestrator: TaskOrchestrator
+  webFetcher: WebFetcher
+  summarizer: ContentSummarizer
+  counter: WordCounter
 }
 
 // ============================================================
 // Demo Runner
 // ============================================================
 
-Agent DemoRunner : Assistant {
-  uses Team WorkerTeam
+agent DemoRunner : Assistant {
+  uses team WorkerTeam
 
   on runDemo(args: Json) {
     console.log("╔════════════════════════════════════════════╗")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koi-language/koi",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Koi - Agent-first language. Calm orchestration.",
   "type": "module",
   "main": "src/runtime/index.js",
@@ -64,6 +64,7 @@
     "node-fetch": "^3.3.2",
     "openai": "^6.16.0",
     "peggy": "^5.0.6",
+    "prompts": "^2.4.2",
     "source-map": "^0.7.6",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",

package/src/cli/koi.js

@@ -21,8 +21,8 @@ const COMMANDS = {
 };
 
 const FLAGS = {
-  '--no-precalculate': 'Disable embedding pre-calculation (dynamic at runtime)',
-  '--no-cache': 'Disable persistent cache (always regenerate embeddings)',
+  '--no-precalculate': 'Disable description pre-generation (dynamic at runtime)',
+  '--no-cache': 'Disable persistent cache (always regenerate descriptions)',
   '--verbose': 'Show detailed output',
   '--debug': 'Show all LLM prompts and responses',
   '--output, -o': 'Specify output file path',
@@ -87,14 +87,14 @@ function showCommandHelp(command) {
   switch (command) {
     case 'compile':
       console.log('koi compile - Compile Koi source to JavaScript\n');
-      console.log('By default: Pre-computes embeddings and caches them for fast builds.');
+      console.log('By default: Pre-generates handler descriptions and caches them.');
       console.log('Use --no-precalculate or --no-cache to customize behavior.\n');
       console.log('Usage:');
       console.log('  koi compile <file.koi>');
       console.log('  koi compile -o <output.js> <file.koi>\n');
       console.log('Options:');
       console.log('  -o, --output <path>      Output file path');
-      console.log('  --no-precalculate        Disable embedding pre-calculation (dynamic at runtime)');
+      console.log('  --no-precalculate        Disable description pre-generation (dynamic at runtime)');
       console.log('  --no-cache               Disable persistent cache (always regenerate)');
       console.log('\nExamples:');
       console.log('  koi compile examples/simple.koi                    # Default: pre-compute + cache');
@@ -105,11 +105,11 @@ function showCommandHelp(command) {
 
     case 'run':
       console.log('koi run - Compile and execute Koi programs\n');
-      console.log('By default: Pre-computes embeddings and caches them.\n');
+      console.log('By default: Pre-generates handler descriptions and caches them.\n');
       console.log('Usage:');
       console.log('  koi run <file.koi>\n');
       console.log('Options:');
-      console.log('  --no-precalculate     Disable embedding pre-calculation');
+      console.log('  --no-precalculate     Disable description pre-generation');
       console.log('  --no-cache            Disable persistent cache');
       console.log('  --verbose             Show detailed execution logs');
       console.log('\nExamples:');
@@ -132,8 +132,8 @@ function showCommandHelp(command) {
       console.log('  koi cache stats       Show cache statistics');
       console.log('  koi cache clear       Clear all cache');
       console.log('  koi cache clear <file> Clear cache for specific file\n');
-      console.log('The cache stores pre-computed embeddings to avoid API calls.');
-      console.log('Cache is stored in .koi-cache/ directory.\n');
+      console.log('The cache stores pre-generated handler descriptions to avoid API calls.');
+      console.log('Cache is stored in .koi/cache/ directory.\n');
       console.log('Examples:');
       console.log('  koi cache stats');
       console.log('  koi cache clear');
@@ -286,7 +286,7 @@ async function compileFile(sourcePath, outputPath = null, options = {}) {
       cacheData = cacheManager.get(source, sourcePath);
 
       if (cacheData && verbose) {
-        cliLogger.success(`✅ Using cached embeddings (${cacheData.metadata.totalAffordances} affordances)`);
+        cliLogger.success(`✅ Using cached descriptions (${cacheData.metadata.totalAffordances} affordances)`);
       } else if (verbose) {
         cliLogger.clear();
       }
@@ -303,19 +303,19 @@ async function compileFile(sourcePath, outputPath = null, options = {}) {
       try {
         if (shouldCache) {
           if (verbose) {
-            cliLogger.progress('🔄 Pre-computing embeddings...');
+            cliLogger.progress('🔄 Generating handler descriptions...');
           }
           cacheData = await optimizer.optimizeAST(ast, source, sourcePath);
           if (verbose) {
-            cliLogger.success(`✅ Pre-computed ${cacheData.metadata.totalAffordances} embeddings`);
+            cliLogger.success(`✅ Generated ${cacheData.metadata.totalAffordances} descriptions`);
           }
         } else {
           if (verbose) {
-            cliLogger.progress('🔄 Pre-computing embeddings (no cache)...');
+            cliLogger.progress('🔄 Generating handler descriptions (no cache)...');
           }
           cacheData = await optimizer.optimizeASTWithoutCache(ast);
           if (verbose) {
-            cliLogger.success(`✅ Pre-computed ${cacheData.metadata.totalAffordances} embeddings`);
+            cliLogger.success(`✅ Generated ${cacheData.metadata.totalAffordances} descriptions`);
           }
         }
       } catch (error) {
@@ -323,12 +323,12 @@ async function compileFile(sourcePath, outputPath = null, options = {}) {
           cliLogger.clear();
         }
         console.error('⚠️  Build-time optimization failed:', error.message);
-        console.error('   Continuing without pre-computed embeddings...\n');
+        console.error('   Continuing without pre-generated descriptions...\n');
       }
     }
   } else {
     if (options.verbose) {
-      cliLogger.info('[Optimizer] Pre-calculation disabled. Runtime will generate embeddings dynamically.');
+      cliLogger.info('[Optimizer] Pre-generation disabled. Runtime will generate descriptions dynamically.');
     }
   }
 
@@ -347,7 +347,7 @@ async function compileFile(sourcePath, outputPath = null, options = {}) {
     }
 
     const basename = path.basename(sourcePath, '.koi');
-    outputPath = path.join(buildDir, basename + '.js');
+    outputPath = path.join(buildDir, basename + '.ts');
   }
 
   // Transpile with output path so it can calculate correct runtime import path
@@ -398,14 +398,16 @@ async function runFile(sourcePath, options = {}) {
   const verbose = options.verbose || false;
   const debug = options.debug || false;
 
-  // Show simple 1-line log if not verbose
+  // Show simple 1-line log if not verbose (cleared before child spawns)
   if (!verbose) {
-    console.log(`🌊 Running ${sourcePath}`);
+    process.stdout.write(`🌊 Running ${sourcePath}`);
   }
 
   // Compile first
   const jsPath = await compileFile(sourcePath, null, options);
 
+  // "🌊 Running" message stays on screen until child's first cliLogger.progress() clears it
+
   // Run
   if (verbose) {
     console.log(`🚀 Executing: ${jsPath}\n`);
@@ -416,15 +418,19 @@ async function runFile(sourcePath, options = {}) {
   // This ensures each run uses the freshly compiled code
   const { spawn } = await import('child_process');
 
-  // Prepare environment variables
+  // Prepare environment variables (pass COLUMNS so child knows terminal width)
   const env = { ...process.env };
+  if (process.stdout.columns) {
+    env.COLUMNS = String(process.stdout.columns);
+  }
   if (debug) {
     env.KOI_DEBUG_LLM = '1';
   }
 
-  const child = spawn('node', [jsPath], {
+  const child = spawn('npx', ['tsx', jsPath], {
     stdio: 'inherit',
-    env
+    env,
+    shell: true
   });
 
   return new Promise((resolve, reject) => {
@@ -489,7 +495,6 @@ async function initProject(projectName) {
 package "${projectName}"
 
 role Worker { can execute }
-role Lead { can delegate }
 
 // Agent with LLM playbook - generates creative greetings
 Agent Greeter : Worker {
@@ -505,28 +510,12 @@ Agent Greeter : Worker {
     - Add a motivational message or fun fact
     - Be brief (2-3 sentences)
 
-    Use the return action with your greeting data:
-    { "greeting": "your greeting here", "emoji": "an appropriate emoji" }
+    Return JSON: { "greeting": "your greeting here", "emoji": "an appropriate emoji" }
     """
   }
 }
 
-Team MainTeam {
-  greeter = Greeter
-}
-
-// Orchestrator coordinates with team members
-Agent Orchestrator : Lead {
-  uses Team MainTeam
-
-  on start(args: Json) {
-    const result = await send peers.event("greet").role(Worker).any()({ name: "World" }) timeout 30s
-    console.log("Greeting:", result.greeting, result.emoji)
-    return result
-  }
-}
-
-run Orchestrator.start({})
+run Greeter.greet({ name: "World" })
 `;
 
   fs.writeFileSync(path.join(projectPath, 'src', 'main.koi'), exampleCode);
@@ -602,7 +591,7 @@ Koi project - Agent-first language. Calm orchestration.
 .env
 dist/
 .build/
-.koi-cache/
+.koi/
 *.js.map
 .DS_Store
 `;