@koi-language/koi 1.0.0

package/examples/test-permissions-fail.koi

@@ -0,0 +1,20 @@
+// Test that permissions are enforced
+package "test.permissions.fail"
+
+// Role without execute permission
+role ReadOnly { can registry_read }
+
+// Agent without execute permission - should fail when trying to print
+Agent ReadOnlyAgent : ReadOnly {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  on test(args: Json) {
+    playbook """
+    Try to print a message (should fail due to missing execute permission).
+
+    Show: "❌ This should not appear because print requires execute permission"
+    """
+  }
+}
+
+run ReadOnlyAgent.test({})

package/examples/test-permissions.koi

@@ -0,0 +1,36 @@
+// Test permissions system
+package "test.permissions"
+
+// Role with execute permission
+role Worker { can execute }
+
+// Role without execute permission (empty)
+role ReadOnly { can registry_read }
+
+// Agent with execute permission - should work
+Agent TestAgent : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  on test(args: Json) {
+    playbook """
+    Print a simple message to test permissions.
+
+    Show: "✅ Print action works with execute permission"
+    """
+  }
+}
+
+// Agent without execute permission - should fail
+Agent ReadOnlyAgent : ReadOnly {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  on test(args: Json) {
+    playbook """
+    Try to print a message (should fail due to missing execute permission).
+
+    Show: "❌ This should not appear"
+    """
+  }
+}
+
+run TestAgent.test({})

package/examples/test-simple-registry.koi

@@ -0,0 +1,31 @@
+// Simple test for registry operations
+package "test.simple"
+
+role Worker { can execute }
+
+Agent SimpleWorker : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini" }
+
+  on saveUser(args: Json) {
+    playbook """
+    Save a user to the registry with key "user:${args.id}" and value:
+    {
+      "name": "${args.name}",
+      "age": ${args.age},
+      "createdAt": "${Date.now()}"
+    }
+
+    Return: { "success": true, "message": "User saved" }
+    """
+  }
+
+  on getUser(args: Json) {
+    playbook """
+    Get the user from registry with key "user:${args.id}".
+    If found, return: { "found": true, "user": [the complete user object] }
+    If not found, return: { "found": false }
+    """
+  }
+}
+
+run SimpleWorker.saveUser({ id: "test1", name: "TestUser", age: 25 })

package/examples/test-typescript-import.koi

@@ -0,0 +1,64 @@
+package "test.typescript.import"
+
+// Import TypeScript module
+import "./utils/math-helpers.ts"
+
+role Worker { can work }
+
+Agent MathAgent : Worker {
+  on calculate(args: Json) {
+    console.log("=".repeat(60))
+    console.log("Testing TypeScript Import")
+    console.log("=".repeat(60))
+
+    // Test simple functions
+    const sum = utils_math_helpers.add(5, 3)
+    console.log("\nTest 1: add(5, 3) =", sum)
+
+    const product = utils_math_helpers.multiply(4, 7)
+    console.log("Test 2: multiply(4, 7) =", product)
+
+    const fib10 = utils_math_helpers.fibonacci(10)
+    console.log("Test 3: fibonacci(10) =", fib10)
+
+    const is17Prime = utils_math_helpers.isPrime(17)
+    console.log("Test 4: isPrime(17) =", is17Prime)
+
+    // Test constants
+    console.log("\nTest 5: PI =", utils_math_helpers.PI)
+    console.log("Test 6: E =", utils_math_helpers.E)
+
+    // Test class instantiation
+    const calc = new utils_math_helpers.Calculator()
+    const r1 = calc.add(10, 20)
+    const r2 = calc.subtract(50, 15)
+    console.log("\nTest 7: Calculator.add(10, 20) =", r1)
+    console.log("Test 8: Calculator.subtract(50, 15) =", r2)
+
+    const history = calc.getHistory()
+    console.log("Test 9: Calculator history:", JSON.stringify(history))
+
+    console.log("\n" + "=".repeat(60))
+    console.log("All tests completed!")
+    console.log("=".repeat(60))
+
+    return {
+      success: true,
+      tests: {
+        add: sum,
+        multiply: product,
+        fibonacci: fib10,
+        isPrime: is17Prime,
+        pi: utils_math_helpers.PI,
+        e: utils_math_helpers.E,
+        calculator: {
+          add: r1,
+          subtract: r2,
+          history: history
+        }
+      }
+    }
+  }
+}
+
+run MathAgent.calculate({})

package/examples/test-uses-team-syntax.koi

@@ -0,0 +1,25 @@
+package "test.uses.team"
+
+role Worker { can work }
+
+Agent TestAgent : Worker {
+  on work(args: Json) {
+    return { result: "working" }
+  }
+}
+
+Team TestTeam {
+  worker = TestAgent
+}
+
+Agent MainAgent : Worker {
+  // Esta sintaxis SÍ debe funcionar
+  uses Team TestTeam
+
+  on start(args: Json) {
+    const result = await send peers.event("work").role(Worker).any()({}) timeout 5s
+    return result
+  }
+}
+
+run MainAgent.start({})

package/examples/test-uses-team.koi

@@ -0,0 +1,31 @@
+package "test.uses.team"
+
+role Worker { can execute }
+role Manager { can manage }
+
+Agent SimpleWorker : Worker {
+  on doWork(args: Json) {
+    playbook """
+    Do some work: ${args.task}
+    Return JSON: { "result": "work done" }
+    """
+  }
+}
+
+Team SimpleTeam {
+  worker = SimpleWorker
+}
+
+Agent TeamUser : Manager {
+  uses Team SimpleTeam
+
+  on requestWork(args: Json) {
+    playbook """
+    Request work from team: ${args.request}
+    Return JSON with actions:
+    { "actions": [{ "intent": "do work", "data": { "task": "${args.request}" } }] }
+    """
+  }
+}
+
+run TeamUser.requestWork({ request: "process data" })

package/examples/utils/calculator.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Unit tests for Calculator module using Jest
+ */
+
+import { Calculator, factorial, isPrime } from './calculator';
+
+describe('Calculator', () => {
+  let calc: Calculator;
+
+  beforeEach(() => {
+    calc = new Calculator();
+  });
+
+  describe('add', () => {
+    test('should add two positive numbers', () => {
+      expect(calc.add(2, 3)).toBe(5);
+    });
+
+    test('should add negative numbers', () => {
+      expect(calc.add(-5, -3)).toBe(-8);
+    });
+
+    test('should add zero', () => {
+      expect(calc.add(5, 0)).toBe(5);
+    });
+  });
+
+  describe('subtract', () => {
+    test('should subtract two numbers', () => {
+      expect(calc.subtract(10, 4)).toBe(6);
+    });
+
+    test('should handle negative results', () => {
+      expect(calc.subtract(5, 10)).toBe(-5);
+    });
+  });
+
+  describe('multiply', () => {
+    test('should multiply two numbers', () => {
+      expect(calc.multiply(4, 5)).toBe(20);
+    });
+
+    test('should return zero when multiplying by zero', () => {
+      expect(calc.multiply(100, 0)).toBe(0);
+    });
+
+    test('should handle negative numbers', () => {
+      expect(calc.multiply(-3, 4)).toBe(-12);
+    });
+  });
+
+  describe('divide', () => {
+    test('should divide two numbers', () => {
+      expect(calc.divide(10, 2)).toBe(5);
+    });
+
+    test('should handle decimal results', () => {
+      expect(calc.divide(7, 2)).toBe(3.5);
+    });
+
+    test('should throw error on division by zero', () => {
+      expect(() => calc.divide(10, 0)).toThrow('Division by zero');
+    });
+  });
+
+  describe('power', () => {
+    test('should calculate power correctly', () => {
+      expect(calc.power(2, 3)).toBe(8);
+    });
+
+    test('should handle exponent of zero', () => {
+      expect(calc.power(5, 0)).toBe(1);
+    });
+
+    test('should handle negative exponents', () => {
+      expect(calc.power(2, -2)).toBe(0.25);
+    });
+  });
+
+  describe('percentage', () => {
+    test('should calculate percentage correctly', () => {
+      expect(calc.percentage(100, 10)).toBe(10);
+    });
+
+    test('should handle decimal percentages', () => {
+      expect(calc.percentage(200, 2.5)).toBe(5);
+    });
+  });
+});
+
+describe('factorial', () => {
+  test('should calculate factorial of 0', () => {
+    expect(factorial(0)).toBe(1);
+  });
+
+  test('should calculate factorial of 1', () => {
+    expect(factorial(1)).toBe(1);
+  });
+
+  test('should calculate factorial of 5', () => {
+    expect(factorial(5)).toBe(120);
+  });
+
+  test('should calculate factorial of 10', () => {
+    expect(factorial(10)).toBe(3628800);
+  });
+
+  test('should throw error for negative numbers', () => {
+    expect(() => factorial(-1)).toThrow('Factorial is not defined for negative numbers');
+  });
+});
+
+describe('isPrime', () => {
+  test('should return false for numbers less than 2', () => {
+    expect(isPrime(0)).toBe(false);
+    expect(isPrime(1)).toBe(false);
+    expect(isPrime(-5)).toBe(false);
+  });
+
+  test('should return true for prime numbers', () => {
+    expect(isPrime(2)).toBe(true);
+    expect(isPrime(3)).toBe(true);
+    expect(isPrime(5)).toBe(true);
+    expect(isPrime(7)).toBe(true);
+    expect(isPrime(11)).toBe(true);
+    expect(isPrime(17)).toBe(true);
+    expect(isPrime(19)).toBe(true);
+  });
+
+  test('should return false for composite numbers', () => {
+    expect(isPrime(4)).toBe(false);
+    expect(isPrime(6)).toBe(false);
+    expect(isPrime(8)).toBe(false);
+    expect(isPrime(9)).toBe(false);
+    expect(isPrime(10)).toBe(false);
+    expect(isPrime(15)).toBe(false);
+    expect(isPrime(21)).toBe(false);
+  });
+
+  test('should handle large primes', () => {
+    expect(isPrime(97)).toBe(true);
+    expect(isPrime(100)).toBe(false);
+  });
+});

package/examples/utils/calculator.ts

@@ -0,0 +1,56 @@
+/**
+ * Calculator module to demonstrate unit testing in Koi
+ */
+
+export class Calculator {
+  add(a: number, b: number): number {
+    return a + b;
+  }
+
+  subtract(a: number, b: number): number {
+    return a - b;
+  }
+
+  multiply(a: number, b: number): number {
+    return a * b;
+  }
+
+  divide(a: number, b: number): number {
+    if (b === 0) {
+      throw new Error('Division by zero');
+    }
+    return a / b;
+  }
+
+  power(base: number, exponent: number): number {
+    return Math.pow(base, exponent);
+  }
+
+  percentage(value: number, percent: number): number {
+    return (value * percent) / 100;
+  }
+}
+
+export function factorial(n: number): number {
+  if (n < 0) {
+    throw new Error('Factorial is not defined for negative numbers');
+  }
+  if (n === 0 || n === 1) {
+    return 1;
+  }
+  return n * factorial(n - 1);
+}
+
+export function isPrime(n: number): boolean {
+  if (n <= 1) return false;
+  if (n <= 3) return true;
+  if (n % 2 === 0 || n % 3 === 0) return false;
+
+  for (let i = 5; i * i <= n; i += 6) {
+    if (n % i === 0 || n % (i + 2) === 0) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/examples/utils/math-helpers.js

@@ -0,0 +1,50 @@
+/**
+ * Math helper utilities (TypeScript module)
+ */
+export function add(a, b) {
+    return a + b;
+}
+export function multiply(a, b) {
+    return a * b;
+}
+export function fibonacci(n) {
+    if (n <= 1)
+        return n;
+    return fibonacci(n - 1) + fibonacci(n - 2);
+}
+export function isPrime(n) {
+    if (n <= 1)
+        return false;
+    if (n <= 3)
+        return true;
+    if (n % 2 === 0 || n % 3 === 0)
+        return false;
+    for (let i = 5; i * i <= n; i += 6) {
+        if (n % i === 0 || n % (i + 2) === 0)
+            return false;
+    }
+    return true;
+}
+export class Calculator {
+    constructor() {
+        this.history = [];
+    }
+    add(a, b) {
+        const result = a + b;
+        this.history.push(`${a} + ${b} = ${result}`);
+        return result;
+    }
+    subtract(a, b) {
+        const result = a - b;
+        this.history.push(`${a} - ${b} = ${result}`);
+        return result;
+    }
+    getHistory() {
+        return [...this.history];
+    }
+    clearHistory() {
+        this.history = [];
+    }
+}
+export const PI = 3.141592653589793;
+export const E = 2.718281828459045;

package/examples/utils/math-helpers.ts

@@ -0,0 +1,55 @@
+/**
+ * Math helper utilities (TypeScript module)
+ */
+
+export function add(a: number, b: number): number {
+  return a + b;
+}
+
+export function multiply(a: number, b: number): number {
+  return a * b;
+}
+
+export function fibonacci(n: number): number {
+  if (n <= 1) return n;
+  return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+export function isPrime(n: number): boolean {
+  if (n <= 1) return false;
+  if (n <= 3) return true;
+  if (n % 2 === 0 || n % 3 === 0) return false;
+
+  for (let i = 5; i * i <= n; i += 6) {
+    if (n % i === 0 || n % (i + 2) === 0) return false;
+  }
+
+  return true;
+}
+
+export class Calculator {
+  private history: string[] = [];
+
+  add(a: number, b: number): number {
+    const result = a + b;
+    this.history.push(`${a} + ${b} = ${result}`);
+    return result;
+  }
+
+  subtract(a: number, b: number): number {
+    const result = a - b;
+    this.history.push(`${a} - ${b} = ${result}`);
+    return result;
+  }
+
+  getHistory(): string[] {
+    return [...this.history];
+  }
+
+  clearHistory(): void {
+    this.history = [];
+  }
+}
+
+export const PI = 3.141592653589793;
+export const E = 2.718281828459045;

package/examples/web-delegation-demo.koi

@@ -0,0 +1,165 @@
+// ============================================================
+// Web Delegation Demo
+// Demonstrates delegation with indentation and loop detection
+// ============================================================
+
+package "demo.koi.delegation"
+
+role Worker { can execute }
+role Assistant { can help }
+
+// ============================================================
+// Skills - JavaScript functions agents can use
+// ============================================================
+
+Skill WebFetching {
+  affordance """
+  Fetch content from web URLs
+  """
+
+  export async function fetchUrl(args: any): Promise<any> {
+    const url = args.url;
+    console.log("[fetchUrl] Fetching: " + url);
+
+    try {
+      const response = await fetch(url, {
+        headers: {
+          "User-Agent": "Mozilla/5.0 (compatible; KoiBot/1.0)"
+        }
+      });
+
+      if (!response.ok) {
+        return {
+          url: url,
+          content: "Failed to fetch: " + response.status + " " + response.statusText,
+          status: "error",
+          error: true
+        };
+      }
+
+      const html = await response.text();
+      return {
+        url: url,
+        content: html,
+        status: "success",
+        length: html.length
+      };
+    } catch (error) {
+      console.error("[fetchUrl] Error:", error.message);
+      return {
+        url: url,
+        content: "Error fetching page: " + error.message,
+        status: "error",
+        error: true
+      };
+    }
+  }
+}
+
+// ============================================================
+// Worker Agents with Specialized Capabilities
+// ============================================================
+
+Agent WebFetcher : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.2, max_tokens: 500 }
+  uses Skill WebFetching
+
+  on fetchWebPage(args: Json) {
+    playbook """
+    Download the web page from this URL: ${JSON.stringify(args.url)}
+
+    Use the available fetchUrl tool to download the content, then return the result.
+    """
+  }
+}
+
+Agent ContentSummarizer : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.3, max_tokens: 300 }
+
+  on summarize(args: Json) {
+    playbook """
+    Summarize the following content in 1-2 sentences:
+    ${JSON.stringify(args.content || args.text)}
+
+    Return your summary as JSON with a "summary" field containing the text.
+    """
+  }
+}
+
+Agent WordCounter : Worker {
+  llm default = { provider: "openai", model: "gpt-4o-mini", temperature: 0.1, max_tokens: 200 }
+
+  on count(args: Json) {
+    playbook """
+    Count the number of words in this text: ${JSON.stringify(args.text || args.summary)}
+
+    Return JSON with "wordCount" field containing the number of words.
+    """
+  }
+}
+
+// ============================================================
+// Orchestrator Agent
+// ============================================================
+
+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!!!!
+  on processWebTask(args: Json) {
+    playbook """
+    User request: ${args.request}
+
+    You MUST execute the user request and return the result as JSON. Print also the plan you followed to execute the request.
+    """
+  }
+}
+
+// ============================================================
+// Team
+// ============================================================
+
+Team WorkerTeam {
+  orchestrator = TaskOrchestrator
+  webFetcher = WebFetcher
+  summarizer = ContentSummarizer
+  counter = WordCounter
+}
+
+// ============================================================
+// Demo Runner
+// ============================================================
+
+Agent DemoRunner : Assistant {
+  uses Team WorkerTeam
+
+  on runDemo(args: Json) {
+    console.log("╔════════════════════════════════════════════╗")
+    console.log("║  Web Delegation Demo                       ║")
+    console.log("║  Indented Delegation + Loop Detection      ║")
+    console.log("╚════════════════════════════════════════════╝\n")
+
+    // ============================================================
+    // Test 1: Web → Summarize → Count (requires delegation)
+    // ============================================================
+    console.log("📋 Test 1: Fetch Web → Summarize → Count Words")
+    console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
+    console.log('Request: "Fetch web content, summarize it, then count the words in the summary"\n')
+
+    const test1 = await send peers.event("processWebTask").role(Assistant).any()({
+      request: "Fetch web content, summarize it, then count the words in the summary",
+      url: "https://soloprogramadores.com",
+      topic: "artificial intelligence"
+    }) timeout 60s
+
+    console.log("✅ Final Result:")
+    console.log(JSON.stringify(test1, null, 2))
+
+    return {
+      success: true,
+      tests_completed: 1
+    }
+  }
+}
+
+run DemoRunner.runDemo({})