@koi-language/koi 1.0.0

package/examples/actions-demo.koi

@@ -0,0 +1,177 @@
+// ============================================================
+// Koi — Actions Demo
+// Demonstrates playbook-based action system:
+// - update_state: Modify agent state
+// - call_skill: Execute skills
+// - send_message: Send events to peers
+// - return: Return results
+// ============================================================
+
+package "demo.koi.actions"
+
+role Worker { can execute }
+role LoggerRole { can execute }
+
+Agent Logger : LoggerRole {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 150 }
+
+  state {
+    logCount: Int = 0
+  }
+
+  on log(args: Json) {
+    playbook """
+    You are a logger agent. Increment the log count and return confirmation.
+
+    Current logCount: ${state.logCount}
+    Message to log: ${JSON.stringify(args)}
+
+    Return this JSON with state_updates:
+    {
+      "state_updates": {
+        "logCount": [logCount + 1]
+      },
+      "logged": true,
+      "count": [new logCount]
+    }
+    """
+  }
+
+  on getLogs(args: Json) {
+    playbook """
+    Return the current log count.
+
+    Current logCount: ${state.logCount}
+
+    Return ONLY:
+    {
+      "count": ${state.logCount}
+    }
+    """
+  }
+}
+
+Agent TaskProcessor : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.2, max_tokens: 300 }
+
+  state {
+    tasksProcessed: Int = 0
+  }
+
+  on processTask(args: Json) {
+    playbook """
+    You are a task processing agent. Process the incoming task and execute actions.
+
+    Current state:
+    - tasksProcessed: ${state.tasksProcessed}
+
+    Incoming task: ${JSON.stringify(args)}
+
+    Your job is to plan and return a list of actions to:
+    1. Update the state (increment tasksProcessed)
+    2. Return the final result
+
+    Return ONLY this exact JSON structure (no markdown, no explanations):
+    {
+      "actions": [
+        {
+          "type": "update_state",
+          "updates": {
+            "tasksProcessed": [current tasksProcessed + 1]
+          }
+        },
+        {
+          "type": "return",
+          "data": {
+            "success": true,
+            "task": "[task description from args.task]",
+            "tasksProcessed": [new count]
+          }
+        }
+      ]
+    }
+
+    Example if args = {"task": "analyze data", "priority": "high"}:
+    {
+      "actions": [
+        {
+          "type": "update_state",
+          "updates": {
+            "tasksProcessed": 1
+          }
+        },
+        {
+          "type": "return",
+          "data": {
+            "success": true,
+            "task": "analyze data",
+            "tasksProcessed": 1
+          }
+        }
+      ]
+    }
+    """
+  }
+
+  on getStatus(args: Json) {
+    playbook """
+    Return the current status of the task processor.
+
+    Current state:
+    - tasksProcessed: ${state.tasksProcessed}
+
+    Return ONLY:
+    {
+      "tasksProcessed": ${state.tasksProcessed}
+    }
+    """
+  }
+}
+
+Team LoggingTeam {
+  logger = Logger
+  processor = TaskProcessor
+}
+
+Agent Orchestrator : Worker {
+  uses Team LoggingTeam
+
+  on start(args: Json) {
+    console.log("🎯 Actions Demo Starting...")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    // Process first task
+    console.log("\n📋 Processing Task 1: Analyze User Data")
+    const task1 =
+      await send peers.event("processTask").role(Worker).any()({
+        task: "analyze user data",
+        priority: "high"
+      }) timeout 15s
+    console.log("✓ Task 1 result:", task1)
+
+    // Process second task
+    console.log("\n📋 Processing Task 2: Generate Report")
+    const task2 =
+      await send peers.event("processTask").role(Worker).any()({
+        task: "generate monthly report",
+        priority: "medium"
+      }) timeout 15s
+    console.log("✓ Task 2 result:", task2)
+
+    // Get processor status
+    console.log("\n📊 Getting processor status...")
+    const status =
+      await send peers.event("getStatus").role(Worker).any()({}) timeout 10s
+    console.log("✓ Status:", status)
+
+    console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    return {
+      message: "Actions demo complete ✓",
+      summary: {
+        tasksProcessed: status.tasksProcessed
+      }
+    }
+  }
+}
+
+run Orchestrator.start({})

package/examples/cache-test.koi

@@ -0,0 +1,29 @@
+// 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

@@ -0,0 +1,61 @@
+// ============================================================
+// 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

@@ -0,0 +1,33 @@
+#!/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

@@ -0,0 +1,30 @@
+// 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

@@ -0,0 +1,149 @@
+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({})

package/examples/counter.koi

@@ -0,0 +1,132 @@
+// ============================================================
+// Koi — Counter Example
+// Simple stateful agent that counts using playbooks
+// ============================================================
+
+package "demo.koi.counter"
+
+role Worker { can execute }
+
+Agent Counter : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
+
+  state {
+    count: Int = 0
+  }
+
+  on increment(args: Json) {
+    playbook """
+    You are a counter agent. Increment the internal counter by 1 and return the new value.
+
+    Current state: state.count = ${state.count}
+
+    Your task:
+    1. Calculate the new count by adding 1 to the current count
+    2. Return a JSON response with BOTH the result AND the state update
+
+    Return ONLY this exact JSON structure (no markdown, no explanations):
+    {
+      "state_updates": {
+        "count": [new count value after incrementing]
+      },
+      "count": [new count value after incrementing]
+    }
+
+    Example: If current count is 5, return:
+    {
+      "state_updates": { "count": 6 },
+      "count": 6
+    }
+    """
+  }
+
+  on get(args: Json) {
+    playbook """
+    You are a counter agent. Return the current counter value without modifying it.
+
+    Current state: state.count = ${state.count}
+
+    Return ONLY this exact JSON structure (no markdown, no explanations):
+    {
+      "count": ${state.count}
+    }
+    """
+  }
+
+  on reset(args: Json) {
+    playbook """
+    You are a counter agent. Reset the counter to zero.
+
+    Current state: state.count = ${state.count}
+
+    Your task:
+    1. Reset the counter to 0
+    2. Return a JSON response with BOTH the result AND the state update
+
+    Return ONLY this exact JSON structure (no markdown, no explanations):
+    {
+      "state_updates": {
+        "count": 0
+      },
+      "count": 0
+    }
+    """
+  }
+
+  on incrementBy(args: Json) {
+    playbook """
+    You are a counter agent. Increment the counter by a specific amount.
+
+    Current state: state.count = ${state.count}
+    Amount to increment: args.amount = ${args.amount || 1}
+
+    Your task:
+    1. Calculate the new count by adding args.amount to the current count
+    2. Return a JSON response with BOTH the result AND the state update
+
+    Return ONLY this exact JSON structure (no markdown, no explanations):
+    {
+      "state_updates": {
+        "count": [new count value]
+      },
+      "count": [new count value],
+      "incremented": [amount that was added]
+    }
+    """
+  }
+}
+
+Team CounterTeam {
+  counter = Counter
+}
+
+Agent Orchestrator : Worker {
+  uses Team CounterTeam
+
+  on start(args: Json) {
+    console.log("🔢 Counter Test Starting...")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    const r1 =
+      await send peers.event("increment").role(Worker).any()({}) timeout 5s
+    console.log("✓ After increment 1:", r1)
+
+    const r2 =
+      await send peers.event("increment").role(Worker).any()({}) timeout 5s
+    console.log("✓ After increment 2:", r2)
+
+    const r3 =
+      await send peers.event("increment").role(Worker).any()({}) timeout 5s
+    console.log("✓ After increment 3:", r3)
+
+    const current =
+      await send peers.event("get").role(Worker).any()({}) timeout 5s
+    console.log("✓ Current value:", current)
+
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+
+    return { message: "Counter test complete ✓", final: current }
+  }
+}
+
+run Orchestrator.start({})

package/examples/delegation-test.koi

@@ -0,0 +1,52 @@
+package "test.delegation"
+
+role Worker { can execute }
+
+// Simple translator agent
+Agent Translator : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  on translate(args: Json) {
+    playbook """
+    Translate "${args.text}" to ${args.language}.
+    Return JSON: { "translated": "translated text here" }
+    """
+  }
+}
+
+// Simple counter agent
+Agent WordCounter : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  on count(args: Json) {
+    playbook """
+    Count words in: "${args.text}"
+    Return JSON: { "wordCount": number }
+    """
+  }
+}
+
+// Orchestrator that chains tasks
+Agent Orchestrator : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  on processText(args: Json) {
+    playbook """
+    Task: Translate "${args.text}" to Spanish, then count the words.
+
+    Create a plan with 2 actions:
+    1. Translate the text to Spanish
+    2. Count the words in the translation
+
+    Return JSON with actions array:
+    {
+      "actions": [
+        { "intent": "translate to spanish", "data": { "text": "${args.text}", "language": "spanish" } },
+        { "intent": "count words", "data": { "text": "\${previousResult.translated}" } }
+      ]
+    }
+    """
+  }
+}
+
+run Orchestrator.processText({ text: "hello world" })